In this section we will walk you through the relatively simple tasks involved in configuring OneGate for use with your applications. There are twelve sections in all.

Before we begin, it should be stated that in the following sections, pathnames will contain certain parts in square brackets. These parts are:

• [maindir] - The full path to the main onegate directory for configuration and spooling.
• [progset] - The name of a valid program set, used as a directory name.

It is a good idea to familiarise yourself with manual configuration. After doing so, you can either configure OneGate manually, or you can use the ogconfig configuration tool. The choice is yours, but you should understand the configuration at its basic level before using the tool.

Valid Program Set Definitions

Program sets are single word names that tell OneGate which application it is working with at any given time. A program set name may contain only alphanumeric characters, and the underscore symbol.

When called, OneGate will verify the program set name passed to it in the form field onegate_set. The file used to verify validity of program set names is [maindir]/valid.sets. This file should contain one program set name per line. Blank lines or lines starting with a pound sign (comments) are ignored. You can not put comments on the same line as a program set name. This file must be present.

Main Environment

Global environment variables that all your applications require may be set by using the [maindir]/main.environment file. The presence of this file is optional.

The format of this file is identical to Bourne shell syntax, with one VAR=value assignment per line. There are a few exceptions to the Bourne-like quality of the syntax. Exports are not needed. OneGate handles this for you, as the file is not processed by a shell. Comments may be on individual lines, and blank lines are ignored. You may not put comments after value contents. The other notable difference is that you do not need to quote your values. Any quotes included (be they single or double) will be literally interpreted as part of the value for your variable.

Main Configuration

The file [maindir]/main.config controls global behaviour for OneGate's handling of all applications. The presence of this file is optional, and if it is absent or empty, default values will be used.

There are 18 options in all, which are described in detail on the Configuration Options page. The format of this file is one option=value assignment per line. Comments may be on lines by themselves, and blank lines are ignored.

Global General Error File

The file [maindir]/error.page may be be used to create a "pretty" general error page in the event OneGate encounters an error during execution. This page should be in HTML format, and is intended in the same vein as httpd custom error pages.

Using this file, you can suppress OneGate's normal, terse error reporting and give your users an error page that is integrated closely with the look and feel of your site, and allows for graceful redirection at your discretion.

If the devel_debug option is enabled, custom error pages are disabled.

Global Field Definitions File

The file [maindir]/main.fields controls which fields OneGate will accept globally for all program sets, and their definitions. See the Program Set Field Definitions page for full details on syntax.

Any fields defined in program sets automatically overridethe fields defined in this file in the event of a redefinition conflict.

Global Cookie Definitions File

The file [maindir]/main.cookies controls which cookies OneGate will accept globally for all program sets, and their definitions. See the Program Set Cookie Definitions page for full details on syntax.

Program Set Field Definitions

The file [maindir]/configs/[progset]/fields is used to describe the permitted and required fields for each program set. This file must be present, although it may be empty if your program requires no fields.

The format of this file is one entry per line, consisting of three fields separated by whitespace. The fields, in order, are:

1. fieldname - The literal field name used in your form.
2. mandatory or optional - Whether the field must be present at submission. Please note that this means exactly what it says, that the field must be present, not that the field must contain data. This setting is not meant to catch empty fields; it is meant to prevent abuse by people faking submissions and omitting fields, while at the same time allowing you to make certain fields (like file uploads) optional for debugging or other purposes. Any field set to mandatory must be present at submission, or OneGate will return a Missing Fields error and terminate the transaction. Note that if you utilise the allow_field_wildcards option, optional fields may be wildcarded to cut down on repetitive definitions.
3. FILE or TEXTAREA - If this optional field is present and set to FILE, it denotes that the field is an HTTP File Upload field, and should be treated as such. In this case, the uploaded file is saved to a safe filename, and the contents of the XML output are adjusted as detailed in the descripton of the OneGate DTD All file upload files are deleted after your program set finishes running, so you must copy them to somewhere for permanent storage if you wish to keep them. If this field is present and set to TEXTAREA, it denotes that you wish to store the field contents in a separate file and only reference the path to the file in the XML output, as specified in the OneGate DTD. All TEXTAREA files are deleted after your program set finishes running, so you must copy them to somewhere for permanent storage if you wish to keep them. Absence of this field is the same as giving it any value other than FILE or TEXTAREA, and will result in the field being treated as a regular value field.

