Koha SIP2 server setup

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.
* 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.
== Troubleshooting ==
=== Microsoft Azure cloud platform ===
If you're running a SIP2 server on Microsoft Azure, you may notice that your SIP2 clients are timing out intermittently. This is probably due to Azure having a 4 minute TCP idle timeout (https://learn.microsoft.com/en-us/azure/firewall/long-running-sessions). If a SIP2 connection (ie a TCP connection) is idle for more than 4 minutes, it will be silently dropped. This leads to mysterious timeouts on both the client and server side.
A solution is available at https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=37087
== 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 
Category:Circulation Category:SIP2