Appendix A. Using Caching Proxy commands

This topic provides a reference for proxy server commands.

cgiparse command

Purpose

Use the cgiparse command to parse the QUERY_STRING environment variable for CGI scripts. If the QUERY_STRING environment variable is not set, the command reads CONTENT_LENGTH characters from its standard input. All returned output is written to its standard output.

Format

   cgiparse -Flag [Modifier]

Parameters

Flags, their one-character equivalents (-k -f -v -r -i -s -p -c -q -P) and their function, include:

-keywords | -k
Parses QUERY_STRING for keywords. Keywords are decoded and written to standard output, one per line.
-form | -f
Parses QUERY_STRING as form request. Returns a string which, when evaluated by the shell, sets shell variables with the prefix FORM_ followed by a field name. Field values are the contents of the variables.
-value field-name | -v field-name
Parses QUERY_STRING as form request. Returns only the value of field-name.
-read | -r
Reads CONTENT_LENGTH characters from standard input and writes them to standard output.
-init | -i
If QUERY_STRING is not set, reads the value of standard input and returns a SET statement that sets QUERY_STRING to this value. This can be used with both the GET and POST methods. A typical use is:
eval 'cgiparse -init'

This sets the QUERY_STRING environment variable, regardless of whether the GET or POST method was used.

cgiparse can be called multiple times in the same script when the GET method is used, but it must only be called once if the POST method is used. With the POST method, after standard input is read, the next cgiparse finds standard input empty and waits indefinitely.

-sep separator | -s separator
Specifies the string used to separate multiple values. If you are using the -value flag, the default separator is newline. If you are using the -form flag, the default separator is a comma (,).
-prefix prefix | -p prefix
Used with -POST and -form, specifies the prefix to use when creating environment variable names. The default is "FORM_".
-count | -c
Used with -keywords, -form, and -value, returns a count of items related to these flags.
-keywords | -k
Returns the number of keywords.
-form | -f
Returns the number of unique fields (multiple values are counted as one).
-value field-name | -v field-name
Returns the number of values for field-name (if there is not a field named field-name, output is 0).
-number
Used with -keywords, -form, and -value, returns the specified occurrence related to these flags.
-keywords
Returns the n'th keyword. (For example -2 -keywords outputs the second keyword.)
-form
Returns all the values of the n'th field. (For example -2 -form outputs all the values of the second field.)
-value field-name
Returns the n'th of the multiple values of field field-name. (For example -2 -value -whatsit outputs the second value of the whatsit field).
-quiet | -q
Suppresses all error messages. (Non-zero exit status still indicates error.)
-POST | -P
Information from standard input (or if a filename is intended, the stdin file) is directly decoded and parsed into shell variables, QUERY_STRING is not used. -POST is equivalent to consecutive use of the -init and -form options.

Examples

The following examples ignore the fact that, in reality, QUERY_STRING is already set by the server. In the following examples, $ is the Bourne shell prompt.

Results

0
Success
1
Illegal command line
2
Environment variables not set correctly
3
Failed to get requested information (for example, there is no such field or QUERY_STRING contains keywords when form field values are requested)
Note:
When you receive one of these error codes, you may receive additional informational messages, too. The message varies depending on the command issued.

cgiutils command

Purpose

Use the cgiutils command in no-parse header programs to produce a full HTTP 1.0 response.

Note:
If you want to supply your own no-parse header (nph) programs specifically to return your own return values, the name of the program must begin with nph-. This prevents the server header from overriding your return value with the standard server return value.

Format

cgiutils -Flag [Modifier]

If Modifier contains blanks, enclose it in quotation marks ("").

Parameters

-version
Returns version information.
-nodate
Does not return the Date: header.
-noel
Does not return a blank line after headers. This is useful if you want other MIME headers after the initial header lines.
-status nnn
Returns full HTTP response with status code nnn, instead of only a set of HTTP headers. Do not use this flag if you want only the Expires: header.
-reason explanation
Specifies the reason line for the HTTP response. You can use only this flag with the -status nnn flag.
-ct [type/subtype]
Specifies MIME Content-Type header. This example specifies a MIME content type of text/html:
   cgiutils -ct text/html

