NAME

nph-config.cgi - Process config file requests.

SYNOPSIS

    --- http.conf ---
    ...
    Include /var/webjob/config/apache/webjob.conf
    ...
    --- http.conf ---

    --- /var/webjob/config/apache/webjob.conf ---
    SetEnv CONFIG_PROPERTIES_FILE /var/webjob/config/nph-config/nph-config.cfg

    ScriptAlias /cgi-client/ "/usr/local/webjob/cgi/cgi-client/"

    <Directory "/usr/local/webjob/cgi/cgi-client/">
      AllowOverride AuthConfig
      Options None
      Order allow,deny
      Allow from all
    </Directory>
    --- /var/webjob/config/apache/webjob.conf ---

DESCRIPTION

This utility implements a Common Gateway Interface (CGI), and its purpose is to process requests for various configuration files.

The name of this utility must begin with the string ``nph-''. This naming convention, which stands for Non Parsed Headers, informs the web server that the utility is responsible for generating the entire HTTP response. Non Parsed Headers are used by this utility because they allow it to take full advantage of HTTP status code extensions. This simplifies client-side error checking without giving up the ability to generate application-specific responses.

The nph-config.cfg config file is used to control the CGI's runtime behavior. To make use of it, set CONFIG_PROPERTIES_FILE as appropriate. Upon execution, the script looks for and processes the file specified by this environment variable.

The cgi-client directory is where nph-config.cgi lives by default. Access to this directory should be strictly controlled, and any utilities placed in this directory should operate in the same security context (or realm). This utility is designed to read/write data from/to the server's local disk on behalf of potentially hostile clients. Therefore, you'll want to maintain a tight rein to avoid any unwanted results.

CONFIGURATION CONTROLS

This section describes the various controls that this program recognizes. In general, controls either shape runtime behavior or provide information needed to perform a specific function. Controls and their values, one pair/line, are read from a file having the following format.

    <control> = <value>

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., '#'). In any given line, all text to the right of the first comment will be ignored. White space surrounding controls and values is ignored.

BaseDirectory: <path>

BaseDirectory is the epicenter of activity. The default value is '/var/webjob'.

CapContentLength: [Y|N]

CapContentLength forces the script to abort when ContentLength exceeds MaxContentLength. The default value is 'N'.

ConfigDirectory: <path>

ConfigDirectory is where various configuration files are maintained. The default value is '<BaseDirectory>/config'.

ConfigSearchOrder: [clients|configs|clients:configs|configs:clients]

ConfigSearchOrder specifies the order in which custom config files are sought out and processed. Custom config files may be used to override a predefined subset of the site-specific properties. The following tree enumerates the locations where global and custom config files may exist.

    config
      |
      + nph-config
          |
          - nph-config.cfg # applies globally
          |
          + clients
          |   |
          |   - nph-config.cfg # applies globally
          |   |
          |   + <client-N>
          |       |
          |       - nph-config.cfg # applies to all configs for <client-N>
          |       |
          |       + <config-N>
          |           |
          |           - nph-config.cfg # applies only to <client-N>/<config-N>
          |
          + configs
              |
              - nph-config.cfg # applies globally
              |
              + <config-N>
                  |
                  - nph-config.cfg # applies to all clients for <config-N>
                  |
                  + <client-N>
                      |
                      - nph-config.cfg # applies only to <config-N>/<client-N>

As each config file is processed, its values trump those of any that came before -- including any values that came from global config files. Supported values for this variable are 'clients', 'configs', 'clients:configs', and 'configs:clients'. The default value is 'clients:configs'.

DynamicDirectory: <path>

DynamicDirectory is where dynamic content is stored. The default value is '<BaseDirectory>/dynamic'.

EnableConfigOverrides: [Y|N]

When active, EnableConfigOverrides causes the script to seek out and process additional client- and/or command-specific config files (see ConfigSearchOrder). The default value is 'Y'.

EnableGetService: [Y|N]

When active, EnableGetService allows the script to accept and process valid GET requests. This control can be overridden, and its intended purpose is to administratively disable access for valid clients (e.g., to force a failover). The default value is 'Y'.

EnableHostAccessList: [Y|N]

When active, EnableHostAccessList causes the script to consult a host access list to determine whether or not the client will be granted access based on its IP address. Note: This mechanism will fail closed if it's enabled and the access list is missing or does not contain the necessary client ID to IP address mappings. The default value is 'N'.

EnableLogging: [Y|N]

When active, EnableLogging forces the script to generate a log message for each request. If the designated LogFile can not be opened, the log message will be written to STDERR. The default value is 'Y'.

FolderList: <item[:item[...]]>

FolderList specifies locations where shared programs can be found. If a requested file does not exist in a given client's configs directory, the FolderList is searched according to the order given here. The list delimiter is a colon (i.e., ':'). An example list would be 'common:shared'. The default value is 'common'.

GetHookCommandLine: <command>

GetHookCommandLine is a command string consisting of zero or more conversion specifications optionally interspersed with zero or more plain text characters. The following conversion specifications are supported:

    %A   = Weekday as a full name
    %a   = Weekday as an abbreviated name
    %cid = Client ID as a string
    %d   = Day of the month as a decimal number (01-31)
    %dynamic_dir = Full path of the dynamic directory
    %dynamic_out = Full path of the dynamic output file that is to be created
    %file = Client-requested filename as a string
    %H   = Hour as a decimal number (00-23)
    %ip  = IP address as a dotted quad string
    %jid = Job ID as a string
    %M   = Minute as a decimal number (00-59)
    %m   = Month as a decimal number (01-12)
    %pid = Process ID of server-side CGI script
    %S   = Second as a decimal number (00-60)
    %s   = Number of seconds since the Epoch
    %sid = Server ID as a string
    %u   = Weekday as a decimal number (1-7)
    %w   = Weekday as a decimal number (0-6)
    %Y   = Year with century as a decimal number

