% 
% Licensed to the Apache Software Foundation (ASF) under one
% or more contributor license agreements.  See the NOTICE file
% distributed with this work for additional information
% regarding copyright ownership.  The ASF licenses this file
% to you under the Apache License, Version 2.0 (the
% "License"); you may not use this file except in compliance
% with the License.  You may obtain a copy of the License at
% 
%   http://www.apache.org/licenses/LICENSE-2.0
% 
% Unless required by applicable law or agreed to in writing,
% software distributed under the License is distributed on an
% "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
% KIND, either express or implied.  See the License for the
% specific language governing permissions and limitations
% under the License.
% 
% Create well-known link to this spot for HTML version
\ifpdf
\else
\HCode{<a name='DUCC_CLI_SERVICES'></a>}
\fi
    \section{ducc\_services}
    \label{sec:cli.ducc-services}

    \paragraph{Description:}

        The ducc\_services CLI is used to manage service registration. It has a number of functions 
        as listed below.
        
        The functions include: 
        \begin{description}
            \item[Register] This registers a service with the Service Manager by saving a service
              specification in the Service Manager's registration area. The specification is
              retained by DUCC until it is unregistered.

              The registration consists primarily of a service specification, similar
              to a job specification. This specification is
              used when the Service Manager needs to start a service instance.  A second properties
              file, the {\em meta properties} for the service, contains additional state and
              management properties.  The registered properties for a service are made available for
              viewing from the DUCC Web Server's \hyperref[sec:ws-service-details]{service details}
              page.
              
            \item[Unregister] This unregisters a service with the Service Manager. When a service is
              unregistered DUCC optionally stops the service instance, if any, and discard the
              saved specification.
              
            \item[Start] The start function instructs DUCC to allocate resources for a service and to
              start it in those resources. The service remains running until explicitly stopped. DUCC
              will attempt to keep the service instances running if they should fail. The start function
              is also used to increase the number of running service instances if desired.
              
            \item[Stop] The stop function stops some or all service instances.
              
            \item[Query] The query function returns detailed information about all known services, both
              registered and otherwise.
              
            \item[Modify] The modify function allows some aspects of a registered service to be updated
              without reregistereing the service. It optionally alters the running service instances to
              conform with the updates.    
        \end{description}
            

    \paragraph{Usage:}
       \begin{description}
          \item[Script wrapper] \ducchome/bin/ducc\_services {\em options}
          \item[Java Main]      java -cp \ducchome/lib/uima-ducc-cli.jar org.apache.uima.ducc.cli.DuccServiceApi {\em options}
          \end{description}
          
          The ducc\_services CLI requires one of the verbs listed above as the first argument. Other arguments are determined
          by the verb.

    \paragraph{Options:}

    \subsection{Common Options}
        These options are common to all of the service verbs:
        \begin{description}
           \item[$--$debug ]          
             Prints internal debugging information, intended for DUCC developers or extended problem determination.                    
           \item[$--$help]
             Prints the usage text to the console. 
        \end{description}
        
    \subsection{ducc\_services --register Options}
    \label{subsec:cli.ducc-services.register}
       The {\em register} function submits a service specification to DUCC.  DUCC stores this 
       information until it is {\em unregistered}.  Once registered, a service may be
       started, stopped, etc.

       The {\em register} options are logically divided into two classes:
       \begin{enumerate}
         \item ``Meta'' options which define how the Service Manager manages the service, and
         \item Options which describe the service itself.  These optinos are analagous to
           those used to submit a job.
       \end{enumerate}

       The ``meta'' options include:
       \begin{description}
           \item[$--$register {[specification file] [options]}] The specification file is optional.

           \item[$--$autostart {[true or false]}] This indicates whether to register the service as
             an autostarted service.  If not specified, the default is {\em false}.
             
           \item[$--$instances {[n]}] This specifies the number of instances to start when the service
             is started.  If not specified, the default is 1.
                         
       \end{description}

       The options describing the service include:
    \begin{description}

        \item[$--$classpath] The CLASSPATH used for the service, if the service is a
          \hyperref[sec:services.types]{UIMA-AS services}.  If not specified, the CLASSPATH used
          by the {\em ducc\_services} command is used.

        \begin{sloppypar}
        \item[$--$classpath\_order {[user-before-ducc $|$ ducc-before-user]} ] When DUCC deploys a service,
          set the user-supplied CLASSPATH before DUCC-supplied CLASSPATH, or the reverse. 
          The default is ducc-before-user. This is
          only valid for  \hyperref[sec:services.types]{UIMA-AS services}.
        \end{sloppypar}
        
        \item[$--$debug ]
          Enable debugging messages. This is primarily for debugging DUCC itself. 
          
        \item[$--$description {[text]}] The text is any quoted string used to describe the job. It is
          displayed in the Web Server.

          Note: When used as a CLI option, the description string must usually be quoted to protect
          it from the shell.
    
        \item[$--$environment {[env vars]}] Blank-delimited list of environment variable
          assignments for the service. Example:
          \begin{verbatim}
