Add startup options and Startup script from Anoop Atre.
[working/Evergreen.git] / 1.6 / admin / AdminMisc.xml
index ec6144e..db21f40 100644 (file)
@@ -44,9 +44,9 @@
                <caution>\r
                        <para>If you decide to start each service individually, you need to start them in a specific order \r
                        for Evergreen to start correctly. Run the commands in this exact order:</para>\r
-                       <screen><userinput>osrf_ctl.sh -l -a start_router</userinput></screen>\r
-                       <screen><userinput>osrf_ctl.sh -l -a start_perl</userinput></screen>\r
-                       <screen><userinput>osrf_ctl.sh -l -a start_c</userinput></screen>\r
+<screen><userinput>osrf_ctl.sh -l -a start_router</userinput></screen>\r
+<screen><userinput>osrf_ctl.sh -l -a start_perl</userinput></screen>\r
+<screen><userinput>osrf_ctl.sh -l -a start_c</userinput></screen>\r
                </caution>      \r
                <para>After starting or restarting Evergreen, it is also necessary to restart the <systemitem class="service">Apache web server</systemitem>\r
                <indexterm><primary>web server</primary><secondary>Apache</secondary></indexterm> for the OPAC to work correctly.</para>  \r
                <para>As with starting, you can choose to stop services individually.</para>\r
                <para>To restart <application>Evergreen</application>, run:</para>\r
                <screen><userinput>osrf_ctl.sh -l -a restart_all</userinput></screen>\r
