Docs: updating SIP docs

Signed-off-by: Jane Sandberg <sandbej@linnbenton.edu>

diff --git a/docs/admin/sip_privacy.adoc b/docs/admin/sip_privacy.adoc
new file mode 100644 (file)
index 0000000..2db1e85
--- /dev/null
+++ b/docs/admin/sip_privacy.adoc
@@ -0,0 +1,50 @@
+Patron privacy and the SIP protocol
+-----------------------------------
+
+SIP traffic includes a lot of patron information, and is not
+encrypted by default.  It is strongly recommended that you
+encrypt any SIP traffic.
+
+SIP server configuration
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+On the SIP server, use `iptables` or `etc/hosts` to allow SSH connections on port 22 from the SIP client machine.  You will probably want to have very restrictive rules
+on which IP addresses can connect to this server.
+
+
+SSH tunnels on SIP clients
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SSH tunnels are a good fit for use cases like self-check machines, because it is relatively easy to automatically open the connection.  Using a VPN is another option,
+but many VPN clients require manual steps to open the VPN connection.
+
+. If the SIP client will be on a Windows machine, install cygwin on the SIP client.
+. On the SIP client, use `ssh-keygen` to generate an SSH key.
+. Add the public key to /home/my_sip_user/.ssh/authorized_keys on your SIP server to enable logins without using the UNIX password.
+. Configure an SSH tunnel to open before every connection.  You can do this in several ways:
+.. If the SIP client software allows you to run an arbitrary command before
+   each SIP connection, use something like this:
++
+[source,bash]
+----
+ssh -f -L 6001:localhost:6001 my_sip_user@my_sip_server.com sleep 10
+----
++
+.. If you feel confident that the connection won't get interrupted, you can have something like this run at startup:
++
+[source,bash]
+----
+ssh -f -N -L 6001:localhost:6001 my_sip_user@my_sip_server.com
+----
++
+.. If you want to constantly poll to make sure that the connection is still running, you can do something like this as a cron job or scheduled task on the SIP client machine:
+[source,bash]
+----
+#!/bin/bash
+instances=`/bin/ps -ef | /bin/grep ssh | /bin/grep -v grep | /bin/wc -l`
+if [ $instances -eq 0 ]; then
+  echo "Restarting ssh tunnel"
+  /usr/bin/ssh -L 6001:localhost:6001 my_sip_user@my_sip_server.com -f -N
+fi
+----
+

diff --git a/docs/admin/sip_server.adoc b/docs/admin/sip_server.adoc
index 9fe87ca..2aeb619 100644 (file)
--- a/docs/admin/sip_server.adoc
+++ b/docs/admin/sip_server.adoc
@@ -60,6 +60,32 @@ indexterm:[configuration files, oils_sip.xml]
 bear in mind that too many connections can exhaust memory. On a 4G RAM/4 CPU server (that is also running 
 evergreen), it is not recommended to exceed 100 +SIP+ client connections. 
 
+Setting the encoding
+++++++++++++++++++++
+
+SIPServer looks for the encoding in the following
+places:
+
+1. An +encoding+ attribute on the +account+ element for the currently active SIP account.
+2. The +encoding+ element that is a child of the +institution+ element of the currently active SIP account.
+3. The +encoding+ element that is a child of the +implementation_config+ element that is itself a child of the +institution+ element of the currently active SIP account.
+4. If none of the above exist, then the default encoding (ASCII) is used.
+
+Option 3 is a legacy option.  It is recommended that you alter your configuration to
+move this element out of the +implementation_config+ element and into
+its parent +institution+ element.  Ideally, SIPServer should *not* look into
+the implementation config, and this check may be removed at some time
+in the future.
+
+Datatypes
++++++++++
+
+The `msg64_hold_datatype` setting is similar to `msg64_summary_datatype`, but affects holds instead of circulations.
+When set to `barcode`, holds information will be delivered as a set of copy barcodes instead of title strings for
+patron info requests. With barcodes, SIP clients can both find the title strings for display (via item info requests)
+and make subsequent hold-related action requests, like holds cancellation. 
+
+
 Adding SIP Users
 ^^^^^^^^^^^^^^^^
 
@@ -421,8 +447,8 @@ indexterm:[magnetic media]
 
 [NOTE]
 ===============
-The logic for Evergreen to determine whether the content is magnetic_media comes from either legacy circ 
-scripts or search_config_circ_modifier. The default is non-magnetic. The same is true for media_type (default 
+The logic for Evergreen to determine whether the content is magnetic_media comes from  
+or search_config_circ_modifier. The default is non-magnetic. The same is true for media_type (default 
 001). Evergreen does not populate the collection_code because it does not really have any, but it will provide 
 the call_number where available.
 
@@ -541,7 +567,8 @@ anchor:sip_29-30_renew[]
 29/30 Renew
 ^^^^^^^^^^^
 
-Evergreen supports the Renew message.
+Evergreen supports the Renew message. Evergreen checks whether a penalty is specifically configured to block
+renewals before blocking any SIP renewal.
 
 
 anchor:sip_35-36_end_session[]
@@ -617,6 +644,8 @@ Example:
 
 _941_ means successful terminal login. _940_ or getting dropped means failure.
 
+When using a version of SIPServer that supports the feature, the Location (CP) field of the Login (93) message will be used as the workstation name if supplied. Blank or missing location fields will be ignored. This allows users or reports to determine which selfcheck performed a circulation.
+
 
 anchor:sip_97-96_resend[]
 

diff --git a/docs/root.adoc b/docs/root.adoc
index 952e5aa..39d4575 100644 (file)
--- a/docs/root.adoc
+++ b/docs/root.adoc
@@ -159,6 +159,12 @@ include::admin/phonelist.adoc[]
 
 include::admin/sip_server.adoc[]
 
+:leveloffset: 1
+
+include::admin/sip_privacy.adoc[]
+
+:leveloffset: 0
+
 include::admin/apache_rewrite_tricks.adoc[]
 
 include::admin/apache_access_handler.adoc[]

diff --git a/docs/root_integrations.adoc b/docs/root_integrations.adoc
index 4c8fbbe..6c5b2a2 100644 (file)
--- a/docs/root_integrations.adoc
+++ b/docs/root_integrations.adoc
@@ -43,6 +43,8 @@ include::admin/sip_server.adoc[]
 
 :leveloffset: 0
 
+include::admin/sip_privacy.adoc[]
+
 include::shared/attributions.adoc[]
 
 include::shared/end_matter.adoc[]