Koha SIP2 server setup
Koha uses SIPServer implementation (also used by OpenILS-Evergreen) available at https://github.com/atz/SIPServer
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.
- https://web.archive.org/web/20190712041755/https://multimedia.3m.com/mws/media/355361O/sip2-protocol.pdf
- rsyslog documentation
- Net::Server::PreFork from cpan;
- logrotate
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.
In more recent versions these commands have been replaced by a single command that takes different arguments:
- koha-sip --enable <instance>
- koha-sip --start <instance>
- koha-sip --status <instance>
- koha-sip --stop <instance>
- koha-sip --disable <instance>
"man koha-sip" gives more details.
SIPconfig.xml
SIP server configuration file is stored in etc/ . To find location on your installation use something like:
find /etc/koha -name "SIPconfig.xml"
or use locate SIPconfig if you are running updatedb.
See SIP2 configuration for details of the configuration.
start server
dpavlin@koha-dev:/srv/koha$ sudo koha-start-sip <instancename>
After you started server see Setting up Koha SIP and 3M machines
syslog
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
rsyslog
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:
<server-params ... ... log_file='Sys::Syslog' syslog_ident='koha_sip' syslog_facility='local6' />
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:
from ... auth,authpriv.* /var/log/auth.log *.*;auth,authpriv.none -/var/log/syslog ... to ... 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.
testing
Koha SIP CLI emulator
Koha has its own ./misc/sip_cli_emulator.pl
Usage:
sip_cli_emulator.pl [OPTIONS]
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:
patron_status_request
patron_information
item_information
checkout
checkin
renew
Example
./misc/sip_cli_emulator.pl -a 127.0.0.1 -p 6001 -su term1 -sp term1 \
-l CPL --patron 23529001000463 -m checkout --item 39999000001259
translation: via the koha user term1 at the library CPL, checkout item 39999000001259 to patron 23529001000463
3M SIP emulator
It's possible to test SIP server using 3M SIP emulator which is proprietary 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] com_type = sockets [TCP/IP] ip_address = 127.0.0.1 host_name = tcp_port = 6001
and change 127.0.0.1 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
dir=/virtual/win/3M
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
fi
echo "Using SIP2 server $ip $port"
wine $dir/SIP2/Program/SCEmul.exe
SIP-in-the-middle
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.,
$ sudo koha-shell [instance name] $ perl C4/SIP/SIPServer.pm /etc/koha/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
9300CNterm1|COterm1|CPCPL|
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
Testing with openssl s_client
When testing that your stunnel configuration is correct, you need to test a SIP2 connection over TLS. For this, you can't use telnet or Koha's CLI emulator. You can use openssl's s_client though!
Press enter after each of the following commands:
openssl s_client -crlf -connect <IP address or DNS name>:<SIP2 port>
9300CNterm1|COterm1|CPCPL|
The expected response is '941'
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
SIP commands
Checkout items
NOTE: This section is a work in progress.
11<self check renewal policy><whether block><date of transaction><due date><id of institution><patron id> <item id><password of terminal><patrons password><<[optional]item properties><fee acknowledged><cancel>
e.g. 11YY20171211ZZZZ01121220171221ZZZZ011212CPL5121passwordsecretY