+               <simplesect>\r
+                       <title>Starting Specific Perl Services</title>\r
+                       <para>It is also possible to start and stop a specific perl service using <filename>opensrf-perl.pl</filename>.  Here is the syntax for starting a perl service with this command:</para>\r
+<screen><userinput>opensrf-perl.pl --service <systemitem class="service">&lt;service-name&gt;</systemitem> -a start -p <filename class="directory">&lt;PID-directory&gt;</filename> </userinput></screen>\r
+<para>Example (starting the booking module):</para>\r
+<screen><userinput>opensrf-perl.pl --service <systemitem class="service">open-ils.booking</systemitem> -a start -p <filename class="directory">/openils/var/run/opensrf</filename></userinput></screen>\r
+\r
+<para>This is the syntax for stopping a perl service with this command:</para>\r
+<screen><userinput>opensrf-perl.pl --service <systemitem class="service">&lt;service-name&gt;</systemitem> -a stop -p <filename class="directory">&lt;PID-directory&gt;</filename> </userinput></screen>\r
+<para>Example (stopping the booking module):</para>\r
+<screen><userinput>opensrf-perl.pl --service <systemitem class="service">open-ils.booking</systemitem> -a stop -p <filename class="directory">/openils/var/run/opensrf</filename></userinput></screen>\r
+                       <para>These commands can be very useful when you edit Perl modules and only need to restart the specific service for changes to take effect.</para>\r
+                       \r
+                       <note>\r
+                       <para>The default for the PID-directory: <filename class="directory">/openils/var/run/opensrf</filename></para>\r
+                       <para>For a clustered server instance of Evergreen, you must store the PIDs on a directory \r
+                       that is local to each server, or else one of your cluster servers may try killing processes on itself that actually have PIDs on other servers.</para>\r
+                       <para>For services running on the local server use the <option>--localhost</option> to force the hostname to be <systemitem class="domainname">localhost</systemitem>, \r
+                       instead of the fully qualified domain name for the machine.</para>\r
+                       <para>To see other options run the command with the <option>-h</option> option:</para>\r
+<screen><userinput>opensrf-perl.pl  -h</userinput></screen>\r
+                       </note>\r
+<para>For a list of Evergreen/OpenSRF perl services see: <xref linkend="_evergreen_specific_opensrf_services"/>.</para>\r
+               </simplesect>\r
+       </section>\r
+       <section xml:id="evergreen_startup_script">\r
+               <title>Automating Evergreen Startup and Shutdown</title>\r
+               <para>Once you understand starting and stopping Evergreen, you will want to create a start up script for two purposes:</para>\r
+               <itemizedlist>\r
+                       <listitem>Allow you to start, restart and stop Evergreen, SIP, reporter and z39.50 services with one command.</listitem>\r
+                       <listitem>Allow Evergreen to stop and start properly during a system restart.</listitem>\r
+               </itemizedlist>\r
+               <para>The following procedure is for Debian or Ubuntu distributions of Linux.</para>\r
+               <procedure>\r
+                       <step>\r
+                               <para>Create a bash script for starting Evergreen and all associated services. Here is an example script:</para>  \r
+\r
+<programlisting>\r
+<![CDATA[\r
+\r
+\r
+#!/bin/bash\r
+\r
+OPENILS_BASE="/openils"\r
+OPENILS_CORE="${OPENILS_BASE}/conf/opensrf_core.xml"\r
+SRU_LOG="${OPENILS_BASE}/var/log/sru.log"\r
+\r
+SIP_PID="${OPENILS_BASE}/var/run"\r
+SIP_CONF="${OPENILS_BASE}/conf/oils_sip.xml"\r
+\r
+REP_LOCK="${OPENILS_BASE}/var/lock/reporter-LOCK"\r
+REP_NAME="Clark Kent, waiting for trouble"\r
+\r
+sru_name='simple2zoom'\r
+\r
+if [ $(whoami) != 'opensrf' ]; then\r
+ PERL5LIB='/openils/lib/perl5:$PERL5LIB';\r
+fi;\r
+\r
+start() {\r
+        sleep 3\r
+        echo "Starting Evergreen"\r
+        sudo -u opensrf /bin/bash -c "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin osrf_ctl.sh -l -a start_all"\r
+}\r
+\r
+stop() {\r
+        echo "Stopping Evergreen"\r
+        sudo -u opensrf /bin/bash -c "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin osrf_ctl.sh -l -a stop_all"\r
+}\r
+\r
+autogen() {\r
+        echo "Running Autogen Update"\r
+        sudo -u opensrf /bin/bash -c "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin autogen.sh -u -c ${OPENILS_CORE}"\r
+}\r
+\r
+sip_start() {\r
+        sudo -u opensrf /bin/bash -c "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin oils_ctl.sh \\r
+                                                                                                                     -d ${SIP_PID} \\r
+                                                                                                                     -s ${SIP_CONF} \\r
+                                                                                                                     -a start_sip"\r
+}\r
+\r
+sip_stop() {\r
+        sudo -u opensrf /bin/bash -c "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin oils_ctl.sh \\r
+                                                                                                                     -d ${SIP_PID} \\r
+                                                                                                                     -s ${SIP_CONF} \\r
+                                                                                                                     -a stop_sip"\r
+}\r
+\r
+sip_restart() {\r
+        sudo -u opensrf /bin/bash -c "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin oils_ctl.sh \\r
+                                                                                                                     -d ${SIP_PID} \\r
+                                                                                                                     -s ${SIP_CONF} \\r
+                                                                                                                     -a restart_sip"\r
+}\r
+\r
+start_rep() {\r
+        pids="$(pidof "$REP_NAME")"\r
+        if [ ! x"$pids" = x ] ; then\r
+          echo FAILURE ; echo $"Starting Reporting: already running as $pids" \r
+          return 1\r
+        fi\r
+        rm -f $REP_LOCK\r
+        sudo -u opensrf bash -c "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin clark-kent.pl \\r
+                                                           --lockfile=${REP_LOCK} --boostrap=${OPENILS_CORE} --concurrency=1 --sleep=30 --daemon" ;\r
+        pids="$(pidof "$REP_NAME")"\r
+        if [ x"$pids" = x ] ; then\r
+          echo FAILURE \r
+        else \r
+          echo OK\r
+        fi\r
+        echo "Starting Reporting: $pids" \r
+        return $RETVAL\r
+}\r
+\r
+stop_rep() {\r
+        pids="$(pidof "$REP_NAME")"\r
+        if [ x"$pids" = x ] ; then\r
+          echo FAILURE ; echo $"Stopping Reporting: not running" ; RETVAL=1\r
+        else \r
+          kill $pids ; RETVAL=$?\r
+          if [ $RETVAL ] ; then\r
+            echo OK ; echo $"Stopping Reporting: $pids"\r
+          else\r
+            echo FAILURE \r
+          fi\r
+        fi\r
+        rm -f $REP_LOCK\r
+        return $RETVAL\r
+}\r
+\r
+z39_50_start() {\r
+        pids=`ps -eo pid,args | grep $sru_name | grep -v grep | cut -c1-6`\r
+        if [ ! x"$pids" = x ] ; then\r
+          echo FAILURE ; echo $"Starting Z39.50/SRU: already running as $pids" \r
+          return 1\r
+        fi\r
+        sudo -u opensrf bash -c "touch ${SRU_LOG}"\r
+        sudo bash -c "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin z39_50.sh >> ${SRU_LOG} 2>&1" &\r
+        sleep 1\r
+        pids=`ps -eo pid,args | grep $sru_name | grep -v grep | cut -c1-6`\r
+        if [ x"$pids" = x ] ; then\r
+          echo FAILURE \r
+        else \r
+          echo OK\r
+        fi\r
+        echo "Starting Z39.50/SRU: $pids" \r
+        return $RETVAL\r
+}\r
+\r
+z39_50_stop() {\r
+        pids=`ps -eo pid,args | grep $sru_name | grep -v grep | cut -c1-6`\r
+        if [ x"$pids" = x ] ; then\r
+          echo FAILURE ; echo $"Stopping Z39.50/SRU: not running" ; RETVAL=1\r
+        else \r
+          kill $pids ; RETVAL=$?\r
+          if [ $RETVAL ] ; then\r
+            echo OK ; echo $"Stopping Z39.50/SRU: $pids"\r
+          else\r
+            echo FAILURE \r
+          fi\r
+        fi\r
+        return $RETVAL\r
+}\r
+\r
+case "$1" in\r
+    start)\r
+        start\r
+        start_rep\r
+        z39_50_start\r
+        sip_start\r
+    ;;\r
+    stop)\r
+        sip_stop\r
+        z39_50_stop\r
+        stop_rep\r
+        stop\r
+    ;;\r
+    restart)\r
+        echo "Restarting Evergreen, Reporter and Z39.50 Processes"\r
+        sip_stop\r
+        z39_50_stop\r
+        stop_rep\r
+        stop\r
+        start\r
+        start_rep\r
+        z39_50_start\r
+        sip_start\r
+    ;;\r
+    autogen)\r
+        autogen\r
+    ;;\r
+    sip_start)\r
+        sip_start\r
+    ;;\r
+    sip_stop)\r
+        sip_stop\r
+    ;;\r
+    sip_restart)\r
+        sip_restart\r
+    ;;\r
+    start_reporter)\r
+        start_rep\r
+    ;;\r
+    stop_reporter)\r
+        stop_rep\r
+    ;;\r
+    restart_reporter)\r
+       stop_rep\r
+       start_rep\r
+    ;;\r
+    z39_50_start)\r
+        z39_50_start\r
+    ;;\r
+    z39_50_stop)\r
+        z39_50_stop\r
+    ;;\r
+    z39_50_restart)\r
+        z39_50_stop\r
+        z39_50_start\r
+    ;;\r
+    start_router|stop_router|restart_router|start_perl|stop_perl|restart_perl| \\r
+    start_c|stop_c|restart_c|start_osrf|stop_osrf|restart_osrf|stop_all|start_all|restart_all)\r
+        sudo -u opensrf /bin/bash -c "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin osrf_ctl.sh -l -a $1"\r
+    ;;\r
+    *)\r
+        echo " * Usage: /etc/init.d/evergreen {start|stop|restart|autogen"\r
+        echo "                                 |sip_start|sip_stop|sip_restart"\r
+        echo "                                 |z39_50_start|z39_50_stop|z39_50_restart"\r
+        echo "                                 |start_reporter|stop_reporter|restart_reporter"\r
+        echo "                                 |start_router|stop_router|restart_router|start_perl|stop_perl|restart_perl"\r
+        echo "                                 |start_c|stop_c|restart_c|start_osrf|stop_osrf|restart_osrf|stop_all|start_all|restart_all}"\r
+        exit 1\r
+    ;;\r
+esac;\r
+]]>\r
+</programlisting>\r
+                       </step>\r
+                       <step>\r
+                               <para>Save file in <filename>/etc/init.d</filename> folder.</para> \r
+                       </step>\r
+                       <step>\r
+                       <para>Ensure that it is executable.</para>\r
+<screen><userinput>sudo chmod 755 evergreenstart </userinput></screen>\r
+                       </step> \r
+                       <step>\r
+                               <para>Test the script by running it from the command line as the <systemitem class="username">root</systemitem> user.</para>\r
+<screen><userinput>/etc/init.d/evergreenstart restart</userinput></screen>\r
+                               <para>You will also need to restart apache as the <systemitem class="username">root</systemitem> user.</para>\r
+<screen><userinput>/etc/init.d/apache2 restart</userinput></screen>\r
+                       </step> \r
+                       <step>\r
+                       <para>Test the script by running it from the command line as the <systemitem class="username">root</systemitem> user.</para>\r
+<screen><userinput>/etc/init.d/evergreenstart restart</userinput></screen>\r
+                       <para>You will also need to restart apache as <systemitem class="username">root</systemitem>.</para>\r
+<screen><userinput>/etc/init.d/apache2 restart</userinput></screen>\r
+                       </step> \r
+                       <step>\r
+                       <para>Update runlevel defaults of the new evergreenstart service as the <systemitem class="username">root</systemitem>  user:</para>\r
+<screen><userinput>update-rc.d evergreenstart defaults 80 20</userinput></screen>\r
+<note><para>For Evergreen to start properly during a reboot, you will want to ensure that the first number <option>80</option> is lower than the assigned starting priority for Apache so it starts before Apache.  It should also a higher stopping priority <option>20</option> than Apache so it stops after Apache at shutdown.</para></note>\r
+                       </step> \r
+               </procedure>\r
+               <para>For more information on update-rc.d you should review the documentation on this topic for <link xl:href="http://www.debuntu.org/how-to-manage-services-with-update-rc.d">\r
+               Debian</link> or <link xl:href="http://manpages.ubuntu.com/manpages/hardy/man8/update-rc.d.8.html">Ubuntu</link> depending on your distribution of Linux.</para>        \r
        </section>\r
        <section xml:id="backingup">\r
                <title>Backing Up</title>\r