Please note that the main OneGate field onegate_set is always accepted, and does not need to be in the field definition file for any program set.

Additionally, the special fields for user authentication (if you enable it) are always accepted, and do not need to be in the field definition file for any program set. These fields are onegate_user and onegate_pass.

Any other field not listed in this file will cause the entire request to be denied with an error.

NOTE: A leading cause of "Extra fields given" errors (error 12) is forgetting to include the field for your SUBMIT or IMAGE buttons. This field should ideally be defined as optional, as it will not always be returned. If the browser allows a user to submit a form by hitting <ENTER> in a text field or elsewhere, the submit button value may not be returned. If the button is pressed, it should be returned. Hence, optional is the advised setting for these types of fields.

Program Set Cookie Definitions

The file [maindir]/configs/[progset]/cookies is used to describe the requested cookie names to be retrieved for each program set. The presence of this file is optional. The syntax allows for blank and separate comment lines. Each cookie name to be retrieved should be listed on a separate line.

Program Set Command File

The heart of your interaction with OneGate, the file [maindir]/configs/[progset]/program.set controls what commands are executed within your application. This file must be present, and configured with the list of your commands for the program set.

The syntax allows for blank and separate comment lines. You may not place comments on the same line as a command. Each command should be on a separate line, and each will be processed in order at execution.

You may use any valid command on your system, and shell metacharacters (redirects, etc.) are allowed. Please note that OneGate clears the $PATH environment variable at the beginning of its execution, so you effectively have no path unless you set one in either the main or program set environment variable files. If you do not define a path, you will need to explicitly state full paths to your commands.

There are six "magic cookies" that allow you to give your commands access to the relevant files and data associated with a OneGate transaction. Wherever these tokens appear in your commands, they will be replaced with the appropriate pathname.

• %i - This token represents the XML data file generated by OneGate. This file contains your form data.
• %o - This token represents the output file that will be sent back to the remote client after all commands in the program set have successfully been executed.
• %t - This token represents the Reply MIME Type File, which allows you to control the MIME type with which your response is sent.
• %n - This token represents the internal lock number OneGate uses for your current transaction.
• %p - This token represents the program name to call in your URL's when using the multiple testbed functionality.
• %u - This token represents a unique ID that can be used by both your applications and commands in your program set to let you save and utilise temporary files between commands. (e.g., %u-sync.sql) NOTE: Any files you create are created in [maindir]/spool/[progset]/tmp unless you specify a full path. Should you create any "external" files, you should remove them manually from within your program set if you wish them to be deleted as part of the transaction, as OneGate will not remove these non-OneGate-specific files automatically.

Should you be unable to utilise the command line to pass filenames or the internal lock number to your application, an alternate method is available in the form of environment variables. These do not go in the configuration file, but instead may be accessed from within your application:

• ONEGATE_INFILE - Identical to the file that %i denotes in the program set command file.
• ONEGATE_OUTFILE - Identical to the file that %o denotes in the program set command file.
• ONEGATE_MIMEFILE - Identical to the file that %t denotes in the program set command file.
• ONEGATE_LOCK_NUMBER - Identical to the number that %n denotes in the program set command file.
• ONEGATE_CGINAME - Identical to the program name that %p refers to in the program set command file.
• ONEGATE_UNIQUE_ID - Identical to the program name that %u refers to in the program set command file.

NOTE: As of v04.00.00, the %t and ONEGATE_MIMEFILE methodology is not required. The new mime_type option in the configuration files will suffice. If the legacy functionality is used, it will override whatever may be set in the configuration file(s).

Commands may be run conditionally as of version 04.01.00. The syntax for doing so involves prefixing your commands with certain characters at the very beginning of the line. The following syntaxes have the following effects on your commands:

• command - Without modifying characters at the start of the line, your commands will run in regular mode. This means that if they exit with a non-zero status (indicating a failure in most cases), OneGate will exit with Error 17 after dispersing the appropriate error page.
• !command - With an exclamation point prefix, if the current command exits with a non-zero status, subsequent commands continue to be executed.
• ?command - With a question mark prefix, the current command is only executed if the immediately preceding command exited with a non-zero status. This can be used to institute "fallback" commands in case other commands fail.
• ?!command - With a question mark and then an exclamation point, the command will only be executed if the immediately preceding command exited with a non-zero status, and subsequent commands will continue to be executed if the current command exits with a non-zero status. NOTE: The "?!" sequence is not reversable. A syntax of "!?" will not do the same thing, and should not be used.

Additionally, any command may create a file equivalent to %u.STOP in the current working directory (that is, a file [maindir]/spool/[progset]/tmp/[ONEGATE_UNIQUE_ID].STOP where the unique ID is the value from that environment variable or taken from %u) in order to entirely halt execution of further commands. Before each command is executed, a check is made for the presence of this semaphore file. If it is present, no further commands will be executed. Thus, it is possible to have a file "fail" programmatically, write an output page, and use this semaphore to cause no further commands to run, in order to get that error page to the browser and proceed no further.

Program Set Environment

Similar to the main environment variable file, you may set environment variables for each specific application independantly by using the [maindir]/configs/[progset]/environment file. This file is optional, and if it is empty or absent, global and then default values will be used, in that order of precedence.

The format of this file is identical to that of the main environment variable file. Please note that any identical variable names in the application environment file will override global entries of the same name.

Program Set Configuration

Similar to the main configuration file, you may set the OneGate options at the application level with the file [maindir]/configs/[progset]/config. This file is optional, and if it is empty or absent, global and then default values will be used, in that order of precedence.

As with environment variables, any entry at the application level will override the global settings. The sole exception is the max_session_count option, which will be ignored in the application context and is only valid at the global level.

Program Set General Error File

The file [maindir]/configs/[progset]/error.page may be be used to create a "pretty" general error page in the event OneGate encounters an error during execution. This page should be in HTML format, and is intended in the same vein as httpd custom error pages.

Using this file, you can suppress OneGate's normal, terse error reporting and give your users an error page that is integrated closely with the look and feel of your site, and allows for graceful redirection at your discretion.

Any program set general error file automatically overrides the global general error file, if the global file exists.

If the devel_debug option is enabled, custom error pages are disabled.

Lock Count Error Message File

The file [maindir]/lock.error should contain a valid HTML page to be returned in the event that OneGate encounters its maximum number of instances as set by the max_session_count option, and exceeds all retry time. Place any message you want in this file, in HTML format. Bear in mind that this is a global file, and will be returned on all occurrances of this event. This file must be present.

Program Set Virtual Firewall

The virtual firewall for an application is configured through the file [maindir]/configs/[progset]/host.access and is disabled if this file does not exist. Comments and blank lines are allowed in this file. The format of the file is one rule per line, consisting of the following fields in order, separated by whitespace:

1. An IP address. This can be a complete address, or a wildcarded address. Any of the four octets may be an asterisk as a wildcard for that octet. All four octets must always be present, even if you wild card all but the first two. For example: 192.168.*.* is correct, but 192.168 is incomplete and will cause OneGate to issue an error message regarding the misconfiguration of the address.
2. A class. Valid classes are allow, deny, or alwaysdeny.
3. A path to the file containing the HTML message to relate to the browser in the case where a ban is enforced. This field is only used (and necessary) if the class field is either deny or alwaysdeny. If the class is deny or alwaysdeny, this field must be present and point to a file that exists.

The order in which the rules are listed is not important as of version 04.00.00.