--environment TERM=xterm DISPLAY=:1.0
          \end{verbatim}

          \begin{sloppypar}
          Additional entries may be copied from the user's environment based on the setting of
          ducc.submit.environment.propagated in the global DUCC configuration ducc.properties.
        \end{sloppypar}
        
          Note: When used as a CLI option, the environment string must usually be
          quoted to protect it from the shell.
          
        \item[$--$help ] This prints the usage text to the console.

        \item[$--$jvm {[path-to-java]}] This specifies the JVM to use for 
          \hyperref[sec:services.types]{UIMA-AS services}. If not
          specified, the same JVM used by the Agents is used.  

          Note: The path must be the full path the the Java executable (not 
          simply the JAVA\_HOME environment variable.).  Example:
\begin{verbatim}
--jvm /share/jdk1.6/bin/java 
\end{verbatim}


        \item[$--$process\_jvm\_args {[list]} ]        
          This specifes extra JVM arguments to be provided to the server process for
          \hyperref[sec:services.types]{UIMA-AS services}. It is a blank-delimited 
            list of strings. Example: 
\begin{verbatim}
--process_jvm_args -Xmx100M -Xms50M
\end{verbatim}

          Note: When used as a CLI option, the argument string must usually be quoted to protect
          it from the shell.
    
          \item[$--$log\_directory {[path-to-log directory]}] This specifies the path to the directory for
            the individual service instance logs. If not specified, the default is \$HOME/ducc/logs. Example:
\begin{verbatim}
--log_directory /home/bob 
\end{verbatim}
        
        Within this directory DUCC creates a subdirectory for each job, using the numerical 
        ID of the job. The format of the generated log file names as described
        \hyperref[chap:job-logs]{here}.
        
        Note: Note that $--$log\_directory specifies only the path to a directory where 
        logs are to be stored. In order to manage multiple processes running in multiple 
        machines DUCC, sub-directory and file names are generated by DUCC and may 
        not be directly specified. 

      \item[$--$process\_DD {[DD descriptor]}] 
        This specifies the UIMA Deployment Descriptor for \hyperref[sec:services.types]{UIMA-AS services}.

      \item[$--$process\_executable {[program-name]}] For \hyperref[sec:services.types]{CUSTOM
          services}, this specifies the full path of the program to execute.

      \item[$--$process\_executable\_args {[list-of-arguments]}] For \hyperref[sec:services.types]{CUSTOM
          services}, this specifies the program arguments, if any.

      \item[$--$process\_memory\_size {[size]}] This specifies the maximum amount of RAM in GB to be
        allocated to each Job Process.  This value is used by the Resource Manager to allocate
        resources. 

      \item[$--$instance\_failures\_limit {[integer]}] 
        This specifies the maximum number of consecutive individual service instance failures that are to be 
        tolerated before stopping the service. The default is five (5). If the instance is successfully
        restarted, the count is reset to zero (0), so that the occasional process failure does not cause
        the entire service to be terminated.
        
      \item[$--$scheduling\_class {[classname]}] This specifies the name of the scheuling class the RM
        will use to determine the resource allocation for each process. The names of the classes are
        installation dependent. If not specified, the default is taken from the global DUCC
        configuration \hyperref[sec:ducc.properties]{ducc.properties.}

      \item[$--$service\_dependency{[list]}] This specifies a blank-delimited list of services the job
        processes are dependent upon. Service dependencies are discussed in detail
        \hyperref[sec:service.endpoints]{here}. Example:
