more clean up of some admin files..
[working/Evergreen.git] / 1.6 / admin / sip.xml
index 8877939..7e8d44d 100644 (file)
@@ -4,23 +4,28 @@
        <info>\r
                <title>SIP Server</title>\r
        </info>\r
-       <para>SIP, standing for Standard Interchange Protocol, was developed by the 3M corporation to be a common protocol for data transfer between ILS' \r
-       (referred to in SIP as an <emphasis>ACS</emphasis>, or <emphasis>Automated Circulation System</emphasis>) and a third party device. Originally, the protocol was developed for \r
+       <para><systemitem class="protocol">SIP</systemitem>, standing for <systemitem class="protocol">Standard Interchange Protocol</systemitem>, was developed by the \r
+       <orgname class="corporation">3M</orgname>corporation to be a common protocol for data transfer between ILS' \r
+       (referred to in <systemitem class="protocol">SIP</systemitem> as an <emphasis>ACS</emphasis>, or <emphasis>Automated Circulation System</emphasis>)\r
+       <indexterm><primary>Automated Circulation System</primary></indexterm> and a \r
+       third party device. Originally, the protocol was developed for \r
        use with 3M SelfCheck (often abbreviated SC, not to be confused with Staff Client) systems, but has since expanded to other companies and devices. It is now common to find \r
-       SIP in use in several other vendors' SelfCheck systems, as well as other non-SelfCheck devices. Some examples include:</para>\r
+       <systemitem class="protocol">SIP</systemitem> in use in several other vendors' SelfCheck systems<indexterm><primary>SelfCheck</primary></indexterm>, as well as other non-SelfCheck devices. \r
+       Some examples include:</para>\r
        <itemizedlist>\r
                <listitem>Patron Authentication (computer access, subscription databases)</listitem>\r
-               <listitem>Automated Material Handling (AMH) - The automated sorting of items, often to bins or book carts, based on shelving location or other programmable criteria</listitem>\r
+               <listitem>Automated Material Handling (AMH) <indexterm><primary>Automated Material Handling (AMH)</primary></indexterm>- The automated sorting of items, often to bins or \r
+               book carts, based on shelving location or other programmable criteria</listitem>\r
        </itemizedlist>\r
    \r
        <section xml:id="Installing_SIP_Server">\r
                <info>\r
-               <title>Installing the SIP Server</title>\r
+               <title>Installing the <systemitem class="protocol">SIP</systemitem> Server</title>\r
                </info>\r
-                 <para>This is a rough intro to installing the SIP server for Evergreen.</para>\r
+                 <para>This is a rough intro to installing the <systemitem class="protocol">SIP</systemitem> server for Evergreen.</para>\r
                <simplesect xml:id="Gettingthecode">\r
                            <title>Getting the code</title>\r
-                               <para>Current SIP code lives at github:</para>\r
+                               <para>Current <systemitem class="protocol">SIP</systemitem> code lives at github:</para>\r
                                <screen>cd /opt</screen>\r
                                <screen>git clone git://github.com/atz/SIPServer.git SIPServer</screen>\r
                                <para>Or use the old style:</para>\r
@@ -40,7 +45,8 @@
                                <screen>$ cp oils_sip.xml.example oils_sip.xml</screen>\r
                        </step>\r
                        <step>\r
-                               <para>Edit oils_sip.xml. Change the commented out &lt;server-params&gt; section to this:</para>\r
+                               <para>Edit <filename>oils_sip.xml</filename><indexterm><primary>configuration files</primary><primary>oils_sip.xml</primary></indexterm>. \r
+                               Change the commented out &lt;server-params&gt; section to this:</para>\r
                                <screen>&lt;server-params</screen>\r
                                <screen>min_servers='1'</screen>\r
                                <screen>min_spare_servers='0'</screen>\r
                                <screen>/&gt;</screen>\r
                        </step>\r
                        <step>\r
-                               <para> 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 \r
-                               exhaust memory. On a 4G RAM/4 CPU server (that is also running evergreen), I would recommend not exceeding 100 SIP client connections, \r
+                               <para> max_servers will directly correspond to the number of allowed <systemitem class="protocol">SIP</systemitem> clients. Set the number accordingly, but \r
+                               bear in mind that too many connections can \r
+                               exhaust memory. On a 4G RAM/4 CPU server (that is also running evergreen), I would recommend not exceeding 100 \r
+                               <systemitem class="protocol">SIP</systemitem> client connections, \r
                                give or take.</para>                            \r
                        </step>\r
                        </procedure>             \r
                </simplesect>\r
                <simplesect xml:id="Adding_SIP_users">\r
-                       <title>Adding SIP Users</title>\r
+                       <title>Adding <systemitem class="protocol">SIP</systemitem> Users</title>\r
                        <procedure>\r
                                <step>\r
                                        <para>Type the following commands from the command prompt:</para>\r
                                        <screen>$ cp oils_sip.xml.example oils_sip.xml</screen>\r
                                </step>\r
                                <step>\r