• All IP addresses from remote clients that match no bans are allowed by default.
• An IP address that matches a deny rule will be denied unless there is a subsequent allow rule that negates it. Given a remote address of 192.168.1.13, a rule that denies *.*.*.* will be overridden by a rule that allows 192.168.1.*.
• An IP address that matches an alwaysdeny rule will always be denied, regardless of any allow rules it may always match. Given the above example, you could allow all of that subnet except the remote address by adding a rule for the specific IP address, of the class alwaysdeny.

Rules that are of the classes deny or alwaysdeny must have the third field which points to an HTML file that will be presented to the browser, explaining the ban. The file you choose to present is entirely at your discretion, but it will be presented with the text/html MIME type. The file listed must exist at the location indicated, or OneGate will generate an error noting that there is a missing subnet denial message file.

The virtual firewall stage is handled before the user authentication stage, if both are enabled.

Program Set User Authentication

The user authentication for an application is configured through the file [maindir]/configs/[progset]/allowed.users and is disabled if this file does not exist. Comments and blank lines are allowed in this file. The file denotes the users that are allowed to use the program set. The format of this file consists of two fields per line:

1. user or group - A description of the type of entry for the rule.
2. The user name or group name which is allowed by the rule.

The use of a group entry automatically allows all users that fall within that group.

If you create and utilise the allowed.users file, you must also create the files ht.users and ht.groups. These may be symbolic links to already existing files elsewhere on your system on *nix platforms. The formats of these files follow the standard formats that the Apache web server recognises:

ht.users format:

username:encryption_string

ht.groups format:

groupname: user user user ...

The ht.users file, should you not have one already created, may be created and maintained with the program htpasswd, which should be installed on any server with a web server present.

The ht.groups file, should you not have one already created, is created by hand. Please note that as with Apache, additional group lines with the same group name will append their users to the overall list of legal users for that group name, rather than replace the previous list. Thus, you can break up the list of users for large groups over multiple lines starting with the same group name, for increased legibility.

The user authentication may be utilised in two ways:

• The REMOTE_USER environment variable is checked first. If a user has already validated themselves with httpd within the same subdirectory tree that the OneGate program resides and that authentication was for the same request type, either GET or POST, whichever you are using with your application, then if the user is in the allowed.users table, and exists in the ht.users file, the user is allowed to use the program set. Please note that if a user has previously authenticated for GET but not for POST, and you are using POST in your submission (or vice-versa), the REMOTE_USER environment variable will not be set! You must previously authenticate for the same type of submission as you are using for your program set in order to utilise the pre-authentication.
• If the REMOTE_USER environment variable is not set, two special fields are checked for. These fields are onegate_user and onegate_pass. If you supply these (either from INPUT TEXT and INPUT PASSWORD fields that a user can fill out, or in HIDDEN fields generated from another program set [or even another source entirely]), OneGate will perform the encryption check on the password internally and attempt to validate the user against the configuration you set. For security reasons, do not put the onegate_pass field in a static file on your web server! Anyone can view the source of a form, and your password would be present in plain text, thus compromising your security. This method is meant to be used in a single session, with the fields either filled out manually or generated by software in dynamic forms that do not reside on disk.

The allowed.users file is OneGate's equivalent to Apache's .htaccess file, if you care to think of it that way. The difference (besides being less complex) is that any users not accounted for in this file will not be permitted to use the program set. There is no need (or ability) to manually deny anyone access. All listed users (or users included in listed groups) will be authenticated. Anyone else is denied access.

In addition, if you activate user authentication, you must create the file [maindir]/configs/[progset]/invalid.user.message for display to the remote browser. This file will be presented with a MIME type of text/html when a user is denied access.

The user authentication stage is handled after the virtual firewall stage, if both are enabled.

"No Login" Disabling Mechanism

OneGate may be told not to execute any applications (global) or a specific application (program set) by use of a nologin file. This file not only tells OneGate not to execute the usual functions, but the contents of the file are presented to the remote browser as an explanation of the refusal of service. The file will be presented with the MIME type text/html. The locations of the global and program set files are [maindir]/nologin and [maindir]/configs/[progset]/nologin, respectively. The global message will override any program set messages, should both be present simultaneously.