wiki:sysadminSIPServerConfiguration

Version 6 (modified by risard, 13 years ago) (diff)

--

SIP

Overview

Installing

Configuring the server

Adding SIP users

Running the server

Stopping the server

QuickStart?

Overview

SIP - Standard Interchange Protocol was developed by 3M to provide a way for self-check terminals to interact with ILS systems. It's important not to confuse this with the Session Initiation Protocol, which is a very common VOIP protocol.

Installing

Working on the server where oils is installed:

Make sure cvs is installed by running "which cvs" a reply of nothing means you need to install it. If you do then:

    sudo apt-get update
    sudo apt-get install cvs

Next try to download the code to the opt directory:

    cd /opt
    sudo cvs -d:pserver:anonymous@openncip.cvs.sourceforge.net:/cvsroot/openncip login

Note: you might get an error here if you just installed cvs to the effect of "CVS password file .... does not exist - creating a new file". If this happens just run the command above again.

when prompted for a password, just hit "Enter" and run the following:

    sudo cvs -z3 -d:pserver:anonymous@openncip.cvs.sourceforge.net:/cvsroot/openncip co -P SIPServer

you should now have the code downloaded. There should be a new folder named /opt/SIPServer

Configuring the Server

    su opensrf
    $ cd /openils/conf
    $ cp oils_sip.xml.example oils_sip.xml

Edit /openils/conf/oils_sip.xml, ensure the services are set to listen as below:

        <listeners>
             <service
                     port="127.0.0.1:6001/tcp"
                     transport="http"
                     protocol="NCIP/1.0" />

             <service
                     port="8023/tcp"
                     transport="telnet"
                     protocol="SIP/1.00"
                     timeout="60" />

             <service
                     port="8080/tcp"
                     transport="RAW"
                     protocol="SIP/2.00"
                     timeout="60" />
        </listeners>

Change the commented out <server-params> section to this:

    <server-params
    min_servers='1' 
    min_spare_servers='0'
    max_servers='25'
    />

NOTE: <max_servers> will directly correspond to the number of allowed SIP clients. Set the number accordingly, but bear in mind that too many connections can exhaust memory. On a 4G RAM/4 CPU server (that is also running evergreen), I would recommend not exceeding 100 SIP client connections, give or take.

In the <accounts> section of oils_sip.xml, add SIP client login information. Make sure that all <login>'s use the same institution attribute. All attributes in the <login> section will be used by the SIP client ie:

        <accounts>
                <login id="sipclient" password="sippassword" institution="conifer"/>    
        </accounts>

NOTE: make sure you change all instances of "institiution id=" to match the institution attribute in <login>. In this case, you'd change them all to "conifer".

Edit iptables to open ports 8080 and 8023:

Adding SIP users

In Evergreen, create a new profile group called SIP. This group should be a sub-group of Users (not Staff or Patrons). Give the group the following permissions:

    COPY_CHECKIN
    COPY_CHECKOUT
    RENEW_CIRC
    VIEW_CIRCULATIONS
    VIEW_COPY_CHECKOUT_HISTORY
    VIEW_PERMIT_CHECKOUT
    VIEW_USER
    VIEW_USER_FINES_SUMMARY
    VIEW_USER_TRANSACTIONS

