Koha SIP2 server setup

From Koha Wiki

Jump to: navigation, search
Home > Documentation > Library System Modules > Circulation

Koha uses SIPServer implementation (also used by OpenILS-Evergreen) available at https://github.com/atz/SIPServer


Koha SIP2 Server Capabilities

Koha SIP2 Server Capabilities

Things good to know before starting working with Koha's SIP server

It is possible to install and deploy the SIP server without researching the following topics, but to succeed better in the long term, the following topics are recommended to be absorbed.

Package installations

Installations made with the Debian packages have special commands available for enabling SIP2:

  • koha-enable-sip
  • koha-start-sip
  • koha-stop-sip

Please use e.g. "man koha-enable-sip" for help on how these commands are used.


SIP server configuration file is stored in etc/ . To find location on your installation use something like:

find /etc/koha -name "SIPconfig.xml"

Create self-check account, one for each self-check station

     <login id="sc1"  password="**password**" delimiter="|" error-detect="enabled" institution="FFZG" />

Then create patrons inside Koha for each account you made, with same logins and passwords and homebranches. Give them basic circulation permissions. The Level1 permission, "circulate" must be active. It is handy to create a separate patron category, "automate" or "self-check machine", or whatever suits your conventions, but this is not mandatory.

Finally, institution entries

   <institution id="FFZG" implementation="ILS" parms="">
         <policy checkin="true" renewal="true" checkout="true"
                 status_update="false" offline="false"
                 retries="5" />

[N.B. The institution in both the 'accounts' and 'institutions' element should match the 'branchcode' of the library that you are seeking to use.]

start server

dpavlin@koha-dev:/srv/koha$ sudo koha-start-sip <instancename>

After you started server see Setting up Koha SIP and 3M machines


You can change syslog level6 directly in source code:

dpavlin@koha-dev:/srv/koha$ grep LOG_SIP C4/SIP/SIPServer.pm
use constant LOG_SIP => "local6"; # Local alias for the logging facility

To redirect output in individual file add following to /etc/syslog.conf

local6.*        -/var/log/sip2.log


If you are using rsyslogd (replaces syslog with Ubuntu 12.04 and later), I managed to get the SIP server to log using the following instructions:

1. Set the SIP server logging directives.

 In the SIPconfig.xml, modify the server-params-block to this:

As SIPServer.pm subclasses Net::Server::PreFork you can see the Net::Server manual what the configuration instructions do.

2. Configure rsyslog. Write koha.conf to /etc/rsyslog.d/koha.conf, looking like this:

 local6.*        /home/koha/koha-dev/var/log/sip2.log

Then run the following console commands to prepare the log file:

 touch /home/koha/koha-dev/var/log/sip2.log
 chown syslog:adm /home/koha/koha-dev/var/log/sip2.log

Modify /etc/rsyslog.d/50-default.conf. Find the following block and make the following change, to prevent sip2 logging to syslog:

 auth,authpriv.*                 /var/log/auth.log
 *.*;auth,authpriv.none           -/var/log/syslog
 auth,authpriv.*                 /var/log/auth.log
 *.*;auth,authpriv,local6.none           -/var/log/syslog

Finally restart the SIP server.

Logging for the SIP server is really shrapnelled, but this removes the /var/log/syslog from the list of log files Koha's SIP server uses.


Koha SIP CLI emulator

Koha has its own ./misc/sip_cli_emulator.pl

     sip_cli_emulator.pl [OPTIONS]
     --help           display help message
     -a --address     SIP server ip address or host name
     -p --port        SIP server port
     -su --sip_user   SIP server login username
     -sp --sip_pass   SIP server login password

     -l --location    SIP location code
     --patron         ILS patron cardnumber or username
     --password       ILS patron password
     -s --summary     Optionally define the patron information request summary field.
                      Please refer to the SIP2 protocol specification for details
     --item           ILS item identifier ( item barcode )
     -t --terminator  SIP2 message terminator, either CR, or CRLF
                      (defaults to CRLF)
     -fa --fee-acknowledged Sends a confirmation of checkout fee
     -m --message     SIP2 message to execute

     Implemented Messages:

3M SIP emulator

It's possible to test SIP server using 3M SIP emulator which is propitiatory software available from 3M and runs under Microsoft Windows (which also works on Linux using wine with SCEmul.exe).

To configure emulator, edit C:\Program Files\3M Library Systems\3M SIP2 Development Kit\SC_Emulator Settings.sc

com_type = sockets

ip_address =
host_name =
tcp_port = 6001

and change to IP address of your SIP server.

SCEmul.exe is somewhat picky about socket connection. When in fails for first time you have to restart it to make it talk to SIP server again. To overcome this, following small shell script first checks if SIP server is running and then starts emulator using wine:

#!/bin/sh -x


ip=`grep ip_address $dir/SIP2/SC_Emulator/Settings.sc | sed 's/^.*= *\([0-9\.]*\).*$/\1/'`
port=`grep tcp_port $dir/SIP2/SC_Emulator/Settings.sc | sed 's/^.*= *\([0-9]*\).*$/\1/'`

if ! echo '9300CNfake-user|COfake-password|' | nc -w 1 $ip $port ; then
        echo "Can't connect to $ip $port"
        exit 1

echo "Using SIP2 server $ip $port"

wine $dir/SIP2/Program/SCEmul.exe


Another alternative is to run acs-proxy.pl from https://github.com/dpavlin/Biblio-SIP2 to record communication between Koha's SIP server and self-check station which should point to newly started proxy server.

After collecting protocol chatter, test script can be written similar to example sc-emulator.pl

Testing with Telnet

Instructions on how to test:

This assumes using stock Koha and an unmodified SIPconfig.xml.

  • Add a staff user whose username and barcode are 'term1' and whose password is 'term1'. Give it the 'circulate' permission.
  • Fire up the SIPServer. E.g.,
$ perl C4/SIP/SIPServer.pm C4/SIP/SIPconfig.xml &
  • Use telnet to open a SIP connection:
$ telnet localhost 6001

(Further interaction is assumed to be in the context of the telnet session. Use Ctrl-] to close the connection when you're done).

  • Try logging into the terminal

The expected response is '941'

  • Enter a patron information request:
6300020060329    201700Y         AOCPL|AAterm1|ACterm1|ADterm1|

Response should be something like:

64              00020120104    171118000000000000000000000000AOCPL|AAterm1|AEterm1|BLY|CQY|CC1|PCS|PIY|AFGreetings from Koha. |

You can test more by sending more commands via telnet

SIP Testing Tool by CLC (Ohio)

Central Library Consortium (CLC) developed a SIP testing tool and released it in 2013 under the GPLv3 license. The tool acts as a SIP client showing the messages passed between client and server. http://www.clcohio.org/sip-testing-tool

More resources

A great resource for different SIP transactions and how to test them: http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-admin:sip_support

Personal tools