NAME

webjob-jqd-create-job - Add a job to the specified job queues.

SYNOPSIS

webjob-jqd-create-job [-h] [-c command-file] [-e queue[,queue[...]]] [-j job-group] [-m mode] [-o option[,option[,...]]] [-p priority] [-S webjob-server-home] [-T tag] -f file -i queue[,queue[...]] -t {p|parallel|s|serial}

DESCRIPTION

This utility reads/validates a job file, conditionally copies the corresponding command/signature files to the POUND, and then adds the job to the specified queues. A job file is simply a text file that contains key/value pairs for the following properties:

Command (required)

Specifies the actual (i.e., on-disk) name of the target program.

CommandAlias (required)

Specifies the actual name of the target program except when server-side GET hooks are enabled. If GET hooks are not in use, this value should be the same as the value for Command.

CommandLine (required)

Specifies the actual command line to execute including any arguments. This value has the following syntax:

    <CommandAlias> [arguments]

As stated above, the values for Command and CommandAlias differ only in the case where server-side GET hooks are enabled, which is beyond the scope of this man page.

CommandMd5 (conditionally required)

Specifies the MD5 hash of the target program. This key/value pair is required if the UseExistingPoundFiles option is set. Otherwise, it should be omitted.

CommandSha1 (conditionally required)

Specifies the SHA1 hash of the target program. This key/value pair is required if the UseExistingPoundFiles option is set. Otherwise, it should be omitted.

Comment (optional)

Specifies a comment that describes the job or provides some other relevant information. Note that the value for this property must fit on a single line.

The following is an example job file for a the testenv command, which takes no arguments:

    --- testenv.job ---
    Command=testenv
    CommandAlias=testenv
    CommandLine=testenv
    Comment=This is a job to check various environment variables.
    --- testenv.job ---

Note that the queued job file will be assigned file permissions according to the -m option and ownership according to the 'ApacheOwner' and 'WebJobGroup' properties located in the server's main config file (typically /var/webjob/config/server.cfg). Also, if the queued job file is not writable by nph-webjob.cgi, then that instance of the script will freeze the associated queue and abort, so it's important that queued job file permissions and ownerships are set correctly.

OPTIONS

-c command-file

Specifies the command file. This is a relative or full path to the actual binary/script being queued. By default, the command file is derived from the job file (assuming it has an extension of '.job'). See the -f option for details about the job file.

-e queue[,queue[...]]

Specifies one or more queues or queue groups that are to be excluded from the operation. Note that group names must be prefixed with '%'. For example, a group called 'test' must be specified as '%test'.

-f job-file

Specifies the job file. The command contained in this file will be assigned to each of the specified queues. If the job file has an extension of '.job', the extension will be removed and the resulting value is assumed to be the path/name of the command file. See the -c option for details about the command file.

-h

This is a legacy option, and it is being phased out. Please use the PutJobOnHold option instead (see -o).

-i queue[,queue[...]]

Specifies one or more queues or queue groups that are to be included in the operation. Note that group names must be prefixed with '%'. For example, a group called 'test' must be specified as '%test'.

-j job-group

Specifies the name of the group to which this job belongs. Note that jobs are assigned to the 'void' group by default.

-m mode

Specifies the job file's default mode (i.e., permissions). The default mode is 0644.

-o option,[option[,...]]

Specifies the list of options to apply. Currently, the following options are supported:

OverwritePoundFiles

Indicates that existing files in the POUND are to be overwritten. Typically, this is not necessary since the POUND's directory structure is based on hash values. However, there are cases where this option is useful (e.g., updating signature files or repairing files that have become corrupt since being added to the POUND).

PutJobOnHold

Indicates that the job is to be created and placed in the 'hold' state. Jobs in this state will appear in queue listings, but they are not visible to queue workers. By default, all jobs are initially placed in the 'todo' state, which means they are visible to queue workers.

UseExistingPoundFiles

Indicates that the necessary files already exist in the POUND and only they may be used when creating the job. If the necessary files do not exist, the script will abort. To use this option, the job file must include the CommandMd5 and CommandSha1 key/value pairs.

UseZeroNonce

Typically, a pseudo random nonce is used when creating tags to help prevent name collisions. This option suppresses that behavior, and uses a value of zero instead.

-p priority

Specifies the job priority. Priorities can be in the range [0-99] with 0 being the highest priority. The default priority is 50.

-S webjob-server-home

Specifies the WebJob Server home directory. The default value is /var/webjob.

-T tag

Specifies a particular tag that is to be assigned to the job. This can be used to repeat a partially failed job assignment. For example, you could have a situation where 9/10 jobs queue up fine, but one fails. In that case, you may want to queue the final job up using the tag that was generated on the previous execution. The format of the tag is as follows:

  DD_DDDDDDDDDD_DDDDDD_HHHHHHHH

where 'DD', 'DDDDDDDDDD', and 'DDDDDD' are decimal numbers, and 'HHHHHHHH' is a hex number. The first number, 'DD', represents the job priority. The second and third numbers, 'DDDDDDDDDD' and 'DDDDDD', represent the time in time in seconds and microseconds. The fourth number, 'HHHHHHHH', represents a pseudo random nonce.

-t {p|parallel|s|serial}

Specifies the job type. Parallel jobs are executed in the background, and serial jobs are executed in the foreground.

AUTHOR

Klayton Monroe

SEE ALSO

nph-webjob.cgi(1), webjob-jqd-delete-job(1), webjob-jqd-list-jobs(1), webjob-setup-server(1)

LICENSE

All documentation and code are distributed under same terms and conditions as WebJob.