.rn '' }` ''' $RCSfile$$Revision$$Date$ ''' ''' $Log$ ''' .de Sh .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp .if t .sp .5v .if n .sp .. .de Ip .br .ie \\n(.$>=3 .ne \\$3 .el .ne 3 .IP "\\$1" \\$2 .. .de Vb .ft CW .nf .ne \\$1 .. .de Ve .ft R .fi .. ''' ''' ''' Set up \*(-- to give an unbreakable dash; ''' string Tr holds user defined translation string. ''' Bell System Logo is used as a dummy character. ''' .tr \(*W-|\(bv\*(Tr .ie n \{\ .ds -- \(*W- .ds PI pi .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch .ds L" "" .ds R" "" ''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of ''' \*(L" and \*(R", except that they are used on ".xx" lines, ''' such as .IP and .SH, which do another additional levels of ''' double-quote interpretation .ds M" """ .ds S" """ .ds N" """"" .ds T" """"" .ds L' ' .ds R' ' .ds M' ' .ds S' ' .ds N' ' .ds T' ' 'br\} .el\{\ .ds -- \(em\| .tr \*(Tr .ds L" `` .ds R" '' .ds M" `` .ds S" '' .ds N" `` .ds T" '' .ds L' ` .ds R' ' .ds M' ` .ds S' ' .ds N' ` .ds T' ' .ds PI \(*p 'br\} .\" If the F register is turned on, we'll generate .\" index entries out stderr for the following things: .\" TH Title .\" SH Header .\" Sh Subsection .\" Ip Item .\" X<> Xref (embedded .\" Of course, you have to process the output yourself .\" in some meaninful fashion. .if \nF \{ .de IX .tm Index:\\$1\t\\n%\t"\\$2" .. .nr % 0 .rr F .\} .TH WEBJOB 1 "WebJob 1.6.0" "1/Jun/2006" "WebJob Documentation" .UC .if n .hy 0 .if n .na .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .de CQ \" put $1 in typewriter font .ft CW 'if n "\c 'if t \\&\\$1\c 'if n \\&\\$1\c 'if n \&" \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 '.ft R .. .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2 . \" AM - accent mark definitions .bd B 3 . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds ? ? . ds ! ! . ds / . ds q .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10' . ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' . ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#] .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u' .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u' .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#] .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E .ds oe o\h'-(\w'o'u*4/10)'e .ds Oe O\h'-(\w'O'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds v \h'-1'\o'\(aa\(ga' . ds _ \h'-1'^ . ds . \h'-1'. . ds 3 3 . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE . ds oe oe . ds Oe OE .\} .rm #[ #] #H #V #F C .SH "NAME" \fBWebJob\fR \- Download and execute a program over HTTP/HTTPS .SH "SYNOPSIS" \fBwebjob\fR \fB{\-e|--execute}\fR \fB{\-f|--file}\fR \fBconfig\fR \fBprogram\fR \fB[options]\fR .PP \fBwebjob\fR \fB{\-h|--hashsum}\fR \fB{\-t|--type}\fR \fBdigest\fR \fBfile\fR .PP \fBwebjob\fR \fB{\-v|--version}\fR .PP Note: Command line arguments are position dependent, and argument snuggling (e.g., \*(L'\-ef\*(R' or \*(L'\-ht') is not supported. All arguments and their values (if any) must be separated by whitespace. However, any \fBoptions\fR associated with the specified \fBprogram\fR are not bound by these restrictions. Instead, they are bound to the argument syntax for the specified \fBprogram\fR. .SH "DESCRIPTION" \fBWebJob\fR downloads and executes a \fBprogram\fR in one unified operation. \fBWebJob's\fR runtime behavior is controlled through a config file identified by the \fB--file\fR argument. Among other things, this file identifies a Web resource willing to satisfy \fBWebJob\fR GET requests. Once initialized, \fBWebJob\fR downloads the target \fBprogram\fR, stores it in on the local file system, and executes it in a sub-process. The \fBoptions\fR, if any, are bound to the target \fBprogram\fR at invocation. By default, any output generated by the target \fBprogram\fR is directed to stdout/stderr. However, output may also be directed to a Web resource through a \fBWebJob\fR PUT request. When compiled with OpenSSL, \fBWebJob\fR supports HTTPS requests and certificate authentication. .PP \fBWebJob's\fR GET/PUT requests may be bound to any available outbound port. This increases the likelihood that distant Web resources can be reached in spite of firewalls and filtering routers. .PP \fBWebJob\fR is roughly split into three stages: GET, RUN, and PUT. Each stage provides an independent timer. In the event that a given stage doesn't complete within the alloted time, \fBWebJob\fR will attempt to abort gracefully. A timeout value of zero means there is no time limit. .PP \fBWebJob\fR also has the ability to compute a message digest of a specified file or stdin. This is useful in situations where the downloaded executable needs to compute a hash, but the target platform lacks the necessary hashing tools. .SH "MODES OF OPERATION" The modes of operation described in this section are mutually exclusive. In other words, only one mode may be specified per invocation. .Ip "\fB{\-e|--execute}\fR \fB{\-f|--file}\fR \fBconfig\fR \fBprogram\fR \fB[options]\fR" 5 Use \fBconfig\fR file settings to download and execute the specified \fBprogram\fR. The \fBconfig\fR file, as specified by the \fB--file\fR argument, may be the name of a regular file or \*(L'\-\*(R' which indicates that configuration information is to be read from stdin. Note: Path information in the \fBprogram\fR argument is not allowed. The \fBoptions\fR, if any, are bound to the target \fBprogram\fR at invocation. The various \fBconfig\fR file controls and syntax rules are described in the \s-1CONFIGURATION\s0 \s-1CONTROLS\s0 section of this document. .Ip "\fB{\-h|--hashsum}\fR \fB{\-t|--type}\fR \fBdigest\fR \fBfile\fR" 5 Use \fBdigest\fR algorithm, as specified by the \fB--type\fR argument, to compute a hash of \fBfile\fR. If \fBfile\fR is specified as \*(L'\-\*(R', then input will be read from stdin. Currently, the following algorithms are supported: \s-1MD5\s0, \s-1SHA1\s0, and \s-1SHA256\s0. The value for this option is not case sensitive. .Ip "\fB{\-v|--version}\fR" 5 Display version information and exit. .SH "CONFIGURATION CONTROLS" This section describes the various controls that \fBWebJob\fR recognizes. In general, controls either shape runtime behavior or provide information needed by the application to perform a specific function. Controls and their values, one pair/line, are written to a file having the following format. .PP .Vb 1 \& = .Ve All controls are case insensitive, but, in general, their values are not. Comments may occur anywhere on a given line, and must begin with a pound character (i.e. \*(L'#'). In any given line, all text to the right of the first comment will be ignored. White space surrounding controls and values is ignored. .Sh "\s-1CONTROL\s0 \s-1DESCRIPTIONS\s0" This section describes each control that may be specified, defines what values it may have, and states which modes of operation recognize the control. .Ip "\fBClientId\fR: " 5 Applies to \fBexecute\fR. .Sp \fBClientId\fR is required. It defines the identity of the client for which the \s-1GET/PUT\s0 requests are being made. Typically, the \fBClientId\fR and \fBURLUsername\fR are the same when basic authentication is enabled. However, this is not a requirement. .Ip "\fBDsvCertificateTree\fR: " 5 Applies to \fBexecute\fR. .Sp \fBDsvCertificateTree\fR is optional. This control specifies a directory that contains one or more \s-1PEM\s0\-encoded certificates whose public keys may be used to verify the payload's signature -- invalid and non-\s-1PEM\s0\-encoded files are silently ignored. Each certificate in the certificate tree is used, in turn, to verify the payload's integrity. The verification process does not stop until a match is found or all certificates have been tried. Note that \fBWebJob\fR will not search for certificates in sub-directories of the specified tree. This control is ignored if \fBDsvVerifySignature\fR is disabled. .Sp For more information on signing and verifying payloads refer to the \fBWebJob-DsvTool\fR man page (i.e., \f(CWwebjob-dsvtool(1)\fR). That document also provides examples of how to create the necessary \s-1PEM\s0\-encoded keys and certificates. .Sp Note: If \fBDsvCertificateTree\fR does not exist or does not contain at least one valid certificate, the program will abort. .Sp Note: Digital Signature Verification (\s-1DSV\s0) support is a compile-time option, which is enabled by default. However, if \s-1DSV\s0 support is not compiled into the binary, WebJob will abort with an error if you try to use this (or any) \s-1DSV\s0 control in the config file. To determine if \s-1DSV\s0 support is compiled into the binary, run the following command: .Sp .Vb 1 \& webjob --version .Ve .Ip "\fBDsvVerifySignature\fR: [Y|N]" 5 Applies to \fBexecute\fR. .Sp \fBDsvVerifySignature\fR is optional. When enabled ('Y\*(R' or \*(L'y'), it instructs the application to verify the signature of the requested payload. Signatures are verified against one or more certificates located in \fBDsvCertificateTree\fR. The default value is \*(L'N\*(R'. .Sp If this control is enabled and the payload's signature is missing or invalid, \fBWebJob\fR will abort, and the downloaded payload will not be executed. This helps to protect the client in the case where the \fBWebJob\fR server can no longer be trusted (e.g., because it has been compromised). .Sp Note: Certificate chains and expiration dates are not checked in the verification process. It is the responsibility of the \fBWebJob\fR administrator to periodically manage (i.e., add, remove, update) any certificates installed on the clients. .Sp Note: Digital Signature Verification (\s-1DSV\s0) support is a compile-time option, which is enabled by default. However, if \s-1DSV\s0 support is not compiled into the binary, WebJob will abort with an error if you try to use this (or any) \s-1DSV\s0 control in the config file. To determine if \s-1DSV\s0 support is compiled into the binary, run the following command: .Sp .Vb 1 \& webjob --version .Ve .Ip "\fBGetHookCommandLine\fR: " 5 Applies to \fBexecute\fR. .Sp \fBGetHookCommandLine\fR is required when \fBGetHookEnable\fR is enabled. The value of this control is a command or pipeline that will be executed by the system's command interpreter once the requested file has been downloaded. If \fBGetHookSuffix\fR is defined, a variant of the target \fBprogram\fR is requested. This variant must be transformed by the specified command to produce the target \fBprogram\fR. If the command is successful, as defined by \fBGetHookStatus\fR, then the target \fBprogram\fR will be executed as usual. Otherwise, the target \fBprogram\fR will not be executed. The tokens \*(L'%tp\*(R', \*(L'%vp\*(R', \&'%pid\*(R', and \*(L'%s\*(R' may be used as place holders in the specified command line. When the hook is activated, these tokens are expanded as the target \fBprogram\fR, variant \fBprogram\fR, current Process \s-1ID\s0, and suffix, respectively. The character \*(L'%\*(R' may be used to produce a literal token. For example, \*(L'%%tp\*(R' would be expanded to \*(L'%tp\*(R'. .Ip "\fBGetHookEnable\fR: [Y|N]" 5 Applies to \fBexecute\fR. .Sp \fBGetHookEnable\fR is optional. When enabled ('Y\*(R' or \*(L'y'), the caller has the ability to interrupt or hook the normal course of events by running a single system command. This mechanism provides users with the ability veto or bless, as the case may be, subsequent execution of the target \fBprogram\fR. The default value is \*(L'N\*(R'. .Ip "\fBGetHookStatus\fR: [0-255]" 5 Applies to \fBexecute\fR. .Sp \fBGetHookStatus\fR is required when \fBGetHookEnable\fR is enabled. The value of this control determines the meaning of success for the hook. If the specified value matches the exit status as returned by \fIsystem\fR\|(3), then the target \fBprogram\fR will be executed as usual. Otherwise, the target \fBprogram\fR will not be executed. .Ip "\fBGetHookSuffix\fR: " 5 Applies to \fBexecute\fR. .Sp \fBGetHookSuffix\fR is optional when \fBGetHookEnable\fR is enabled. The hook suffix is appended to the target (\fBprogram\fR) name to create a variant name. This variant name takes the place of the target name in the \s-1GET\s0 request. To maintain order, the hook command must transform the downloaded variant into the target \fBprogram\fR. If this control is not defined, then the variant and target names will be the same, and no transformation would be required. .Ip "\fBGetTimeLimit\fR: [0-86400]" 5 Applies to \fBexecute\fR. .Sp \fBGetTimeLimit\fR is optional. The value of this control specifies how long the program is willing wait before giving up on download (i.e. \s-1GET\s0) requests. If \fBGetTimeLimit\fR is non zero and the time limit expires, the program will abort. If \fBGetTimeLimit\fR is not set or is set to zero, no limit will be imposed. The default value is zero. .Ip "\fBHashType\fR: [md5|sha1]" 5 Applies to \fBexecute\fR. .Sp \fBHashType\fR is optional. This control specifies the hash algorithm that is to be used when calculating message digests. Currently, the following algorithms are supported: \s-1MD5\s0, \s-1SHA1\s0, and \s-1SHA256\s0. If not specified, \fBHashType\fR defaults to \s-1MD5\s0. This control is not case sensitive. .Ip "\fBImport\fR: " 5 Applies to \fBexecute\fR. .Sp \fBImport\fR is optional. When specified, the directives contained in the file referenced by this control are included in the current configuration. Multiple instances of this control are allowed per file, and recursion is permitted up to three levels deep. Imports may be specified using a relative path. .Ip "\fBOverwriteExecutable\fR: [Y|N]" 5 Applies to \fBexecute\fR. .Sp \fBOverwriteExecutable\fR is optional. When enabled ('Y\*(R' or \*(L'y'), existing executables in the specified \fBTempDirectory\fR will be overwritten by subsequent \s-1GET\s0 requests. The default value is \&'N\*(R'. .Ip "\fBPutTimeLimit\fR: [0-86400]" 5 Applies to \fBexecute\fR. .Sp \fBPutTimeLimit\fR is optional. The value of this control specifies how long the program is willing wait before giving up on upload (i.e. \s-1PUT\s0) requests. If \fBPutTimeLimit\fR is non zero and the time limit expires, the program will abort. If \fBPutTimeLimit\fR is not set or is set to zero, no limit will be imposed. The default value is zero. .Ip "\fBRunTimeLimit\fR: [0-86400]" 5 Applies to \fBexecute\fR. .Sp \fBRunTimeLimit\fR is optional. The value of this control specifies how long the program is willing wait for the target application to finish. If \fBRunTimeLimit\fR is non zero and the time limit expires, the program will kill the spawned process and abort. If \fBRunTimeLimit\fR is not set or is set to zero, no limit will be imposed. The default value is zero. .Sp Note: Killing the spawned (i.e., child) process is done via \fITerminateProcess()\fR and \fIkill()\fR on Windows- and \s-1UNIX\s0\-based platforms, respectively. This may result in orphaned grandkids in either case. To help prevent this situation, proactively identify processes that block or take a long time to run and make sure that they run as kids. Using the shell's built-in exec or the family of \fIexec()\fR calls can help in this regard. .Ip "\fBRunType\fR: [linktest|snapshot]" 5 Applies to \fBexecute\fR. .Sp \fBRunType\fR is optional. This control sets a corresponding flag that classifies uploaded data as linktest or snapshot, The value of this control does not affect the format or content of \fBWebJob\fR output. When output is uploaded to a Web server, the value of this control may be used to determine how the data is processed. If not specified, \fBRunType\fR defaults to snapshot. .Ip "\fBSSLBundledCAsFile\fR: " 5 Applies to \fBexecute\fR. .Sp \fBSSLBundledCAsFile\fR is required when \fBSSLVerifyPeerCert\fR is enabled. This control specifies the name of a \s-1PEM\s0 (Privacy Enhanced Mail) encoded file that contains a bundled set of Certificate Authority (\s-1CA\s0) certificates. Any validated peer certificate that is signed by one of these CAs will be accepted provided that the \fBSSLMaxChainLength\fR and \fBSSLExpectedPeerCN\fR checks are also satisfied. \fBSSLBundledCAsFile\fR may be specified as a relative path. .Ip "\fBSSLExpectedPeerCN\fR: " 5 Applies to \fBexecute\fR. .Sp \fBSSLExpectedPeerCN\fR is required when \fBSSLVerifyPeerCert\fR is enabled. The value of this control represents the peer's expected Common Name (\s-1CN\s0). Conventionally, CNs are specified as fully qualified domain names. This control eliminates the need to perform a \s-1DNS\s0 lookup at the time of certificate validation. This, in turn, may help to prevent attacks involving \s-1DNS\s0 spoofing. .Ip "\fBSSLMaxChainLength\fR: [1-10]" 5 Applies to \fBexecute\fR. .Sp \fBSSLMaxChainLength\fR is optional when \fBSSLVerifyPeerCert\fR is enabled. The value of this control determines how deep a certificate chain may be before it is considered invalid. If not specified, this control defaults to a value of 1. .Ip "\fBSSLPassPhrase\fR: " 5 Applies to \fBexecute\fR. .Sp \fBSSLPassPhrase\fR is optional when \fBSSLUseCertificate\fR is enabled. Its value, if specified, is used to decrypt the contents of the client's private key file (see \fBSSLPrivateKeyFile\fR). If a passphrase is required to load the private key and this control has not been set, the user will be prompted for one. Naturally, this will cause problems for automated tasks, so keep that in mind. .Ip "\fBSSLPrivateKeyFile\fR: " 5 Applies to \fBexecute\fR. .Sp \fBSSLPrivateKeyFile\fR is required when \fBSSLUseCertificate\fR is enabled. This control specifies the name of a \s-1PEM\s0 (Privacy Enhanced Mail) encoded key file that can be used to sign \s-1SSL\s0 certificates. \fBSSLPrivateKeyFile\fR may be specified as a relative path. .Ip "\fBSSLPublicCertFile\fR: " 5 Applies to \fBexecute\fR. .Sp \fBSSLPublicCertFile\fR is required when \fBSSLUseCertificate\fR is enabled. This control specifies the name of a \s-1PEM\s0 (Privacy Enhanced Mail) encoded certificate to be used during \s-1SSL\s0 handshakes. \fBSSLPublicCertFile\fR may be specified as a relative path. .Ip "\fBSSLUseCertificate\fR: [Y|N]" 5 Applies to \fBexecute\fR. .Sp \fBSSLUseCertificate\fR is optional. When enabled ('Y\*(R' or \*(L'y'), it instructs the application to provide client side certificate authentication, if necessary. The default value is \*(L'N\*(R'. .Ip "\fBSSLVerifyPeerCert\fR: [Y|N]" 5 Applies to \fBexecute\fR. .Sp \fBSSLVerifyPeerCert\fR is optional. When enabled ('Y\*(R' or \*(L'y'), it instructs the application to verify the credentials of the peer server. The default value is \*(L'N\*(R'. .Ip "\fBTempDirectory\fR: " 5 Applies to \fBexecute\fR. .Sp \fBTempDirectory\fR is optional. This control specifies a directory in which all temporary files are to be created. If \fBTempDirectory\fR is not specified, the program attempts to obtain its value from the environment. First, it looks for \s-1TMPDIR\s0 (\s-1TEMP\s0 for \s-1WIN32\s0). Next, it looks for \s-1TMP\s0 (all platforms). If a suitable environment variable is not found, \fBTempDirectory\fR defaults to /tmp (\etemp for \s-1WIN32\s0). \fBTempDirectory\fR may be specified as a relative path. .Sp Note: If \fBTempDirectory\fR does not exist, the program will abort. .Sp Note: If an environment variable is defined but exceeds the maximum allowed length, it will be rejected. .Ip "\fBTimeoutSignal\fR: " 5 Applies to \fBexecute\fR. .Sp \fBTimeoutSignal\fR is optional. When the run timer expires (see \fBRunTimeLimit\fR), the signal specified by this control is sent to the spawned process. This control is rarely needed, and it should be used with care. Sending the wrong signal to a child process may not yield the desired result. However, there are cases when sending the default signal (\s-1SIGKILL\s0 = 9) is not the preferred course of action either. For example, you may want to run a tool that will perform an orderly shutdown upon receipt of a particular signal (e.g., \s-1SIGINT\s0 = 2). .Sp Note: This control is \s-1UNIX\s0\-specific, and its value must be a valid signal number (e.g., 1, 2, 9, etc.). Because the number of signals can vary from \s-1OS\s0 to \s-1OS\s0, you should check the man pages to determine what values are valid for your systems. On many systems, the following command will produce a mapping of signal names to their assigned numbers: .Sp .Vb 1 \& $ kill -l .Ve .Ip "\fBURLAuthType\fR: [basic|none]" 5 Applies to \fBexecute\fR. .Sp \fBURLAuthType\fR is optional. It identifies what authentication scheme to use when issuing \s-1HTTP/HTTPS\s0 requests. The value specified by this control applies to any requests involving \fBURLGetURL\fR or \fBURLPutURL\fR. When \fBURLAuthType\fR is set to basic, user credentials are base 64 encoded and incorporated into the request header. User credentials specified in the \s-1URL\s0 take precedence over credentials specified in the \fBURLUsername\fR and \fBURLPassword\fR controls. If not specified, \fBURLAuthType\fR defaults to none. .Ip "\fBURLDownloadLimit\fR: " 5 Applies to \fBexecute\fR. .Sp \fBURLDownloadLimit\fR is optional. The value of this control specifies how much data the client is willing to receive for any given \s-1HTTP/HTTPS\s0 request. If \fBURLDownloadLimit\fR is not set or is set to zero, no limit will be imposed. The default value is zero. .Ip "\fBURLGetURL\fR: " 5 Applies to \fBexecute\fR. .Sp \fBURLGetURL\fR is required. It defines the scheme, user credentials, host address, port, and \s-1CGI\s0 application to be used when making requests. If a username/password pair is specified in the \s-1URL\s0, that pair takes precedence over the values specified by \fBURLUsername\fR/\fBURLPassword\fR, if any. The tokens \*(L'%user\*(R' and \&'%pass\*(R' may be used as place holders in the specified \s-1URL\s0. Before a \s-1GET/PUT\s0 request is issued, these tokens are replaced with the actual values assigned to \fBURLUsername\fR and \fBURLPassword\fR, respectively. URLs must use a scheme of http or https and satisfy the following regular expression: .Sp scheme://(\fIuser\fR\|(:pass)?@)?\fIhost\fR\|(:port)?/(\fIpath\fR\|(\e?query)?)? .Ip "\fBURLPassword\fR: " 5 Applies to \fBexecute\fR. .Sp \fBURLPassword\fR is optional. It identifies the password to use when accessing a remote Web server. The value specified by this control is used in conjunction with \fBURLGetURL\fR and \fBURLPutURL\fR unless those controls supply their own username/password pair. .Ip "\fBURLPutURL\fR: " 5 Applies to \fBexecute\fR. .Sp \fBURLPutURL\fR is optional. It defines the scheme, user credentials, host address, port, and \s-1CGI\s0 application to be used when making \s-1PUT\s0 requests. If a username/password pair is specified in the \s-1URL\s0, that pair takes precedence over the values specified by \fBURLUsername\fR/\fBURLPassword\fR, if any. In any event, user credentials are only sent when basic authentication has been requested (See \fBURLAuthType\fR). \fBURLPutURL\fR uses the same syntax as \fBURLGetURL\fR. .Ip "\fBURLUsername\fR: " 5 Applies to \fBexecute\fR. .Sp \fBURLUsername\fR is optional. It identifies the username to use when accessing a remote Web server. The value specified by this control is used in conjunction with \fBURLGetURL\fR and \fBURLPutURL\fR unless those controls supply their own username/password pair. .Ip "\fBUnlinkExecutable\fR: [Y|N]" 5 Applies to \fBexecute\fR. .Sp \fBUnlinkExecutable\fR is optional. When enabled ('Y\*(R' or \*(L'y'), the downloaded executable is deleted before the program exits. The default value is \*(L'N\*(R'. .Ip "\fBUnlinkOutput\fR: [Y|N]" 5 Applies to \fBexecute\fR. .Sp \fBUnlinkOutput\fR is optional. When enabled ('Y\*(R' or \*(L'y'), any output files are unlinked before the program exits. This control has no effect when output data is directed to stdout/stderr. The default value is \*(L'N\*(R'. .Ip "\fBUploadOnGetFailure\fR: [Y|N]" 5 Applies to \fBexecute\fR. .Sp \fBUploadOnGetFailure\fR is optional. When enabled ('Y\*(R' or \*(L'y'), the program will attempt to upload its results even if the \s-1GET\s0 fails. Normally, attempting to upload results after a failed download is futile (e.g., authentication failures). However, there may be times when this behavior is desired. For example, suppose that \fBURLGetURL\fR and \fBURLPutURL\fR point to different servers. In this scenario, a \s-1GET\s0 failure does not imply that the \s-1PUT\s0 will fail too, so by monitoring uploads, you could detect jobs that aren't functioning properly. The default value for this control is \*(L'N\*(R'. .SH "RETURN VALUES" Upon successful completion, a value of \fB0\fR (\fBXER_OK\fR) is returned. Otherwise, one of the following error codes is returned: .Ip "\(bu" 5 \fB1 =\fR \fBXER_Abort\fR .Ip "\(bu" 5 \fB2 =\fR \fBXER_Usage\fR .Ip "\(bu" 5 \fB3 =\fR \fBXER_BootStrap\fR .Ip "\(bu" 5 \fB4 =\fR \fBXER_ProcessArguments\fR .Ip "\(bu" 5 \fB5 =\fR \fBXER_ReadProperties\fR .Ip "\(bu" 5 \fB6 =\fR \fBXER_CheckDependencies\fR .Ip "\(bu" 5 \fB7 =\fR \fBXER_Configure\fR .Ip "\(bu" 5 \fB8 =\fR \fBXER_GetStage\fR .Ip "\(bu" 5 \fB9 =\fR \fBXER_RunStage\fR .Ip "\(bu" 5 \fB10 =\fR \fBXER_PutStage\fR .Ip "\(bu" 5 \fB11 =\fR \fBXER_MultiStage\fR .PP A value of \fB1\fR (\fBXER_Abort\fR) means the program encountered a critical error and had to abort immediately. If the command line does not conform to the required syntax, a value of \fB2\fR (\fBXER_Usage\fR) is returned. The remaining exit codes roughly indicate which subsystem encountered the fatal error. If the error code is \fBXER_MultiStage\fR, then multiple stages (e.g., \s-1GET/RUN/PUT\s0) failed. .SH "FILES" .Ip "The Configuration File" 5 The \fBconfig\fR file specified on the command line contains a set of controls that are used to configure \fBWebJob's\fR runtime behavior. For more details on what controls may be specified, see the \s-1CONFIGURATION\s0 \s-1CONTROLS\s0 section of this document. .Ip "The Program File" 5 The \fBprogram\fR specified on the command line is retrieved from the Web resource and written to the local file system. The exact location varies depending on the value of \fBTempDirectory\fR. When \fBUnlinkExecutable\fR is enabled, the \fBprogram\fR is deleted before \fBWebJob\fR exits. However, if the \fBWebJob\fR aborts, this file may not be deleted. .Ip "The Output Files (webjob_