=head1 EXAMPLES

The following examples are intended to demonstrate different ways
of configuring and using B<WebJob>.  Any text encapsulated between
'--- XXX ---' delimiters represents config file content.

=head2 Example 1. Download and execute a program over HTTP -- output goes to stdout/stderr

This example demonstrates how to download and run ps(1) with output
being directed to stdout/stderr.  It is assumed that a B<WebJob>
server has already been configured to serve the appropriate ps(1)
binary for the system in question.  Also, assume that the following
information has been provided.

    ClientId = client_1
    URL = http://webjob.server.net/cgi-client/nph-webjob.cgi
    Username = client_1
    Password = access

The simplest configuration file that will carry out this task is as
follows:

    --- webjob.cfg ---
    ClientId=client_1
    UrlGetUrl=http://client_1:access@webjob.server.net/cgi-client/nph-webjob.cgi
    UrlAuthType=basic
    --- webjob.cfg ---

or, alternatively

    --- webjob.cfg ---
    ClientId=client_1
    UrlGetUrl=http://webjob.server.net/cgi-client/nph-webjob.cgi
    UrlUsername=client_1
    UrlPassword=access
    UrlAuthType=basic
    --- webjob.cfg ---

Once the config file has been created, B<WebJob> may be invoked as
follows:

    webjob --execute --file webjob.cfg ps -aux

or in short form:

    webjob -e -f webjob.cfg ps -aux

B<WebJob> will also accept the config file via stdin as follows:

    webjob -e -f - ps -aux < webjob.cfg

or

    cat webjob.cfg | webjob -e -f - ps -aux

B<WebJob> stores the target B<program> in a job-specific directory
(webjob_<time>_<nonce>) under B<TempDirectory>.  In this case,
B<TempDirectory> hasn't been specified, so data will be written to the
default B<TempDirectory>, which is '/tmp' or '\temp' for UNIX or
Windows environments, respectively.  To automatically remove the
target program and the sub-directory in which it resides after job
completion, enable B<UnlinkExecutable>.

=head2 Example 2. Download and execute a program over HTTP -- output is uploaded

Suppose that you want to upload the output of ps(1) to a B<WebJob>
server instead of stdout/stderr.  Given that that the URL from the
previous example may be used for both GET and PUT requests, the new
config file becomes:

    --- webjob.cfg ---
    ClientId=client_1
    UrlGetUrl=http://webjob.server.net/cgi-client/nph-webjob.cgi
    UrlPutUrl=http://webjob.server.net/cgi-client/nph-webjob.cgi
    UrlUsername=client_1
    UrlPassword=access
    UrlAuthType=basic
    --- webjob.cfg ---

This job may be invoked as follows:

    webjob -e -f webjob.cfg ps -aux

This time, B<WebJob> will create three files, webjob.{out,err,env}, in
a job-specific directory (webjob_<time>_<nonce>) under
B<TempDirectory>.  These files contain the output data that will be
uploaded to the B<WebJob> server in a PUT request.  To automatically
remove these files after they have been uploaded, enable
B<UnlinkOutput>.  To automatically remove these files and the
sub-directory in which they reside, enable both B<UnlinkOutput> and
B<UnlinkExecutable>.

=head2 Example 3. Download and execute a program over HTTPS -- explore advanced options

Suppose that you want to run netstat(1) over a secure, authenticated
channel (i.e., SSL with mutual certificate authentication).  Suppose
you also want to delete the target B<program> and its associated
output files upon job completion.  Assuming that the B<WebJob> server
is properly configured, then the information provided below is
sufficient to create the following config file.

    GET/PUT URL = https://webjob.server.net:443/cgi-client/nph-webjob.cgi
    SSL Public Cert File = /usr/local/webjob/ssl/mycrt.pem
    SSL Private Key File = /usr/local/webjob/ssl/mykey.pem
    SSL Bundled CAs File = /usr/local/webjob/ssl/CAs.pem
    SSL PassPhrase = flimflam
    Certificate Chain Length = 2
    Web Resource Validates Client Certificates = Y

    --- webjob.cfg ---
    ClientId=client_1
    UrlGetUrl=https://webjob.server.net:443/cgi-client/nph-webjob.cgi
    UrlPutUrl=https://webjob.server.net:443/cgi-client/nph-webjob.cgi
    UrlUsername=client_1
    UrlPassword=access
    UrlAuthType=basic
    UnlinkOutput=Y
    UnlinkExecutable=Y
    SslUseCertificate=Y
    SslPublicCertFile=/usr/local/webjob/ssl/mycrt.pem
    SslPrivateKeyFile=/usr/local/webjob/ssl/mykey.pem
    SslPassPhrase=flimflam
    SslVerifyPeerCert=Y
    SslBundledCAsFile=/usr/local/webjob/ssl/CAs.pem
    SslExpectedPeerCN=webjob.server.net
    SslMaxChainLength=2
    --- webjob.cfg ---

This job may be invoked as follows:

    webjob -e -f webjob.cfg netstat -an

=head2 Example 4. Compute the MD5 hash of /bin/ps

To compute the MD5 hash of /bin/ps, run the following command:

    webjob --hashsum --type md5 /bin/ps

or in short form:

    webjob -h -t md5 /bin/ps

=head2 Example 5. Compute the SHA1 hash of /bin/ps

To compute the SHA1 hash of /bin/ps, run the following command:

    webjob --hashsum --type sha1 /bin/ps