-                                       <para> in the &lt;accounts&gt; section, add SIP client login information. Make sure that all &lt;logins&gt; use the same institution attribute, and make \r
-                                       sure the institution is listed in &lt;institutions&gt;. All attributes in the &lt;login&gt; section will be used by the SIP client.</para>\r
+                                       <para> in the &lt;accounts&gt; section, add <systemitem class="protocol">SIP</systemitem> client login information. Make sure that all &lt;logins&gt; use the \r
+                                       same institution attribute, and make \r
+                                       sure the institution is listed in &lt;institutions&gt;. All attributes in the &lt;login&gt; section will be used by the <systemitem class="protocol">SIP</systemitem> client.</para>\r
                                \r
                                </step>\r
                                <step>\r
-                                       <para> In Evergreen, create a new profile group called SIP. This group should be a sub-group of Users (not Staff or Patrons). \r
+                                       <para> In Evergreen, create a new profile group called <systemitem class="protocol">SIP</systemitem>. This group should be a sub-group of Users \r
+                                       (not Staff or Patrons). \r
                                        Set Editing Permission as <emphasis>group_application.user.sip_client</emphasis> and give the group the following permissions:</para>\r
                                        <literallayout>\r
                                        COPY_CHECKIN\r
                                </step>\r
                                <step>\r
                                        <para>For each account created in the &lt;login&gt; section of oils_sip.xml, create a user (via the staff client user editor) that has the same username \r
-                                       and password and put that user into the SIP group.</para>\r
-                                       <note><para>The expiration date will affect the SIP users' connection, you might want to make a note of \r
+                                       and password and put that user into the <systemitem class="protocol">SIP</systemitem> group.</para>\r
+                                       <note><para>The expiration date will affect the <systemitem class="protocol">SIP</systemitem> users' connection, you might want to make a note of \r
                                        this somewhere. </para></note>  \r
                                </step>\r
                        </procedure>             \r
                </simplesect>\r
                <simplesect xml:id="Running_SIP_server">\r
                        <title>Running the server</title>\r
-                               <para>To start the SIP server type the following commands from the command prompt:</para>\r
+                               <para>To start the <systemitem class="protocol">SIP</systemitem> server type the following commands from the command prompt:</para>\r
                                <screen>$ sudo su opensrf</screen>\r
                                <screen>$ oils_ctl.sh -d /openils/var/run -s /openils/conf/oils_sip.xml -a [start|stop|restart]_sip</screen>    \r
                </simplesect>\r
                        <title>Logging-SIP</title>\r
                        <simplesect>\r
                                <title>Syslog</title>\r
-                               <para>It is useful to log SIP requests to a separate file especially during initial setup by modifying your syslog config file.</para>\r
+                               <para>It is useful to log <systemitem class="protocol">SIP</systemitem> requests to a separate file especially during initial setup by modifying your syslog config file.</para>\r
                                <procedure>\r
                                        <step>\r
                                                <para>Edit syslog.conf.</para>\r
                        </simplesect>\r
                </simplesect>   \r
                <simplesect xml:id="Testing_SIP_Connection">\r
-                       <title>Testing Your SIP Connection</title>\r
+                       <title>Testing Your <systemitem class="protocol">SIP</systemitem> Connection</title>\r
                        <itemizedlist>\r
                                <listitem>\r
                                        <para>In the top level CVS checkout of the SIPServer code.</para>\r
                        <title>More Testing</title>\r
                        <procedure>\r
                                <step>\r
-                                       <para>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 \r
-                                       if you so wish, but we want to prove that SIP2 works from non-localhost. Replace $instid, $server, $barcode, $username, and $password variables below as \r
+                                       <para>Once you have opened up either the <systemitem class="protocol">SIP</systemitem> OR <systemitem class="protocol">SIP2</systemitem> ports to be accessible from outside you can do some testing via telnet. You can try this with localhost \r
+                                       if you so wish, but we want to prove that <systemitem class="protocol">SIP2</systemitem> works from non-localhost. Replace $instid, $server, $barcode, $username, and $password variables below as \r
                                        necessary.</para>\r
-                                       <note><para>We are using 6001 here which is associated with SIP2 as per our configuration.</para></note>\r
+                                       <note><para>We are using 6001 here which is associated with <systemitem class="protocol">SIP2</systemitem> as per our configuration.</para></note>\r
                                        <screen>$ telnet $server 6001</screen>\r
                                        <screen>Connected to $server.</screen>\r
                                        <screen>Escape character is '^]'.</screen>\r
        </section>\r
        <section xml:id="SIP_Communication">\r
                <info>\r
-                       <title>SIP Communication</title>\r
+                       <title><systemitem class="protocol">SIP</systemitem> Communication</title>\r
                </info>\r
