| % |
| % 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. |
| % |
| 2y% Create well-known link to this spot for HTML version |
| \ifpdf |
| \else |
| \HCode{<a name='DUCC_CLI_PROCESS_SUBMIT'></a>} |
| \fi |
| \section{ducc\_process\_submit} |
| \label{sec:cli.ducc-process-submit} |
| \paragraph{Description:} |
| Use {\em ducc\_process\_submit} to submit a Managed Reservation, also known as an |
| {\em arbitrary process} to DUCC. The intention |
| of this function is an alternative to utilities such as {\em ssh}, in order to allow the |
| spawned processes to be fully managed by DUCC. This allows the DUCC scheduler to allocate |
| the necessary resources (and prevent over-allocation), and the DUCC run-time environment |
| to manage process lifetime. |
| |
| If {\em attach\_console} is specified, Stdin, Stderr, and Stdout of the remote |
| process are redirected to the submitting console. It is thus possible to run interactive |
| sessions with remote processes where the resources are managed by DUCC. |
| |
| \paragraph{Usage:} |
| \begin{description} |
| \item[Script wrapper] \ducchome/bin/ducc\_process\_submit {\em options} |
| \item[Java Main] java -cp \ducchome/lib/uima-ducc-cli.jar\\org.apache.uima.ducc.cli.DuccManagedReservationSubmit {\em options} |
| \end{description} |
| |
| \paragraph{Options:} |
| \begin{description} |
| |
| \item[$--$attach\_console] If specified, remote process stdout and stderr are |
| redirected to, and stdin redirected from, the local submitting console. |
| |
| \item[$--$cancel\_on\_interrupt] If specified, the remote process is monitored |
| and will be canceled if the submit command is interrupted, e.g. with CTRL-C. |
| This option always implies $--$wait\_for\_completion. |
| |
| \item[$--$description {[text]}] The text is any string used to describe the process. It is |
| displayed in the Web Server. When specified on a command-line the text usually must be |
| surrounded by quotes to protect it from the shell. |
| |
| \item[$--$debug ] Prints internal debugging information, intended for DUCC developers or |
| extended problem determination. |
| |
| \item[$--$environment {[env vars]}] Blank-delimited list of environment variables and variable |
| assignments. |
| Entries will be copied from the user's environment if just the variable name is |
| specified, optionally with a final '*' for those with the same prefix. |
| If specified, this is used for all DUCC processes in the job. Example: |
| \begin{verbatim} |
| --environment TERM=xterm DISPLAY=:1.0 LANG UIMA_* |
| \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] Prints the usage text to the console. |
| |
| \item[$--$log\_directory {[path-to-log directory]} ] |
| |
| This specifies the path to the directory for the user 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 sub-directory for each process, 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\_executable {[program name]}] This is the full path to a program to be |
| executed. (Required) |
| |
| \item[$--$process\_executable\_args {[argument list]}] This is a list of arguments for |
| {\em process\_executable}, if any. When specified on a command-line the text usually must be |
| surrounded by quotes to protect it from the shell. |
| |
| \item[$--$process\_memory\_size {[size]} ] This specifies the maximum amount of RAM in GB to |
| be allocated to each process. This value is used by the Resource Manager to allocate |
| resources. if this amount is exceeded by a process the Agent terminates the process with a |
| ShareSizeExceeded message. |
| |
| \item[$--$scheduling\_class {[classname]} ] This specifies the name of the scheduling 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 FIXED\_SHARE default is taken from the site class definitions file |
| described \hyperref[subsubsec:class.configuration]{here.} |
| |
| \item[$--$specification, $-$f {[file]} ] All the parameters used to submit a process may be placed |
| in a standard Java properties file. This file may then be used to submit the process |
| (rather than providing all the parameters directory to submit). |
| |
| For example, |
| \begin{verbatim} |
| ducc_process_submit --specification job.props |
| ducc_process_submit -f job.props |
| \end{verbatim} |
| |
| where job.props contains: |
| \begin{verbatim} |
| working_directory = /home/bob/projects |
| environment = AE_INIT_TIME=10000 LD_LIBRARY_PATH=/a/bogus/path |
| log_directory = /home/bob/ducc/logs/ |
| description = Simple Process |
| scheduling_class = fixed |
| process_memory_size = 15 |
| \end{verbatim} |
| |
| \item[$--$suppress\_console\_log] If specified, suppress creation of the log files that |
| normally hold the redirected stdout and stderr. |
| |
| \item[$--$timestamp ] |
| If specified, messages from the submit process are timestamped. This is intended primarily |
| for use with a monitor with --wait\_for\_completion. |
| |
| \item[$--$wait\_for\_completion ] |
| If specified, the submit command monitors the remote process and prints periodic |
| state and progress information to the console. When the process completes, the monitor |
| is terminated and the submit command returns. If the command is interrupted, e.g. with CTRL-C, |
| the request will not be canceled unless $--$cancel\_on\_interrupt is also specified. |
| |
| \item[$--$working\_directory ] This specifies the working directory to be set by the Job |
| Driver and Job Process processes. If not specified, the current directory is used. |
| |
| \end{description} |
| |
| \paragraph{Notes:} |
| |