5.2 Command Line Flags, or Options, and Positional Parameters

This topic identifies the individual command line flags, or options, and positional parameters recognized and/or required by Nitro.

In this topic:

• 5.2.1 Flags
• 5.2.2 Options
• 5.2.3 Positional Parameters
• 5.2.4 Command Line Options per Nitro Mode

5.2.1 Flags

• Disable Affinity – Instructs a worker that it should not track and set the task's affinity.

  

  This option overrides --disable-affinity in the nitro.cfg file.

  --disable-affinity

• Linger – Tells Nitro to keep running after the initial tasks have completed. The <timeout> specifies the number of seconds that must pass after the last completed task before Nitro closes (shuts down). A <timeout> value of -1 indicates an indefinite period of time; Nitro will not close until a signal is given to close.

  --linger <timeout>

• Run Local Worker – Runs a local worker on the coordinator's node.

  --run-local-worker

• Trust Workers – Allows any worker to attach to Nitro and accept workload. Without this flag, the coordinator will only connect workers that were specified with the ‑‑workers, ‑‑workers‑file, ‑‑key, or ‑‑key‑file command line option.

  --trust-workers

5.2.2 Options

• Mode – Required command line parameter that indicates the role (coord/worker) of Nitro when started on a node.

  --mode=[coord | worker]

• Coordinator Host – Specifies the coordinator to connect to when Nitro is running in worker mode (‑‑mode=worker).

  --coord <HOST[:PORT]>

• Session Key – Specifies a session key that can be used to authenticate workers to the coordinator. The session key must be provided on the workers and coordinator command lines. Any worker reporting in to the coordinator will be required to provide this key to be able to connect and receive workload. The session key is any string that does not contain spaces or any characters which the shell will interpret.

  --key <keyvalue>

• Key File – File containing a passphrase that can be used to authenticate workers to a coordinator. If the file contains newline or tab characters, these will be removed from the passphrase.

  --key-file <file>

• Worker Hosts – "+"-separated list of the host names of the worker hosts the job scheduler allocated to the Nitro job for its exclusive use.

  --workers <hostlist>

• Worker Hosts File – File containing a list of the host names, one per line, the job scheduler allocated to the Nitro job for its exclusive use.

  --workers-file <filename>

• Name – Name the worker uses to reference itself when communicating with the coordinator. For the coordinator, this is the name to which the workers will connect. If not specified, Nitro defaults to the node's host name.

  

  The name supplied to the coordinator via ‑‑workers or ‑‑workers‑file must match ‑‑name. If using ‑‑trust‑workers, ‑‑key, or ‑‑key‑file, any unique value can be used for ‑‑name. Workers' names must be unique within a coordinator group.

  --name <name>

• Port Base – Base port number for port assignments (default 47000); used to override first port assignment by Nitro process. Valid range of ports is 47000-65535.

  Each Nitro coordinator process requires four ports. A coordinator process will bind a range of four ports starting with the start port specified by this option as the starting point for port assignments.

  -p <port>

  --port1 <port>

• Port File – File name that the coordinator should use to contain the first port number used by the coordinator. This also indicates that the coordinator should do a port search to find the first set of available ports. If the coordinator cannot find an available port, and when the coordinator closes, "closed" will be written to the file so that workers being started after the coordinator has closed can immediately close.

  The file name argument is optional, and if not specified, defaults to a file in the job directory named ".coord_<job id>.port". If supplied, the file name argument must be in the form --arg=<value>, not --arg <value> (with a space between).

  --port-file=[<file_name>]

• Thread Count – The quantity of threads the Nitro workers should use when executing tasks. This option is mutually-exclusive with the Thread Ratio option.

  If this option and the Thread Ratio option are not given, a worker uses one task launch thread per OS core to which it is pinned.

  The primary reason for this option is to explicitly specify a task-launch thread count for Nitro running a specific single application, usually on homogeneous nodes.

  --thread-count <num>