-               <para>SIP generally communicates over a TCP connection (either raw sockets or over telnet), but can also communicate via serial connections and other methods. In Evergreen, \r
+               <para><systemitem class="protocol">SIP</systemitem> generally communicates over a TCP connection (either raw sockets or over telnet), but can also communicate via serial connections and other methods. In Evergreen, \r
                the most common deployment is a RAW socket connection on port 6001.</para>\r
                <para>SIP communication consists of strings of messages, each message request and response begin with a 2-digit <quote>command</quote> - Requests usually being an odd \r
                number and responses usually increased by 1 to be an even number. The combination numbers for the request command and response is often referred to as a \r
                                                <entry>93/94</entry>\r
                                                <entry>Login</entry>\r
                                                <entry>Yes</entry>\r
-                                               <entry><link linkend='SIP_Login'>93/94_Login</link> - Must be first command to Evergreen ACS (via socket) or SIP will terminate</entry>\r
+                                               <entry><link linkend='SIP_Login'>93/94_Login</link> - Must be first command to Evergreen ACS (via socket) or <systemitem class="protocol">SIP</systemitem> will terminate</entry>\r
                                        </row>\r
                                        <row>\r
                                                <entry>97/96</entry>\r
                        <para>The request looks like:</para>\r
                        <screen>17&lt;xact_date&gt;[fields: AO,AB,AC]</screen>\r
                        <para>The request is very terse. AC is optional.</para>\r
-                       <para>The following response structure is for SIP2. (Version 1 of the protocol had only 6 total fields.)</para>\r
+                       <para>The following response structure is for <systemitem class="protocol">SIP2</systemitem>. (Version 1 of the protocol had only 6 total fields.)</para>\r
                        <screen>18&lt;circulation_status&gt;&lt;security_marker&gt;&lt;fee_type&gt;&lt;xact_date&gt;[fields: CF,AH,CJ,CM,AB,AJ,BG,BH,BV,CK,AQ,AP,CH,AF,AG,+CT,+CS]</screen>\r
                        <para>Example:</para>\r
                        <screen>1720060110    215612AOBR1|ABno_such_barcode|</screen>\r
                        <screen>2300120060101    084235AOCONS|AA999999|ACsip_01|ADuserpassword|LY|CQN|BHUSD|BV0.00|AFOK|AOCONS|</screen>\r
                        <screen>24  Y           00120100507    022803AEDoug Fiander|AA999999|BLY|CQY|BHUSD|BV0.00|AFOK|AOCONS|</screen>\r
                        <orderedlist>\r
-                               <listitem>The <emphasis>BL</emphasis> field (SIP2, optional) is <emphasis>valid patron</emphasis>, so the <emphasis>N</emphasis> value means \r
+                               <listitem>The <emphasis>BL</emphasis> field (<systemitem class="protocol">SIP2</systemitem>, optional) is <emphasis>valid patron</emphasis>, so the <emphasis>N</emphasis> value means \r
                                <emphasis>bad_barcode</emphasis> doesn't match a patron, the <emphasis>Y</emphasis> value means 999999 does.</listitem>\r
-                               <listitem>The <emphasis>CQ</emphasis> field (SIP2, optional) is <emphasis>valid password</emphasis>, so the <emphasis>N</emphasis> \r
+                               <listitem>The <emphasis>CQ</emphasis> field (<systemitem class="protocol">SIP2</systemitem>, optional) is <emphasis>valid password</emphasis>, so the <emphasis>N</emphasis> \r
                                value means <emphasis>bad_password</emphasis> doesn't match 999999's password, the <emphasis>Y</emphasis> means <emphasis>userpassword</emphasis> \r
                                does.</listitem>\r
                        </orderedlist>\r
-                       <para>So if you were building the most basic SIP2 authentication client, you would check for <emphasis>|CQY|</emphasis> in the response to know the user's barcode and password \r
+                       <para>So if you were building the most basic <systemitem class="protocol">SIP2</systemitem> authentication client, you would check for <emphasis>|CQY|</emphasis> in the response to know the user's barcode and password \r
                        are correct (<emphasis>|CQY|</emphasis> implies <emphasis>|BLY|</emphasis>, since you cannot check the password unless the barcode exists). However, in practice, \r
                        depending on the application, there are other factors to consider in authentication, like whether the user is blocked from checkout, owes excessive fines, reported their \r
                        card lost, etc. These limitations are reflected in the 14-character <emphasis>patron status</emphasis> string immediately following the <emphasis>24</emphasis> code. \r
                        <para>Example:</para>\r
                        <screen>9910302.00</screen>\r
                        <screen>98YYYYNN60000320100510    1717202.00AOCONS|BXYYYYYYYYYNYNNNYN|</screen>\r
-                       <para>The Supported Messages field <emphasis>(BX)</emphasis> appears only in SIP2, and specifies whether 16 different SIP commands are supported by the ACS or not.</para>\r
+                       <para>The Supported Messages field <emphasis>(BX)</emphasis> appears only in <systemitem class="protocol">SIP2</systemitem>, and specifies whether 16 different \r
+                       <systemitem class="protocol">SIP</systemitem>  commands are supported by the ACS or not.</para>\r
                </simplesect>\r
                <simplesect xml:id="SIP_Fields">\r
                        <title>Fields</title>\r