You can do this quickly via the sip_user.sql script found in /Contrib/trunk/tools (http://svn.open-ils.org/trac/ILS-Contrib/browser/conifer/trunk/tools/sip_user.sql).

Add the user you deliniated in oils_sip.xml <accounts></accounts> to the SIP group.

Running the server

    $ sudo su opensrf
    $ oils_ctl.sh -d /openils/var/run/ -s /openils/conf/oils_sip.xml -a [start|stop|restart]_sip

Stopping the server

  $ sudo su opensrf
  $ oils_ctl.sh -d /openils/var/run/ -s /openils/conf/oils_sip.xml -a [start|stop|restart]_sip

NOTE: that stop or restart might not work properly. You might need to stop the processes manually. After trying a stop, you should check if the service actually did stop:

    ps aux | grep sip

Running the command above, if you should see something like:

    opensrf   5313  0.0  0.0   5160   772 pts/0    R<+  14:56   0:00 grep sip
    opensrf  28330  0.0  0.0  45376 13552 pts/0    S<   14:44   0:00 perl SIPServer.pm /openils/conf/oils_sip.xml
    opensrf  28331  0.0  0.0  45376 11824 pts/0    S<   14:44   0:00 perl SIPServer.pm /openils/conf/oils_sip.xml

Seeing the above, you know the stop command didn't work and you'd kill the processes manually In this case you'd run:

    sudo kill 28330
    sudo kill 28331

Testing Your Connection

You can test your install by telneting to port 8080.

Test to see if the telnet service (telnetd) is running.

    netstat -a | grep telnet

should return:

    tcp        0      0 *:telnet                *:*                     LISTEN

if not, install and start telnetd.

Install telnet server:

    sudo apt-get install telnetd

start the service

     sudo /etc/init.d/openbsd-inetd restart

Try netstat again. If you have any doubts, try telneting to the local host:

    telnet localhost

If you get a login prompt, telnet is up and running.

Once telnet is up and running, you should verify that SIP is available via port 8080.

    telnet 8080

from another machine should return:

    Trying 131.104.100.168...
    Connected to comet.cs.uoguelph.ca.
    Escape character is '^]'.
    9300CNsipclientCPT3st
    940

940 is a successful login.

References

http://open-ils.org/dokuwiki/doku.php?id=evergreen-admin:sip

http://svn.open-ils.org/trac/ILS-Contrib/browser/conifer/trunk/tools/sip_user.sql

http://multimedia.mmm.com/mws/mediawebserver.dyn?6666660Zjcf6lVs6EVs66S0LeCOrrrrQ-

Condensed

    sudo apt-get update
    sudo apt-get install cvs
    cd /opt
    sudo cvs -d:pserver:anonymous@openncip.cvs.sourceforge.net:/cvsroot/openncip login
    sudo cvs -z3 -d:pserver:anonymous@openncip.cvs.sourceforge.net:/cvsroot/openncip co -P SIPServer

#Configure the Server
    su opensrf
    $ cd /openils/conf
    $ cp oils_sip.xml.example oils_sip.xml

#Edit /openils/conf/oils_sip.xml to match the file snippet at the bottom of the instructions:

# In Evergreen, create a new profile group called SIP with following perms:
#    COPY_CHECKIN
#    COPY_CHECKOUT
#    RENEW_CIRC
#    VIEW_CIRCULATIONS
#    VIEW_COPY_CHECKOUT_HISTORY
#    VIEW_PERMIT_CHECKOUT
#    VIEW_USER
#    VIEW_USER_FINES_SUMMARY
#    VIEW_USER_TRANSACTIONS
# Add the user you deliniated in oils_sip.xml <accounts></accounts> to the SIP group.
# running / stopping the server:

    $ sudo su opensrf
    $ oils_ctl.sh -d /openils/var/run/ -s /openils/conf/oils_sip.xml -a [start|stop|restart]_sip


################################################################
# 
# File snippet:
# /openils/conf/oils_sip.xml
#
################################################################
#
#        <listeners>
#             <service
#                     port="127.0.0.1:6001/tcp"
#                     transport="http"
#                     protocol="NCIP/1.0" />
#
#             <service
#                     port="8023/tcp"
#                     transport="telnet"
#                     protocol="SIP/1.00"
#                     timeout="60" />
#
#             <service
#                     port="8080/tcp"
#                     transport="RAW"
#                     protocol="SIP/2.00"
#                     timeout="60" />
#        </listeners>
#
#        <server-params
#                     min_servers='1' 
#                     min_spare_servers='0'
#                     max_servers='25'
#        />
#
#        <accounts>
#                <login id="sipclient" password="sippassword" institution="conifer"/>    
#        </accounts>
#
# change all instances of "institiution id=" to match institution attribute in accounts
#
#########################################################################################