or in short form:

    webjob -h -t sha1 /bin/ps

=head2 Example 6. Use GetHook to unzip gzipped executables

This example demonstrates how to download and run a gzipped copy of
ps(1).  It is assumed that a B<WebJob> server has already been
configured to serve unzipped and zipped copies of ps(1) as ps and
ps.gz, respectively.

The first step is to enable GetHook in the client's config file and
define the appropriate hook command, suffix, and return status.  The
following config file snippet shows how this is done.

    --- webjob.cfg ---
    ...
    GetHookEnable=Y
    GetHookCommandLine=gzip -d %vp
    GetHookStatus=0
    GetHookSuffix=.gz
    ...
    --- webjob.cfg ---

In general, any valid command or pipeline may be specified for the
hook as long as it produces a valid ps executable.  When the following
B<WebJob> command is issued, the hook modifies the GET request such
that ps.gz is requested.  After ps.gz has been downloaded, the hook
executes the specified command.  In this case, '%vp' will be expanded
to 'ps.gz'.  If the hook command returns a zero status, then the
operation is deemed successful and normal B<WebJob> execution ensues.
If the return status is not zero, the target command will not be
executed.

    webjob -e -f webjob.cfg ps -aux

=head2 Example 7. Use GetHook to verify GPG signed executables

This example demonstrates how to download and run a GPG signed copy of
ps(1).  It is assumed that a B<WebJob> server has already been
configured to serve unsigned or signed copies of ps(1) as ps or
ps.gpg, respectively.

The first step is to enable GetHook in the client's config file and
define the appropriate hook command, suffix, and return status.  The
following config file snippet shows how this is done.

    --- webjob.cfg ---
    ...
    GetHookEnable=Y
    GetHookCommandLine=gpg --batch --decrypt %vp > %tp
    GetHookStatus=0
    GetHookSuffix=.gpg
    ...
    --- webjob.cfg ---

When the following B<WebJob> command is issued, the hook modifies the
GET request such that ps.gpg is requested.  After ps.gpg has been
downloaded, the hook executes the specified command.  In this case,
'%tp' and '%vp' will be expanded to 'ps' and 'ps.gpg', respectively.
If the hook command returns a zero status, then the operation is
deemed successful and normal B<WebJob> execution ensues.  If the
return status is not zero, the target command will not be executed.

    webjob -e -f webjob.cfg ps -aux

=head2 Example 8. Use GetHook to log WebJob activity

This example demonstrates how to log, using logger(1), the fact that
B<WebJob> downloaded and attempted to run ps(1).  It is assumed that a
B<WebJob> server has already been configured to serve copies of ps(1)
as ps.

The first step is to enable GetHook in the client's config file and
define the appropriate hook command and return status.  The following
config file snippet shows how this is done.  Note how the suffix is
commented out -- it could be left blank also.

    --- webjob.cfg ---
    ...
    GetHookEnable=Y
    GetHookCommandLine={ logger -p user.alert -t "webjob[%pid]" "%vp ---> %tp" ; true ; }
    GetHookStatus=0
    #GetHookSuffix=
    ...
    --- webjob.cfg ---

When the following B<WebJob> command is issued, the hook does not
modify the GET request because a suffix was not defined.  After ps has
been downloaded, the hook executes the specified command.  In this
case, '%tp', '%vp', and '%pid' will be expanded to 'ps', 'ps', and the
current Process ID (PID), respectively.  The specified command always
returns a zero status due to true(1), so normal B<WebJob> execution
ensues.

    webjob -e -f webjob.cfg ps -aux

=head2 Example 9. Download a file and write it to stdout

To download the file test.cfg located on www.somewhere.net and write
it to stdout, run the following command:

    webjob --get-url http://www.somewhere.net/test.cfg

or in short form:

    webjob -g http://www.somewhere.net/test.cfg

=head2 Example 10. Download a file through a proxy server and write it to disk

This example is similar to the previous one except that you must now
include a config file.  The purpose of the config file is to enable
proxy support and to specify the server's address and port.  Given
that the proxy server's address is 192.168.1.1, its port is 8888, and
it requires no authentication, the following config file would be
sufficient to perform the task:

    --- webjob.cfg ---
    UrlGetProxyEnable=Y
    UrlGetProxyHost=192.168.1.1
    UrlGetProxyPort=8888
    --- webjob.cfg ---

To download the file test.cfg located on www.somewhere.net through the
specified proxy server and write it to a file called test.cfg on disk,
run the following command:

    webjob --get-url --file webjob.cfg http://www.somewhere.net/test.cfg > test.cfg

or in short form:

    webjob -g -f webjob.cfg http://www.somewhere.net/test.cfg > test.cfg

=head2 Example 11. Execute simple Perl one-liners

This example demonstrates how to use execute a simple Perl one-liner
script to URL-decode a string.

    echo %74%65%73%74 | webjob -r perl -p -e 's/%([0-9A-Fa-f]{2})/pack("C", hex($1))/seg;'

This example demonstrates how to execute a simple Perl one-liner
script to generate a sequence of numbers between 0 and 255.

    webjob -r perl -e 'foreach $i (0..255) { printf("%d\n", $i); }'

This example demonstrates how to execute a simple Perl one-liner
script to insert a comment above a line of selected text in a config
file called test.cfg.

    webjob -r perl -p -i -e 's/^(DsvVerifySignature=.*)$/# No comment.\n$1/;' test.cfg