\begin{verbatim}
--service_dependency UIMA-AS:Service1:tcp:node682:61616 UIMA-AS:OtherSvc:tcp:node123:123 
\end{verbatim}

        Note: When used as a CLI option, the list must usually be
        quoted to protect it from the shell.
          

      \item[$--$service\_linger {[milliseconds]}] This is the time in milliseconds to wait after the last
        referring job or service exits before stopping a non-autostarted service.

      \item[$--$service\_ping\_arguments {[argument-string]}] This is any arbitrary string
        that is passed to the {\em init()} method of the service pinger.  The contents of
        the string is entirely a function of the specifici service.  If not specified,
        a {\em null} is passed in.

        Note: When used as a CLI option, the string must usually be
        quoted to protect it from the shell, if it contains blanks.

        The build-in default UIMA-AS pinger supports an argument string of the following form
        (with NO embedded blanks):
\begin{verbatim}
     queue_threshold=nn,window=mm,broker_jmx_port=pppp,meta_timeout=tttt
\end{verbatim}
        
        The keywords in the string have the following meaning:
        \begin{description}
          \item[queue\_threshold=nn] If the depth of the ActiveMQ queue for the service exceeds
            this value for some period of time, the health of the service is marked ``poor''.
            If omitted, the value is 0, and no quality measurement is made.
          \item[window=ww] This defines a ``window'' over which the queue threshold is measured.
            the value is the number of consecutive measurements over which the queue depth must
            exceed the threshold.  If omitted, the window size is 0.
          \item[broker\_jmx\_port=pppp] This is the JMX port for the service's broker.  If not
            specified, the default of 1099 is used.  This is used to gather ActiveMQ statistics
            for the service.
          \item[meta\_timeout=tttt] This is the time, in milliseconds, to wait for a response
            to UIMA-AS {\em get-meta}.  If not specified, the default is 5000 milliseconds.
        \end{description}
      
      \item[$--$service\_ping\_class {[classname]}] This is the Java class used to ping a service. 

        This parameter is required for CUSTOM services.

        This parameter may be specified for UIMA-AS services; however, DUCC supplies a default
        pinger for UIMA-AS services.

      \begin{sloppypar}  
      \item[$--$service\_ping\_classpath {[classpath]}] If {\em service\_ping\_class} is specified,
        this is the classpath containing service\_custom\_ping class and dependencies.  If not
        specified, the Agent's classpath is used (which will generally be incorrect.)
      \end{sloppypar}
      
      \item[$--$service\_ping\_dolog {[boolean]}] If specified, write pinger stdout and stderr
        messages to a log, else suppress the log. See \hyperref[sec:service.pingers]{Service Pingers}
        for details.

      \item[$--$service\_ping\_jvm\_args {[string]}] If 
        {\em service\_ping\_class} is specified, these are the arguments 
        to pass to jvm when running the pinger. The arguments are specified as a blank-delimited
        list of strings.  Example:
\begin{verbatim}
--service_ping_jvm_args -Xmx400M -Xms100M
\end{verbatim}
        
        Note: When used as a CLI option, the arguments must usually be
        quoted to protect them from the shell.

      \item[$--$service\_ping\_timeout {[time-in-ms]}] This is the time in milliseconds to wait for a
        ping to the service.  If the timer expires without a response the ping is ``failed''. After
        a certain number of consecutive failed pings, the service is considered ``down.''  See
        \hyperref[sec:service.pingers]{Service Pingers} for more details.

      \item[$--$service\_request\_endpoint {[string]}] This specifies the expected service id.  
        \begin{sloppypar}
          This string is optional for UIMA-AS services; if specified, however, it must be of the
          form {\tt UIMA-AS:queue:broker-url}, and both the queue and broker must match those specified in the
          service DD specifier.
        \end{sloppypar}

        If the service is CUSTOM, the endpoint is required, and must be of the form
        {\tt CUSTOM:string} where the contents of the string are determined by the service.

      \item[$--$specification, $-$f {[file]}] All the parameters used to register a service may be placed in a
        standard Java properties file.  This file may then be used to register the service (rather than
        providing all the parameters directly).
        For example, 