• Thread Ratio – The ratio of task launch threads-to-OS "cores" the Nitro workers should use when creating task launch threads. This option is mutually exclusive with the Thread Count option.

  If this option and the Thread Count option are not given, the ratio is "1.0", meaning a worker uses one task launch thread per OS core to which it is pinned.

  Ratio is a positive real number (e.g., 1.5, 0.5, etc) that when multiplied with the count of OS cores to which a worker is pinned yields a count of the task launch threads it will use. The worker rounds the count to the nearest integer, with a minimum value of 1.

  The primary reason for this option is to allow a user to over-subscribe or under-subscribe the task-launch thread count appropriately relative to the OS core count of heterogeneous nodes (e.g., 1.5 means 6 threads for a quad-core node and 24 threads for a 16-core node).

  --thread-ratio <ratio>

• Assignment Size – The quantity of tasks the Nitro coordinator should pass to a Nitro worker at one time; default is 350, maximum value is 1000. Alternatively, you can specify an assignment size of 0; allowing the coordinator to automatically determine the assignment size based on the assignment duration.

  

  This option overrides the --assignment-size setting in the nitro.cfg file.

  --assignment-size <num>

• Job Directory – Specifies the path for the directory where Nitro will place its Job Progress Log and Completed Task Log files.

  --job-dir <path>

• Job ID – Specifies the job ID for a specific Nitro run. The job ID may be used to create the job directory and certain file paths.

  --job-id <jobID>

• Coordinator Threads – Indicates to the coordinator how many threads to reserve for the coordinator when allocating cores to a local worker (when using "‑‑run-local‑worker" on the coordinator command line). Default is 2. Adaptive Computing recommends setting the <count> value to 1 if all jobs will use less than 20 nodes and setting the <count> value to 4 if the jobs require a large number of nodes (greater than 50) to run.
  

  This option overrides the --coord-threads setting in the nitro.cfg file.

  --coord-threads <count>

• Task Environment – Specifies the environment variables to set in the task's execution environment. This is used by the worker but is also needed on the coordinator's command line if running a local worker. Multiple values can be specified by separating name/value pairs with a comma.

  --task-env <ENVVARNAME=value[,...]>

• Debug Log File – The path for the optional "debug log" file the Nitro coordinator can produce. If the path is not defined, the coordinator will use the default path $NITROJOBDIR/nitro_$NITROJOBID-hostname_pid.log.

  --logfile <path>

• Debug Log Level – The level of debug log information the Nitro coordinator will output when tracing/logging. The default is "3" (information). The highest level allowed is "7" (debug).

  --loglevel <num>

5.2.3 Positional Parameters

• Task File Name – Path of text file containing Nitro task definitions. This must be the last parameter on the coordinator's command line.

  path

5.2.4 Command Line Options per Nitro Mode

The table that follows identifies which command line options Nitro uses in worker or coordinator mode. Some command line options are used in both modes and are listed in this table in the "Both" row.

Nitro Mode	Command Line Option
Coordinator	‑‑assignment‑size ‑‑coord‑threads (if using ‑‑run‑local‑worker with the coordinator) ‑‑port1 ‑‑run‑local‑worker ‑‑trust‑workers ‑‑workers ‑‑workers‑file ‑‑key-file
Worker	‑‑coord ‑‑disable‑affinity (if not using ‑‑run‑local‑worker with the coordinator) ‑‑name ‑‑task‑env (if not using ‑‑run‑local‑worker with the coordinator) ‑‑thread‑count (if not using ‑‑run‑local‑worker with the coordinator) ‑‑thread‑ratio (if not using ‑‑run‑local‑worker with the coordinator)
Both	‑‑disable‑affinity (if using ‑‑run‑local‑worker with the coordinator) ‑‑job‑dir ‑‑job‑id ‑‑key ‑‑linger ‑‑logfile ‑‑loglevel ‑‑mode ‑‑port‑file ‑‑task‑env (if using ‑‑run‑local‑worker with the coordinator) ‑‑thread‑count (if using ‑‑run‑local‑worker with the coordinator) ‑‑thread‑ratio (if using ‑‑run‑local‑worker with the coordinator)

© 2017 Adaptive Computing