SIP2 is the protocol self-service library hardware speaks, and Koha ships a SIP2 server you enable and configure. Get it right and a self-check unit issues books without staff involvement. Get it wrong and the unit reports "system unavailable" while Koha itself works perfectly.
What SIP2 is and why Koha needs it
Standard Interchange Protocol version 2 dates from the 1990s and is plain text over a TCP socket. It is old and it is universal — practically every self-check machine, sorter and library payment kiosk speaks it, which is exactly why it still matters. It is also how RFID middleware talks to Koha, since Koha has no RFID support of its own.
A device sends a message ("patron 12345 wants item 67890"), Koha applies its circulation rules and replies. The device never touches the database.
What you can connect over SIP2
| Device | What it does over SIP2 |
|---|---|
| Self-check kiosk | Patron lookup, checkout, renewal, fine display |
| Self-return / book drop | Check-in, receipt |
| Automated sorter | Check-in plus routing by destination branch |
| Payment kiosk | Fine lookup and payment posting |
| Security gate | Usually item status only, if anything |
| Third-party discovery | Patron authentication, account display |
Enabling the Koha SIP2 server
The SIP2 server is a separate daemon from the web application, with its own configuration file and its own service. This separation is the source of the most common complaint: everything worked, the server rebooted, and now the self-check is dead — because the daemon was started by hand and never enabled to start at boot.
Enable it as a service, and verify after a reboot rather than assuming.
Configuring SIP2 accounts
Each device authenticates with a login defined in the SIP configuration, tied to a Koha staff account whose permissions determine what the device may do — typically circulate, and nothing more.
Give every device its own account. A shared account across six kiosks makes troubleshooting nearly impossible: the logs cannot tell you which machine misbehaved, and disabling one device means disabling all of them. Per-device accounts cost nothing and repay themselves the first time something goes wrong.
The configuration file explained
The SIP configuration defines the listening port and format, one or more institutions mapped to Koha branches, and per-login account settings. The account settings control what the device is allowed to do — checkout, checkin, renewal — and how fees and messages are presented.
Two details worth getting right: the institution must map to the correct branch, or items check in to the wrong place; and terminal messages are what patrons actually read at the kiosk, so review the wording.
Testing your SIP2 connection
Test before the hardware vendor arrives on site. Because SIP2 is plain text over TCP, you can connect with a basic network client and send a login message by hand.
Establish, in order: the port is reachable from the device's network; the login is accepted; a patron lookup returns the right patron; a test checkout succeeds and appears in Koha.
Confirming all four before installation day turns a frustrating afternoon into a ten-minute job.
Security considerations
SIP2 is unencrypted plain text. Patron barcodes and, depending on configuration, passwords cross the network in the clear.
- Never expose the SIP2 port to the internet. Not behind a password, not on a non-standard port. Never.
- Keep it on a private network segment or VPN.
- Restrict by source IP so only your devices can connect.
- One account per device, with the minimum permissions needed.
- Consider a stunnel or SSH tunnel for traffic crossing untrusted links.
This is not optional hardening. An exposed SIP2 port is an unauthenticated read of your patron database.
Common SIP2 problems and fixes
- Connection refused — daemon not running, or firewall. Check the service first.
- Login rejected — credentials mismatch between device and config, or the linked Koha account is disabled.
- Patron not found — the device is sending a barcode in a different format, or with a prefix.
- Checkout silently fails — usually a circulation rule blocking it. Test the same transaction at a staff desk; the reason will be visible there.
- Fines not showing on the kiosk — fee display not enabled for that account.
- Works until reboot — service not enabled at boot. The classic.
- Items check in to the wrong branch — institution-to-branch mapping.
SIP2 versus the Koha REST API
SIP2 for hardware — it is what the devices speak, and you do not get to choose. The REST API for software integrations you are writing yourself: modern, authenticated, encrypted, and far more capable.
Alternatives to self-check hardware
Self-check units are a significant purchase per station. Before committing, it is worth knowing there is a cheaper route to the same staff-time saving.
Circulation from a phone, where every field has a camera scan button and a quick-submit mode scans and submits in one motion, needs no kiosk, no tethered scanner and no SIP2 daemon of your own to keep alive. For a small or mid-size library that is often the better purchase — see running circulation from a phone.
And where a library already owns self-check hardware, SIP2 is precisely what keeps that investment working, so the two are not exclusive.
On Koha Cloud the SIP2 side is configured and kept running for you — the library never touches the daemon, the firewall rules or the server it lives on. We handle the server side.
Connecting self-check hardware to Koha? Tell us what units you have and we will configure and test SIP2 for each of them — securely, with per-device accounts.