Koha SIP2 server setup

From Koha Wiki
Jump to navigation Jump to search

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.

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

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Koha_SIP2_server_setup&oldid=34202"