Differences

This shows you the differences between two versions of the page.

--- evergreen-admin:sip [2010/01/13 18:24] – aatre
+++ evergreen-admin:sip [2022/02/10 13:34] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
-====Installing the SIP Server for Evergreen====
+======Installing the SIP Server for Evergreen======
 Author: Bill Erickson\\
 This is a rough intro to installing the SIP server for Evergreen.
-===Getting the code===
+NOTE: This documentation is also available in the Evergreen documentation at [[http://docs.evergreen-ils.org/1.6/draft/html/]]. In github: [[http://github.com/rsoulliere/Evergreen-DocBook/blob/master/1.6/admin/sip.xml]].
+=====Getting the code=====
+Current SIP code lives at http://git.evergreen-ils.org:
 <code>
-$ cd /opt
+cd /opt
-$ sudo cvs -d:pserver:anonymous@openncip.cvs.sourceforge.net:/cvsroot/openncip login
+git clone git://git.evergreen-ils.org/SIPServer.git SIPServer
-# when prompted for a password, just hit Enter
-$ sudo cvs -z3 -d:pserver:anonymous@openncip.cvs.sourceforge.net:/cvsroot/openncip co -P SIPServer
 </code>
-===Configuring the Server===
+=====Configuring the Server=====
    - <code>$ sudo su opensrf
 $ cd /openils/conf
@@ Line 18: / Line 19: @@
     <server-params
         min_servers='1'
-        min_spare_servers='0'
+        min_spare_servers='1'
         max_servers='25'
     /></code>
   - ''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.
-===Adding SIP users====
+=====Adding SIP users=====
-  - in the <accounts> section, 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.
+  - in the <accounts> section, add SIP client login information.  Make sure that all <login>s use the same institution attribute, and make sure the institution is listed in <institutions>.  All attributes in the <login> section will be used by the SIP client.
-  - In Evergreen, create a new profile group called SIP.  This group should be a sub-group of Users (not Staff or Patrons).  Set Editing Permission as "group_application.user.sip_client" and give the group the following permissions:<code>
+  - In Evergreen, create a new profile group called SIP.  This group should be a sub-group of Users (not Staff or Patrons).  Set Editing Permission as "group_application.user.sip_client" and give the group the following permissions:
+<code>
 COPY_CHECKIN
 COPY_CHECKOUT
@@ Line 35: / Line 37: @@
 VIEW_USER_FINES_SUMMARY
 VIEW_USER_TRANSACTIONS</code>
+OR use SQL like:
+<code sql>
+INSERT INTO permission.grp_tree (id,name,parent,description,application_perm)
+VALUES (8, 'SIP', 1, 'SIP2 Client Systems', 'group_application.user.sip_client');
+INSERT INTO
+  permission.grp_perm_map (grp, perm, depth, grantable)
+SELECT
+  g.id, p.id, 0, FALSE
+FROM
+  permission.grp_tree g,
+  permission.perm_list p
+WHERE
+  g.name = 'SIP' AND
+  p.code in (
+    'COPY_CHECKIN',
+    'COPY_CHECKOUT',
+    'RENEW_CIRC',
+    'VIEW_CIRCULATIONS',
+    'VIEW_COPY_CHECKOUT_HISTORY',
+    'VIEW_PERMIT_CHECKOUT',
+    'VIEW_USER',
+    'VIEW_USER_FINES_SUMMARY',
+    'VIEW_USER_TRANSACTIONS'
+);
+-- VERIFY:
+SELECT *
+  FROM permission.grp_perm_map JOIN permission.perm_list ON
+       permission.grp_perm_map.perm=permission.perm_list.id
+  WHERE grp=8;
+</code>
+Keep in mind that the id (8) may not necessarily be available on your system.
   - For each account created in the <login> section of oils_sip.xml, create a user (via the staff client user editor) that has the same username and password and put that user into the SIP group.
 Note: The expiration date will affect the SIP users' connection, you might want to make a note of this somewhere.
-===Running the server===
+=====Running the server=====
 <code>
 $ sudo su opensrf
@@ Line 44: / Line 81: @@
 </code>
-===Testing Your Connection===
+=====Logging=====
+==Syslog==
+ It is useful to log SIP requests to a separate file especially during initial setup by modifying your syslog config file.
+  - Edit syslog.conf.<code>$ sudo vi /etc/syslog.conf  # maybe /etc/rsyslog.conf</code>
+  - Add this:<code>local6.*                -/var/log/SIP_evergreen.log</code>
+  - Syslog expects the logfile to exist so create the file.<code>$ sudo touch /var/log/SIP_evergreen.log</code>
+  - Restart sysklogd<code>$ sudo /etc/init.d/sysklogd restart</code>
+==Syslog-NG==
+  - Edit logging config <code>sudo vi /etc/syslog-ng/syslog-ng.conf</code>
+  - Add:<code>
+# SIP2 for Evergreen
+filter    f_eg_sip { level(warn, err, crit) and facility(local6); };
+destination eg_sip { file("/var/log/SIP_evergreen.log"); };
+log { source(s_all); filter(f_eg_sip); destination(eg_sip); };
+</code>
+  - Syslog-ng expects the logfile to exist so create the file.<code>$ sudo touch /var/log/SIP_evergreen.log</code>
+  - Restart syslog-ng <code>$ sudo /etc/init.d/syslog-ng restart</code>
+== syslog-ng(remote logging server) ==
+Use this configuration in the destination server's syslog-ng.conf to filter incoming remote SIP logs into a daily unified SIP.log.  Be sure to modify paths according to your environment.
+<code>
+# --------------------------------------------------------------------------------
+# Destination
+# --------------------------------------------------------------------------------
+destination d_external_sip {                             # f_sip
+file("/var/log/remote/prod/$YEAR/$MONTH/$DAY/SIP.log",
+        template("$YEAR-$MONTH-$DAY $HOUR:$MIN:$SEC $HOST $MSG\n") owner(nagios) group(nagios) perm(0644) template-escape(no)); };
+# --------------------------------------------------------------------------------
+# Filter
+# --------------------------------------------------------------------------------
+filter f_sip { match("acs-server"); };
+# --------------------------------------------------------------------------------
+# Log Statement
+# --------------------------------------------------------------------------------
+log { source(s_external); filter(f_sip); destination(d_external_sip); };</code>
+Add the lines below to the syslog-ng.conf on the remote server you wish to forward logs from.
+<code>
+#SIP
+source s_file_sip { file("/var/log/SIP.log" follow_freq(1)); };
+log { source(s_file_sip); destination(d_ext); };</code>
+=====Testing Your Connection=====
   * In the top level CVS checkout of the SIPServer code
 <code>
 $ cd SIPServer/t
 </code>
-  * Edit SIPTest.pm, change the $instid, $server, $username, and $password variables.  This will be enough to test connectivity.  To run all tests, you'll need to change all the variables in the Configuration section
+  * Edit SIPtest.pm, change the $instid, $server, $username, and $password variables.  This will be enough to test connectivity.  To run all tests, you'll need to change all the variables in the Configuration section
 <code>
 $ PERL5LIB=../ perl 00sc_status.t
@@ Line 63: / Line 154: @@
   * Don't be dismayed at "Invalid Username".  That's just one of the many tests that are run.
-===More Testing===
+====More Testing====
 Once you have opened up either the SIP OR SIP2 ports to be accessible from outside you can do some testing via telnet.
 You can try this with localhost if you so wish, but we want to prove that SIP2 works from non-localhost.
@@ Line 72: / Line 163: @@
 Connected to $server.
 Escape character is '^]'.
-CN$username|CO$password|CP$instid
+CN**$username**|CO**$password**|CP**$instid**
 </code>
 You should get back.
@@ Line 80: / Line 171: @@
 Now just copy in the following line (with variables replaced) you don't need to hit enter, just paste!
 <code>
-2300120080623    172148AOecrl|AA$barcode|AC$password|AD$password
+2300120080623    172148AO**$instid**|AA**$barcode**|AC$password|AD**$password**
 </code>
-You will get back the patron information for $barcode.
+You will get back the patron information for $barcode (something similar to the what's below).
 <code>
-  Y           00120100113    170738AEFirstName MiddleName LastName|AA$barcode|BLY|CQY|BHUSD|BV0.00|AFOK|AO$instid|
+  Y           00120100113    170738AEFirstName MiddleName LastName|AA**$barcode**|BLY|CQY|BHUSD|BV0.00|AFOK|AO**$instid**|
 </code>
 The response declares it is a valid patron (BLY) with a valid password (CQY) and shows the user's $name.