If you omit the type/subtype, the MIME content type is set to the default text/plain. This example sets the MIME content type to text/plain.

   cgiutils -ct
-ce encoding
Specifies MIME Content-Encoding header. For example:
   cgiutils -ce  x-compress
-cl language-code
Specifies MIME Content-Language header. For example:
   cgiutils -cl en_UK
-length nnn
Specifies MIME Content-Length header.
-expires Time-Spec
Specifies MIME Expires: header. This flag specifies the time to live (the expiration date of a document) in any combination of days, hours, minutes, and seconds. This is the length of time a document is considered valid. For example:
   cgiutils -expires 2 days 12 hours

The cgiutils command adds the time you specify to the current Greenwich Mean Time to determine the expiration date. The expiration date is put in the Expires: header in the HTTP format.

-expires now
Produces an Expires: header that matches the Date: header.
-uri URI
Specifies the Universal Resource Identifier (URI) for the returned document. URI can be considered to be the same as URL.
-extra xxx: yyy
Specifies an extra header that cannot otherwise be specified for the cgiutils command.

Examples

htadm command

Purpose

Use the htadm command to control your server password files. Your server uses password files to control access to your files. You can add a user name to a password file, delete a user from a password file, verify a user’s password, and create an empty password file. You can also change a password for a user by first deleting the user's password and then creating a new one.

Note:
When you use the htadm command to add a user, change a password, or check a password, you must enter the password on the command line. Because the command destroys the password from the command line as soon as possible, it is highly unlikely that you can see a user’s password by looking at the process listing on the machine (with the ps command, for example).

Format

htadm -Flag  [Modifier]

Parameters

-adduser password-file user-name [password [real-name]]
Adds a user and password into the password file. If you enter the command with only password-file, you are prompted for the other parameters.
password-file
The path and name of the password file to which you want to add the user.
user-name
The name of the user you want to add.

Use only alphabetic and numeric characters for the user name; do not use special characters.

The command fails if there is already a user of the same name in the password file.

password
The password you want to define for the user name.

Passwords can be up to 32 characters long. Use only alphabetic and numeric characters for the password; do not use special characters.

Notes:
  1. Some browsers are unable to read and send passwords longer than eight characters. Because of this limitation, if you define a password longer than eight characters, the server recognizes either the complete password or just the first eight characters of the password as valid.
  2. The administrator user name and password are case-sensitive even if the operating system is not case-sensitive. Be sure to input the exact user name and password entered using the htadm command when accessing the Configuration and Administration forms.
real-name
A comment or name you want to use to identify the user name you are adding. Whatever you enter will be written into the password file.
-deluser password-file [user-name]
Deletes a user from the password file. If you enter the command with only password-file, you are prompted for the user-name parameter.
password-file
The path and name of the password file from which you want to delete a user.
user-name
The name of the user you want to delete. The command fails if the user name you specify does not exist in the password file.
-passwd password-file [user-name [password]]
Changes the password for a user name already defined in the password file. If you enter the command with only password-file, you are prompted for the other parameters.
password-file
The path and name of the password file that contains the user name whose password you want to change.
user-name
The user name whose password you want to change. The command fails if the user name you specify does not exist in the password file.
password
The new password you want to define for the user name.

Passwords can be up to 32 characters long. Use only alphabetic and numeric characters for the password; do not use special characters.

Notes:
  1. Some browsers are unable to read and send passwords longer than eight characters. Because of this limitation, if you define a password longer than eight characters, the server recognizes either the complete password or just the first eight characters of the password as valid.
  2. The administrator user name and password are case-sensitive even if the operating system is not case-sensitive. Be sure to input the exact user name and password entered using the htadm command when accessing the Configuration and Administration forms.