\begin{verbatim}
ducc_services --register svc.props 
\end{verbatim}
        
        where the svc.props contains: 

\begin{verbatim}
environment         = AE_INIT_TIME=5000 AE_INIT_RANGE=1000 INIT_ERROR=0
description         = Test Service 3
process_jvm_args    = -DdefaultBrokerURL=tcp://agent86:61616
classpath           = /home/bob/lib/app.jar
process_memory_size = 15
working_directory   = /home/bob/services
process_DD          = /home/bob/services/service.xml
scheduling_class    = fixed
service_dependency  =  UIMA-AS:FixedSleepAE_4:tcp://agent86:61616
\end{verbatim}
        
        \item[$--$working\_directory {[directory-name]}]
          This specifies the working directory to be set for the service processes. 
          If not specified, the current directory is used.
    \end{description}


    \subsection{ducc\_services --start Options}

    The start function instructs DUCC to allocate resources for a service and to start it in those
    resources. The service remains running until explicitly stopped. DUCC will attempt to keep the
    service instances running if they should fail. The start function is also used to increase the
    number of running service instances if desired.
    
       \begin{description}
       \item[$--$start {[service-id or endpoint]}] This indicates that a service is to be started. The service id
         is either the numeric ID assigned by DUCC when the service is registered, or the service
         endpoint string.  Example:
\begin{verbatim}
ducc_services --start 23 
ducc_services --start UIMA-AS:Service23:tcp://bob.com:12345 
\end{verbatim}
         
       \item[$--$instances {[integer]}] This is the number of instances to start. If omitted, sufficient
         instances to match the registered number are started. If more than the registered number of
         instances is running this command has no effect.

         If the number of instances is specified, the number is added
         to the currently number of running instances. Thus if five instances are running and
\begin{verbatim}
         ducc_services --start 33 --instances 5
\end{verbatim}
         is issued, five more service instances are started for service 33 for a total of ten,
         regardless of the number specified in the registration. The registry is updated if the
         {\em --update} option is also specified. Examples:
\begin{verbatim}
ducc_services --start 23 --intances 5 
ducc_services --start UIMA-AS:Service23:tcp://bob.com:12345 --instances 3 --update 
\end{verbatim}

       \item[$--$update]If specified, the registry is updated to the total number of started
         instances.  Example:
\begin{verbatim}
ducc_services --start UIMA-AS:Service23:tcp://bob.com:12345 --instances 3 --update 
\end{verbatim}
       \end{description}

    \subsection{ducc\_services --stop Options}
    The stop function instructs DUCC to stop some number of service instances. If no specific number
    is specified, all instances are stopped.

    \begin{description}

  \item[$--$stop {[service-id or endpoint]}] This specifies the service to be stopped. The service id
         is either the numeric ID assigned by DUCC when the service is registered, or the service
         endpoint string. Example:
\begin{verbatim}
ducc_services --stop 23 
ducc_services --stop UIMA-AS:Service23:tcp://bob.com:12345 
\end{verbatim}
         
       \item[$--$instances {[integer]}] This is the number of instances to stop. If omitted, all
         instances for the service are stopped.  If the number of instances is specified, then only
         the specified number of instances are stopped. Thus if ten instances are running for a
         service with numeric id 33 and
\begin{verbatim}
ducc_services --stop 33 --instances 5
\end{verbatim}
         is issued, five (randomly selected) service instances are stopped for
         service 33, leaving five running.  The registry is updated if the {\em --update} option is
         specified. The registered number of instances is never reduced to zero even if the number of
         running instances is reduced to zero.

         Example: 
\begin{verbatim}
ducc_services --stop 23 --intances 5 
ducc_services --stop UIMA-AS:Service23:tcp://bob.com:12345 --instances 3  
\end{verbatim}

       \item[$--$update] If specified, the registry is updated to the total number of instances
         remaining, but is never reduced below one (1). Example: 
