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.
- Keyword search
$ QUERY_STRING="is+2%2B2+really+four%3F"
$ export QUERY_STRING
$ cgiparse -keywords
is
2+2
really
four?
$
- Parsing all form fields
$ export QUERY_STRING="name1=Value1&name2=Value2%3f+That%27s+right%21";
$ cgiparse -form
FORM_name1='Value1'; FORM_name2='Value2? That'\'s right!'
$ eval `cgiparse -form`
$ set | grep FORM
FORM_name1="Value1"
FORM_name2="Value2? That's right!"
$
- Extracting only one field value
$ QUERY_STRING="name1=value1&name2=Second+value%3F+That'\'s%27s
$ cgiparse -value name1
value1
$ cgiparse -value name2
Second value? That's right!
$
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
- This example calculates the expiration date for the Expires: header.
cgiutils -expires "1 year 3 months 2 weeks 4 days 12 hours 30 mins"
- The following example specifies a status code and reason, and
sets the Expires: header equal to the Date: header.
cgiutils -status 200 -reason "Virtual doc follows" -expires now
This
might produce headers similar to these:
HTTP/1.0 200 Virtual doc follows
MIME-Version: 1.0
Server: IBM-ICS
Date: Tue, 05 Jan 1996 03:43:46 GMT
Expires: Tue, 05 Jan 1996 03:43:46 GM
The cgiutils command
automatically produces the Server: header because
it is available in the CGI environment. The Date: field
is also automatically generated unless the -nodate flag
is specified.
This includes a blank line after the output to
mark the end of the MIME header section. If you want to follow this
with some more headers yourself, use the -noel (NO-Empty-Line)
flag as shown in the next example.
- If you do not want the blank line after the header line, use the -noel flag:
cgiutils -noel -expires "2 days" -nodate
HTTP/1.0 200 Virtual doc follows
MIME-Version: 1.0
Server: IBM-ICS
Expires: Tue, 07 Jan 1996 03:43:46 GMT
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
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:
- 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.
- 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:
- 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.
- 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
- To add a user to a password file:
- Linux and UNIX systems:
htadm -adduser /opt/ibm/edge/cp/server_root/protect/heroes.pwd
clark superman "Clark Kent"
- Windows systems:
htadm -adduser "C:\Program Files\IBM\edge\cachingproxy\cp\server_root\protect\
heroes.pwd" clark superman "Clark Kent"
Note:
The htadm command must
be on one line. It is shown here on more than one line for readability.
Enter the actual command on one line with at least one space between clark and superman.
- To delete a user from a password file:
- Linux and UNIX systems:
htadm -deluser /opt/ibm/edge/cp/server_root/protect/
heroes.pwd clark superman "Clark Kent"
- Windows systems:
htadm -deluser "C:\Program Files\IBM\edge\cachingproxy\cp\server_root\protect\
heroes.pwd" clark superman "Clark Kent"
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
- To start the server on port 8080, using the /usr/etc/ibmproxy.conf
configuration file instead of the default, /etc/ibmproxy.conf, enter:
ibmproxy -p 8080 -r /usr/etc/ibmproxy.conf
- On AIX, to start a server with the default configuration file
using the System Resource Controller, enter:
startsrc -s ibmproxy
If
the default configuration file does not exist, the ibmproxy command
exports the /Public directory tree. This tree can contain soft links
to other directory trees.