-check password-file [user-name [password]]
Verifies the password for a user name already defined in the password file and lets you know if it is correct or not. If you enter the command with only password-file, you are prompted for the other parameters.
password-file
The path and name of the password file that contains the user name whose password you want to verify.
user-name
The user name whose password you want to verify. The command fails if the user name you specify does not exist in the password file.
password
The password that you want to verify. If the password you enter is the one defined for the user name, the command writes Correct to standard output and completes with a 0 return code. If the password you enter is not the one defined for the user name, the command writes Incorrect to standard output.
-create password-file
Create an empty password file.
password-file
The path and name of the password file that you want to create.

Examples

htcformat command

Purpose

Use the htcformat command to prepare a raw device or file to hold the proxy cache. This format command must be used before the device is specified for use with the proxy cache.

The device path must specify the raw device. See your file system documentation for details on how to access raw devices. Examples are available in Configuring proxy server caching.

Note:
Linux 2.2 kernels do not support caching to raw devices. On Linux platforms, only files and memory can be used for cache storage.

The minimum size for a Caching Proxy cache is 16392 KB, which is 2049 blocks.

Format

htcformat device [-blocksize <block size>] [-blocks number of blocks]
htcformat -file filepath [-blocksize block size] -blocks number of blocks

Parameters

-blocksize
This sets the size of blocks in the medium of the cache device. Block size is in bytes. The default is 8192 and should be used for all situations.
-blocks
Number of blocks to create on the device or in the file. When formatting a file, this argument is required in order to specify the file size. This argument also can be used to limit the amount of a particular device or partition to be used for cache storage. If no blocks argument is specified, as many blocks as will fit on the partition will be created.
-file
Format a file instead of a storage device.

Usage

The caching system additionally segregates cache files or devices into containers for indexing and garbage collection. The size of containers is set to a certain number of blocks; container size cannot be configured. In order for garbage collection to run, a minimum of two containers is required; the minimum cache size is 16392 KB.

The htcformat command rejects a format request that yields a cache device with fewer than two containers.

Examples

The following example formats a disk partition called c0t0d0s0 on Solaris.

htcformat /dev/rdsk/c0t0d0s0 

The following example formats a disk partition called lv02 on AIX.

htcformat /dev/rlv02

The following example formats a disk partition called d: on Windows.

htcformat \\.\d:

The following example formats a file named filecache to be about 1 GB large.

htcformat -file /opt/ibm/edge/cp/filecache -blocks 131072

ibmproxy command

Purpose

Use the ibmproxy command to start the server.

You can set all these flags (except -r) using the directives in the server configuration file.

It is common practice to create a file named README containing instructions or notices to be read by anyone new to the directory. By default, the ibmproxy command embeds any README file in the hypertext version of a directory. The README file instructions can also be set with the DirReadme configuration directive.

Format

ibmproxy [-Flag [-Flag [-Flag..]]]

Parameters

-nobg
Runs the server as a foreground process, not as a background process. The default is to run as a background process.
-nosnmp
Turns SNMP support off.
-p port-number
Listens on this port number. The default port number is 80. This flag overrides the Port directive specified in the configuration file. To use the default value or the value specified in the configuration file, omit this flag.
-r configuration-file
Specifies the file to use as the configuration file. You must use this flag if you want to start the server with a configuration file other than the default configuration file. This allows use of multiple configuration files.
-restart
Restarts a server that is currently running. The ibmproxy command gets the process number of the server that is running from the PidFile and sends the process number to the HangUP signal (HUP). It then reloads its configuration files and reopens its log files. To avoid corruption do not run two instances of the server at the same time using the same PidFile, log files, and proxy cache.

Because the http daemon must read the configuration file the server is currently using in order to access the PidFile, you must specify the same configuration file when restarting. If you used the -r flag and a specific configuration file when you started the server, then you must specify this flag and the same file with -restart.

-snmp
Turns SNMP support on.
-unload
On Linux, this removes the associated firewall rules.

Signal handling options also exist on Linux and UNIX platforms only. On Linux and UNIX platforms, the following options are available.

SIGTERM
The ibmproxy command stops and exits when complete. You can use SIGKILL or CANCEL to immediately terminate.
SIGHUP
If running, the ibmproxy command restarts, reloads the configuration file, and continues processing.

Examples