\begin{verbatim}
ducc_services --stop UIMA-AS:Service23:tcp://bob.com:12345 --instances 3 --update
\end{verbatim}

    \end{description}

    \subsection{ducc\_services --modify Options}
    The modify function dynamically updates some of the attributes of a registered service. 
    
    \begin{description}
        \item[$--$modify {[service-id or endpoint]}]  This identifies the service to modify. The service id is either
          the numeric ID assigned by DUCC when the service is registered, or the service endpoint
          string.  Example:
\begin{verbatim}
ducc_services --modify 23 --instances 3 
ducc_services --modify UIMA-AS:Service23:tcp://bob.com:12345 --intances 2 
\end{verbatim}

        \item[ --instances {[integer]}] This updates the number of services instances that are
          started when the service is started.  Only the registration is updated. If the {\em $--$activate}
          option is also specified, running instances are stopped or started as needed to match the
          new number.

          Example: 
\begin{verbatim}
ducc_services --modify 23 --intances 5 
ducc_services --modify UIMA-AS:Service23:tcp://bob.com:12345 --instances 3 --activate 
\end{verbatim}

        \item[ --activate {[integer]}] When specified, the number of running service instances is
          increased or decreased to match the newly specified number.

          Example: 
\begin{verbatim}
ducc_services --modify 23 --intances 5 
ducc_services --modify UIMA-AS:Service23:tcp://bob.com:12345 --instances 3 --activate 
\end{verbatim}

        \item[ --autostart {["true" or "false"]}] This changes the autostart property for the
          registered services. When set to "true", the service is started automatically when the
          DUCC system is started.  If the service is not currently started, it will now start
          with the registered number of instances.  If the service is running, the instances
          remain running.

          One way to think of this is: if {\em autostart} is true, DUCC will attempt to keep
          the registered number of instances running at all times.  If {\em autostart} is
          false, all instance start and stop is manual.
          Example: 
\begin{verbatim}
ducc_services --modify UIMA-AS:Service23:tcp://bob.com:12345 --autostart false 
\end{verbatim}
        \end{description}

    \subsection{ducc\_services --query Options}
    The query function returns details about all known services of all types and classes, including 
    the DUCC ids of the service instances (for submitted and registered services), the DUCC ids of 
    the jobs using each service, and a summary of each service's queue and performance statistics, 
    when available. 
    
    All information returned by {\em ducc\_services $--$query} is also available via the
    \hyperref[ws:services-page]{Services Page} of the Web Server as well as the DUCC Service API (see 
    the JavaDoc).

    \begin{description}
    \item[$--$query {[service-id or endpoint]}] This indicates that a service is to be stopped. The
      service id is either the numeric ID assigned by DUCC when the service is registered, or the
      service endpoint string.

      If no id is given, information about all services is returned. 

      Below is a sample service query.

      The service with endpoint {\tt UIMA-AS:FixedSleepAE\_5:tcp://bobmach:61617} is a 
      registered service, whose registered numeric id is 2. It was registered by bob for two instances and 
      no autostart. Since it is not autostarted, it will be terminated when it is no longer used. It 
      will linger for 5 seconds after the last referencing job completes, in case a subsequent job 
      that uses it enters the system (not a realistic linger time!). It has two active
      instances whose DUCC Ids are 9 and 5. It is currently used (referenced) 
      by DUCC jobs 1 and 5. 


\begin{verbatim}

Service: UIMA-AS:FixedSleepAE_5:tcp://bobmach291:61617 
   Service Class : Registered as ID 2 Owner[bob] instances[2] linger[5000] 
   Implementors : 9 8 
   References : 1 5 
   Dependencies : none 
   Service State : Available 
   Ping Active : true 
   Autostart : false 
   Manual Stop : false 
   Queue Statistics: 
Consum Prod Qsize minNQ maxNQ expCnt inFlgt  DQ  NQ Disp 
    52   44     0     0     3      0      0 402 402  402 
\end{verbatim}
    \end{description}
    \paragraph{Notes:}

