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
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.