= SIP =

[#QuickReference Quick Reference][[BR]]
----
[#Overview Overview][[BR]]
[#Installing Installing][[BR]]
[#ConfiguringTheServer Configuring the server][[BR]]
[#AddingSIPUsers Adding SIP Users][[BR]]
[#RunningTheServer Running The Server][[BR]]
[#StoppingTheServer Stopping The Server][[BR]]
[#TestingYourConnection Testing Your Connection][[BR]]
[#References References][[BR]]


----
== 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 [#sysadminIptables#sip 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-

----
== Quick Reference ==

{{{
    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.
#
# Open ports 8080, 8023 
#
# 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

#check that it all works:

    $ telnet 8080

################################################################
# 
# 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

#########################################################################################
}}}