If the specified command is an empty string, then the hook mechanism is (effectively) disabled, and the condition is logged. However, if the hook is disabled (i.e., GetHookEnable=N), then this control is ignored.

GetHookLogDivertedOutput: [Y|N]

GetHookLogDivertedOutput causes the script to divert any output on stdout/stderr to nph-webjob-hook.{err,out}. Normally, output for these streams is discarded since hook commands should be written to keep them clean (e.g., by logging to a file). The default value is 'N'.

Note: If a given hook command is not working properly, you can use this option to capture any output that was written to stdout/stderr. That, in turn, may help you debug the problem.

Note: If logging is disabled (i.e., EnableLogging=N), this control is ignored.

GetHookEnable: [Y|N]

When active, GetHookEnable causes the script to execute the command line specified by GetHookCommandLine. The behavior of the hook mechanism is to launch a subprocess and wait for it to finish. The purpose of the subprocess is to create dynamic content that will be delivered to the client. The hook mechanism is highly configurable -- config file overrides are fully supported, multiple conversion tokens are available, and the user determines what, if any, commands are executed when the hook is activated. Currently, hooks are only activated if they are enabled and a hook command has been defined. The default value is 'N'.

GetHookStatus: <integer>

GetHookStatus determines the meaning of success for the hook. If the specified value does not match the exit status as returned by system(), the hook is considered a failure and the entire job is aborted. Otherwise, processing continues as normal. The default value is '0'.

GetHookStatusMap: <integer:integer>[,<integer:integer>[...]]

GetHookStatusMap allows the user to map hook exit codes into HTTP response codes. No mappings are defined by default.

LogfilesDirectory: <path>

LogfilesDirectory is where log files are stored. The default value is '<BaseDirectory>/logfiles'.

MaxContentLength: <integer>

MaxContentLength specifies the largest upload in bytes the script will accept. If CapContentLength is disabled, this control has no effect. The default value is '100000000'.

ProfilesDirectory: <path>

ProfilesDirectory is where client profiles and shared commands are maintained. The default value is '<BaseDirectory>/profiles'.

RequireMatch: [Y|N]

RequireMatch forces the script to abort unless ClientId matches RemoteUser. When this value is disabled, any authenticated user will be allowed to issue requests for a given client. Disabling RequireUser implicitly disables RequireMatch. The default value is 'Y'.

RequireUser: [Y|N]

RequireUser forces the script to abort unless RemoteUser has been set. The default value is 'Y'.

ServerId: <string>

ServerId specifies the identity assigned to the WebJob server. The default value is 'server_1'.

SpoolDirectory: <path>

SpoolDirectory is where spools and queues are maintained. The default value is '<BaseDirectory>/spool'.

SslRequireCn: [Y|N]

SslRequireCn forces the script to abort unless SslClientSDnCn has been set. If SslRequireSsl is disabled, this and all other SSL controls are ignored. The default value is 'N'.

SslRequireMatch: [Y|N]

SslRequireMatch forces the script to abort if ClientId does not match SslClientSDnCn. When this control is disabled, access will be governed by RequireMatch. Disabling SslRequireCn implicitly disables SslRequireMatch. Also, if SslRequireSsl is disabled, this and all other SSL controls are ignored. The SslRequireMatch check is performed prior to (not instead of) the RequireMatch check. The default value is 'N'.

SslRequireSsl: [Y|N]

SslRequireSsl forces the script to abort unless the client is speaking HTTPS. Disabling SslRequireSsl implicitly disables all SSL-related controls. The default value is 'Y'.

UseGmt: [Y|N]

When active, UseGmt forces the script to convert all time values to GMT. Otherwise, time values are converted to local time. The default value is 'N'.

FILES

BaseDirectory/logfiles/nph-config.log

This utility writes log messages to nph-config.log (see nph-config.cfg). This file contains the following fields separated by whitespace in the given order: Date, Time, JobId, RemoteUser, RemoteAddress, RequestMethod, ClientId, Filename, ContentLength, ServerContentLength, Duration, ReturnStatus, and ErrorMessage. A single hyphen, '-', is used to denote the fact that a particular field had an empty or undefined value. The ErrorMessage field is set off from the other fields with a double hyphen '--' because it uses a free form text format that can include whitespace.

BaseDirectory/logfiles/nph-config-hook.err

This utility captures hook-related output on stderr and writes it to nph-config-hook.err. This file is a bit bucket for dirty hook commands. It is also useful as a debugging aid when creating new hook commands.

BaseDirectory/logfiles/nph-config-hook.log

This utility writes hook-related log messages to nph-config-hook.log. This file contains the following fields separated by whitespace in the given order: Date, Time, JobId, RequestMethod, ClientId, Filename, PidLabel, Pid, State, and Message. A single hyphen, '-', is used to denote the fact that a particular field had an empty or undefined value. The Message field is set off from the other fields with a double hyphen '--' because it uses a free form text format that can include whitespace.

BaseDirectory/logfiles/nph-config-hook.out

This utility captures hook-related output on stdout and writes it to nph-config-hook.out. This file is a bit bucket for dirty hook commands. It is also useful as a debugging aid when creating new hook commands.

AUTHOR

Klayton Monroe

SEE ALSO

nph-webjob.cgi(1), webjob(1)

LICENSE

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