This chapter describes how to use the server's commands.
For a secure server, use the certutil command to process certificate requests for the clients and servers for whom you're acting as a Certificate Authority (CA). The output of the certutil command is a client or server certificate that has been signed with your private CA key.
Note: How to become your own CA and how to process certificate requests as a CA is described in Chapter 11. "Acting as a certification authority for a private Web network". You should follow the step-by-step instructions in that chapter unless you are familiar with the procedure.
certutil [-p validity-period] [-k ca-key-ring] < cert-req-file > cert-file-name
Note: The certutil command should be on one line. It is shown on more than one line because of formatting.
The < and > symbols, redirect the standard input and standard output.
For clients or servers who mail their certificate request to you through e-mail, it is the file into which you received the certificate request with your e-mail program.
For a certificate request on the same server, it is the file you specified for Save certificate request to file on the Create Key and Request Certificate form when you were requesting the server certificate.
To create a certificate that is valid for two years:
certutil -p 730 -k D:/WWW/BIN/cakeyfil.kyr < D:/WWW/BIN/CertReq.txt > D:/WWW/BIN/Cert.txt
Note: The certutil command must be on one line. It is shown here on more than one line because of formatting restrictions.
After you enter the command, you are prompted for the key ring password. This is the password for the key ring that holds the CA key.
If the certutil command cannot create the signed certificate, it returns an error message.
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.
This corresponds to the GET and POST methods from HTML forms. QUERY_STRING and CONTENT_LENGTH are environment variables. For a GET request, QUERY_STRING holds the form data. For a POST request, CONTENT_LENGTH is set and the form data is sent on standard input.
cgiparse -Flag [Modifier]
Flags have one-character equivalents: -k -f -v -r -i -s -p -c -q -P
'cgiparse -init > tempfile' 'CALL tempfile'
This will set the QUERY_STRING environment variable, regardless of whether the GET or POST method was used.
The cgiparse command may be called multiple times in the same script when the GET method is used, but it should only be called once if the POST method is used. With the POST method, after standard input is read, the next cgiparse would find standard input empty and would hang.
Note: When you receive one of these error codes, you may receive additional informational messages, too. The message varies depending on the command issued.
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.
cgiutils -Flag [Modifier]
If Modifier contains blanks, enclose it in quotes.
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
cgiutils -ce x-compress
cgiutils -cl en_UK
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.
cgiutils -expires "1 year 3 months 2 weeks 4 days 12 hours 30 mins"
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: Tuesday, 05-Jan-96 03:43:46 GMT Expires: Tuesday, 05-Jan-96 03:43:46 GMT
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 would include 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.
cgiutils -noel -expires "2 days" -nodate
HTTP/1.0 200 Virtual doc follows MIME-Version: 1.0 Server: IBM-ICS Expires: Tuesday, 07-Jan-96 03:43:46 GMT
Note: When you use htadm to add a user, change a password, or verify a password, you must enter the password on the command line. Because htadm 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 pstat command, for example).
htadm -Flag [Modifier]
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.
Passwords can be up to 32 characters long. Use only alphabetic and numeric characters for the password; do not use special characters.
Note: 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.
Passwords can be up to 32 characters long. Use only alphabetic and numeric characters for the password; do not use special characters.
Note: 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.
htadm -adduser d:\WINNT35\heroes.pwd clark superman "Clark Kent"
htadm -deluser d:\tcpip\etc\heroes.pwd clark
Use the htimage command to process clickable image maps. It allows defined regions within an image map to be associated with specific URLs. When users click on a defined region, the htimage command executes a CGI script that displays the URL associated with the region. When the server returns the URL associated with the region, it issues a 302 return code (Moved Temporarily) and a location header containing the URL.
Note:
The URL specified in the location header must be fully qualified, or absolute. Include the protocol, host, and request path in the URL. For example:http://hostname/filename.htmlThe Internet Connection Secure Server assumes, if the URL in the map file is not absolute, that the URL is local, and serves it directly. While this saves some network overhead, the browser thinks the original request was satisfied and continues to use the original request as the base for future requests.
When the URL is not fully qualified and the server finds the file locally, the Internet Connection Secure Server issues a Content-Location header which some browsers use to make future requests.
Many browsers understand the HTML tag, <BASE HREF= >, which can be used to specify the base URL, (for example, http://hostnamebase URL). When this tag is used, URLs that are not fully qualified are evaluated relative to this base URL and are correctly found.
The command is used in conjunction with a map file. Map files are text files that define regions within a graphics file by their x,y coordinates and map them to the various URLs. For additional information on using htimage and creating map files and images, see the Web design information on the Internet Connection Family Web site (http://www.ics.raleigh.ibm.com). The Web design information is accessible from the Front Page of your server.
Note: Currently the universal image file accepted by all browsers and servers is the GIF format. GIF is an 8-bit 256 color image file.
You cannot use htimage from the command line. You include it as part of an anchor tag within an HTML document, and it is called when the server processes that document.
The htimage command is located in the CGI Bin scripts directory you specified at installation. The installation default is C:\WWW\CGI-BIN.
Since htimage can only be called from an anchor tag within an HTML document, the syntax is shown as HTML markup.
<A HREF="/CGI-BIN/htimage/mapfile.txt"> <IMG SRC="/ICONS/image.gif" ISMAP></A>
This syntax description assumes that the default configuration file is being used. The default configuration file contains an Exec directive that maps requests beginning with /CGI-BIN/ to the directory that contains the htimage command.
The server uses everything following /htimage/ as the URL of the map file. If the server is using the default configuration and the URL contains only a file name, the server would look for the file in the document root directory.
The ISMAP attribute indicates that the graphic is an image map.
Following is a description of the map files that must be used with the htimage command. A map file is a text file. Each line of the file is in the following format:
region-identifier [region-definition] URL
Coordinates within parentheses identify a point relative to the top left corner of the image. The first number is the number of pixels to the right of the top left corner. The second number is the number of pixels down from the top left corner. There are several shareware programs available that can help you easily identify the coordinates of particular points within a graphic file.
default URL rectangle (x1,y1) (x2,xy) URL circle (x,y) r URL polygon (x1,y1) (x2,y2) (x3,y3) URL
For example, you might use the following HTML in a document:
<A HREF="/cgi-bin/htimage/mapit.txt"> <IMG SRC="/icons/mapimage.gif" ISMAP></A>
The above example calls the htimage command with a map file named mapit.txt. The mapit.txt file would define regions of the mapimage.gif graphic file. Because no path is specified for mapit.txt, the server would look for it on the document root directory. Following is an example of what mapit.txt might look like.
default http://brimstone/cgi-bin/go_home rectangle (50, 100) (200,200) http://brimstone/cgi-bin/go_to_it circle (100,300) 50 http://brimstone/pub/example.html polygon (450,350) (450,500) (150, 500) http://brimstone/pub/triangle.html
One example of a shareware program for determining the x,y coordinates is mapedit. You can obtain mapedit from the following URL:
http://sunsite.unc.edu/~boutell/mapedit/mapedit.html
Please note that output from mapedit is in NCSA format. It is different from the CERN examples shown.
The same examples in NCSA format require anchor tags within an HTML document as follows:
<a href="/cgi-bin/imagemap/mapit.txt"> <img src="/icons/mapimage.gif" ISMAP></a>
The map file will be an EBCDIC text file with the following format:
default http://brimstone/cgi-bin/go_home rect http://brimstone/cgi-bin/go_to_it 50, 100 200,200 circle http://brimstone/pub/example.html 100,300 100,350 poly http://brimstone/pub/triangle.html 450,350 450,500 150, 500
Use the whttpg command to start the server. The default setting is to export the /Public directory tree.
You can set all these flags (except -r and -noservice) using the directives in the server configuration file.
You can set the directory-browsing flags with the DirAccess configuration directive.
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, whttpg will imbed any README file in the hypertext version of a directory. The README file instructions can also be set with the DirReadme configuration directive.
whttpg [-Flag [-Flag [-Flag..]]] -noservice
If you know that the prior instance of the server has terminated, you can use the -B flag to set SO_REUSEADDR on to the servers listen ports before binding to them. This avoids the TIMED_WAIT delay. This flag is expecially useful if you have automation software that recognizes Internet Connection Secure Server termination and needs to start a replacement server as quickly as possible.
Note: If you specify the -r option and either the normalmode or sslmode option, you must specify normalmode or sslmode before -r.
whttpg -r d:\tcpip\httpd.config -p 80
If the Port directive is given in the configuration file, the -p flag is not required. The -p flag can be used to override the value set in the configuration file.