Chapter 1. The HTTPPRM Keywords

HTTPD reads its configuration once, at start, from the DD name HTTPPRM. This chapter lists every keyword that HTTPD accepts, with its default, its range and what HTTPD does with a value that is wrong. The route keywords MOD and LOC have a chapter of their own (Chapter 2, “Routes and Authentication Policy”). The HTTPD User’s Guide explains how to write the member, in “Configuring HTTPD”.

HTTPD reads the file only at start. It has no command to read it again, so a change takes effect at the next start. The command F HTTPD,D CONFIG shows what HTTPD made of the file (Chapter 3, “Console Commands”).

The Rules of the File

The DD name is HTTPPRM. In the sample procedure it names one member of a PDS, and the procedure symbol M chooses the member (Chapter 4, “The Started Task and the Package”).
A line has the form KEY=value. HTTPD splits the line at the first equal sign. Everything after it, including further equal signs, is the value.
Blanks and tabs at both ends of the key and of the value are removed, so PORT = 8080 is valid. A blank inside a value stays.
The key may be in any case. HTTPD changes it to upper case. HTTPD does not change the case of a value. The tables below say where HTTPD compares a value without regard to case.
An empty line is ignored. A line is a comment if its first character after the leading blanks is \# or *. A comment takes the whole line. HTTPD knows no comment at the end of a line: the text after a value belongs to the value.
HTTPD reads at most 255 characters of a line at a time. It takes the rest of a longer line as the next line. There is no continuation line.
A line without an equal sign gives the message HTTPD026W with the first 40 characters of the line. HTTPD goes on.
A key that HTTPD does not know gives HTTPD029W with the key in upper case. HTTPD goes on.
HTTPD writes these messages to the console.
If a key is given twice, the last line counts. There are two exceptions. Each MOD line and each LOC line adds a route, and HTTPD does not look for a duplicate (Chapter 2, “Routes and Authentication Policy”). A second SMF line without TYPE= keeps the type of the first.
If the DD name is missing, HTTPD writes HTTPD020W and starts with the defaults. The defaults contain no route.
If a read error ends the read before the end of the member, HTTPD writes HTTPD038E and stops with CC 0008. HTTPD does not start on half a member.

A value that is not right gets one of four treatments, and the tables below say which one applies. HTTPD keeps the value that was valid before, either the default or an earlier line. HTTPD limits the value to the nearest value that is allowed. HTTPD reads a text that is not a number as 0, because it converts a number with the C function atoi: it takes the digits at the start of the value and ignores the rest. HTTPD refuses the value and the start. Only some of these cases write a message.

Listener and Connections

Keyword	Default	Rules
`PORT`	8080	The TCP port on which HTTPD listens. HTTPD has no keyword for an address: it listens on every address of the host. A number below 1 or above 65535, and a text that is not a number, give `HTTPD023E` with the number that HTTPD read (0 for a text). The earlier value stays.
`BIND_TRIES`	10	How many times HTTPD tries again to bind the port when the bind fails because the port is in use. HTTPD limits the value to 1 to 100.
`BIND_SLEEP`	10	The seconds that HTTPD waits before each of these tries. HTTPD limits the value to 1 to 100.
`LISTEN_QUEUE`	5	The length of the queue of connections that wait to be accepted. HTTPD limits the value to 1 to 100.

Table 1. Keywords of the listener

Before HTTPD binds the port, it takes an ENQ with the major name HTTPD and the minor name HTTPD.PORT.nnnnn, where nnnnn is the port with five digits. If another address space holds the ENQ, or the ENQ fails, HTTPD writes HTTPD037E and ends with CC 0008. A second HTTPD on another port starts.

If the bind fails with “address in use”, HTTPD closes every socket of the stack that has this port as its local port (HTTPD027I for each one). If it closed at least one, it waits 2 seconds and binds again. If the bind still fails, HTTPD writes HTTPD030E. Then it writes HTTPD030I and waits BIND_SLEEP seconds before each of at most BIND_TRIES further tries. If all tries fail, HTTPD writes HTTPD030E again and ends with CC 0008. Any other bind error ends the start at once. The same holds for an error of socket (HTTPD028E) and of listen (HTTPD031E). When the listener is ready, HTTPD writes HTTPD054I.

Worker Tasks and Time Limits

Keyword	Default	Rules
`MINTASK`	3	The least number of worker tasks. A value of 0 or less, and a text that is not a number, are ignored without a message: the earlier value stays. HTTPD limits a larger value to 255. If the value is above `MAXTASK`, HTTPD sets `MAXTASK` to the same value.
`MAXTASK`	9	The most worker tasks. The rules for a wrong value are those of `MINTASK`. At the end of the start HTTPD raises `MAXTASK` to the value of `MINTASK` if it is lower, whatever the order of the two lines.
`CLIENT_TIMEOUT`	10	The seconds that HTTPD waits for the client while it reads one line of a request: the request line or a header line. The time starts again for each line. A line of a request that comes on a connection that has served a request before uses `KEEPALIVE_TIMEOUT` instead. A value of 0 or less, and a text that is not a number, are ignored without a message. HTTPD limits a larger value to 255. When the time is up, HTTPD closes the connection.
`KEEPALIVE_TIMEOUT`	5	The seconds that HTTPD waits for the lines of the next request on a connection that stays open. HTTPD limits the value to 1 to 255.
`KEEPALIVE_MAX`	100	The number of requests a connection carries before HTTPD closes it. HTTPD answers the request after that number with `Connection: close`, so a connection carries the value plus one request. HTTPD limits the value to 1 to 255.
`CLIENT_TIMEOUT_MSG`	1	A number. A value above 0 means yes, any other value and a text that is not a number mean no. If yes, HTTPD writes one line to the console when a time limit ends while the client has sent at least one character of the line. The line has no message ID. It reads `client xxxxxxxx on socket n timed out after s seconds` and gives the address of the client block in hex, the socket and the seconds.
`CLIENT_TIMEOUT_DUMP`	1	The same rules. If yes, HTTPD also writes a dump of the characters received so far, with the title `Receive Buffer`, at such a time-out.
`CLIENT_STATS`	1	The same rules. HTTPD stores the flag and the display module `HTTPDSRV` shows it as `STATS`. No other code of HTTPD reads it, so it changes nothing that HTTPD does or writes.

Table 2. Keywords of the worker tasks and of the time limits

The time limits count in whole seconds. D CONFIG shows the values of MINTASK, MAXTASK, CLIENT_TIMEOUT, KEEPALIVE_TIMEOUT and KEEPALIVE_MAX (Chapter 3, “Console Commands”).

Files and Character Set

Keyword	Default	Rules
`DOCROOT`	/www	The UFS directory that HTTPD puts in front of the path of a request when it serves a static file. The value must begin with a slash. Another value is ignored without a message, and the earlier value stays. HTTPD removes one slash at the end of a value that is longer than one character. HTTPD keeps at most 127 characters.
`UFS`	1	A number. A value above 0 means yes, any other value and a text that is not a number mean no. If yes, HTTPD creates its UFS system at start. If that fails, HTTPD writes `HTTPD044W` and goes on without it. If no, HTTPD does not create the UFS system and serves no file from it. Leave it at the default.
`CODEPAGE`	CP037	The table that translates between the ASCII on the wire and the EBCDIC in HTTPD. The names are `CP037`, `IBM1047` and `LEGACY`, in any case. `LEGACY` is the table of HTTPD 3.3.x. An empty value means `CP037`. Another name gives `HTTPD070E`, and HTTPD uses `CP037`. HTTPD keeps at most 15 characters of the value as written; `D CONFIG` shows them.

Table 3. Keywords of the files and of the character set

Authentication Values

Which route needs a login is a property of the route, set with AUTH= (Chapter 2, “Routes and Authentication Policy”). There is no keyword that sets a login policy for all routes. Three of the four keywords here set the name of the server and the life of a login. The fourth, RES_NOPROFILE, sets what a route with RES= does when the security product has no profile for its resource.

Keyword	Default	Rules
`REALM`	SMF ID	The name of the server. It is the realm in the `WWW-Authenticate: Basic` header and part of the login form. The default is the SMF ID of the system: up to four characters, ending at the first blank. If the system has none, the default is `MVS`. A value has 1 to 64 characters. It must not contain a control character or one of the characters double quote, backslash, `<`, `>` and `&`. Another value gives `HTTPD424W` with the first 40 characters, and the default stays (or the value of an earlier line).
`SESSION_TIMEOUT`	30	The minutes after which HTTPD drops the login of a client that is idle. HTTPD reads the value as a number. A negative number and a text that is not a number give 0, a number above 65535 gives 65535. A value of 0 switches this limit off.
`SESSION_MAXAGE`	480	The minutes after which a login ends whatever the client does, counted from the login. Activity does not renew it. The rules for a wrong value are those of `SESSION_TIMEOUT`. A value of 0 switches this limit off.
`RES_NOPROFILE`	ALLOW	`ALLOW` or `DENY`, in any case. The value ends at the first blank. It decides what a route with `RES=` does when no profile covers its resource. With `ALLOW` the request passes, and the start writes `HTTPD425W`. With `DENY` the request gets status 403, and the start writes `HTTPD426W`. Any other value is fatal: HTTPD writes `HTTPD427E` with the first 16 characters of the value and then `HTTPD420E`, and the start ends with CC 0008.

Table 4. Keywords of the authentication values

A login that a request is using must not be dropped. HTTPD therefore compares the two limits with CLIENT_TIMEOUT at the end of the start. If SESSION_TIMEOUT in seconds is not larger than CLIENT_TIMEOUT, HTTPD writes HTTPD026E. If SESSION_MAXAGE in seconds is not larger, HTTPD writes HTTPD032E. Both messages are warnings: HTTPD starts. A limit of 0 is not compared. The server drops logins about once a minute, if at least one of the two limits is above 0.

Note: The messages HTTPD026W and HTTPD026E have the same number and different meanings. The first is a line that is not a keyword line. The second is the check of SESSION_TIMEOUT.

The rules of RES_NOPROFILE:

One value for the whole server. The keyword is not an option of a route. It applies to every route with RES=, except the routes with AUTH=NONE, which HTTPD does not check (“The Login Mode of a Route”).
The check is made for each request. With DENY a request to a route whose resource has no profile gets status 403 and the body 403 Forbidden: no RACF profile protects this resource. The class and the resource name are not sent. A request that a profile refuses gets the plain 403 Forbidden. A request without a login gets the 401 of the first stage, as before.
A profile that is defined later needs no restart. The check looks at the profile as the security product holds it at the time of the request. Under RAKF the product holds a new profile after the started task RAKFPROF has run (“RES=: Checking a Profile” in the HTTPD User’s Guide). Until then the route answers 403 with the body above. HTTPD426W is written at the start only, so it stays in the log.
HTTPD sees only the return code 4. The security product answers 4 when no profile covers the resource. HTTPD cannot tell why the product had none to apply, and with DENY every return code 4 refuses. This book does not state in which conditions, other than a missing profile, a product answers 4.
The default does not change anything. Without the keyword, or with ALLOW, the check passes the return codes 0 and 4 and refuses every other one, as in the releases before 4.5.0.
A misspelled value is fatal on purpose. HTTPD does not fall back to ALLOW. A keyword that exists to close a gate must not leave the gate open when it is misspelled.

Routes and Modules

Keyword	Default	Rules
`MOD`	none	A route to a program: `MOD=program pattern AUTH=mode RES=class:resource`. Each line adds one route. The whole syntax is in Chapter 2, “Routes and Authentication Policy”.
`LOC`	none	A route without a program, for a path that HTTPD serves as a static file but with a login: `LOC=pattern AUTH=mode RES=class:resource`. See Chapter 2, “Routes and Authentication Policy”.
`RESIDENT`	YES	`YES` or `NO`, in any case. Text after the first blank is ignored. With `YES` HTTPD holds each module of a `MOD` route from the start to the end, so a request does not fetch it from the library. With `NO` each request fetches the module, so a new level of a module is used at once. Another value gives `HTTPD443W` and the earlier value stays. Chapter 2, “Routes and Authentication Policy” describes what HTTPD does at start.
`CGI_CONTEXT_POINTERS`	255	The size of the table in which modules register their context blocks: the table has this value plus one entries. HTTPD reads the value as a number. A negative number is ignored without a message. A number above 255 gives 255. A text that is not a number gives 0. A module gets a block through the function `http_cgictx_get` (Chapter 6, “The Server Module Interface”).
`CGI`	none	The old name of `MOD`. HTTPD writes `HTTPD410W` for each line and then reads the line as a `MOD` line. Use `MOD`.

Table 5. Keywords of the routes and of the modules

Diagnostics and Recording

Keyword	Default	Rules
`DEBUG`	0	A number. A value above 0 switches the trace on, any other value and a text that is not a number switch it off. There is only one level: 5 means the same as 1. With the trace on, HTTPD opens the DD name `HTTPDBG` for output and writes its trace lines to it. If the DD name cannot be opened, HTTPD writes `HTTPD020E` with the `errno` and `HTTPD021I`, and the trace goes to the DD name `SYSTERM`. If a write to the trace fails, HTTPD writes `HTTPD039W` once and switches the trace off until the next start. The server goes on.
`TRACE`	0	The number of records of the request trace: 0 or a number from 16 to 1024. 0 is off. The request trace is not the trace of `DEBUG`. It keeps, for each request, the worker that serves it, the time of each phase of the request and a few counters, in a table of the server. It does not change what the server does. The target `TRACE` of `/.dsrv` shows the table (“Target TRACE”). HTTPD reads the value at the start, so a change takes a restart. Any other value, and a text that is not a number, give `HTTPD444W` and the trace stays off. With a valid number HTTPD takes one block of storage from the region of the server, 32 bytes plus 136 bytes for each record (34,848 bytes for 256 records, 139,296 bytes for 1024), and writes `HTTPD066I`. If the region has no room for the block, HTTPD writes `HTTPD067W` and the server runs without the trace. The server frees the block at the stop. The table holds the most recent requests: when it is full, a new request takes the record of a finished one. Switch the trace on to find a problem and off after it. The table holds the client address and the path of every request.
`SMF`	NONE	`SMF=level` or `SMF=level TYPE=nnn`. The level is `NONE`, `ERROR`, `AUTH` or `ALL`, in any case. HTTPD compares only as many characters as the word has, so `ERR` is read as `ERROR`. Another word, and an empty value, give `HTTPD431W` and the earlier level stays. `TYPE=` is the SMF record type, 128 to 255, default 243. HTTPD looks for it anywhere in the value, in upper case only. Another number gives `HTTPD432W` and the earlier type stays. Chapter 8, “SMF Records” describes the records.

Table 6. Keywords for diagnostics and for recording

Keywords That Are No Longer Valid

These keywords are known to HTTPD, and each gives a message. A member from an earlier release starts, except in one case.

Keyword	What HTTPD does
`LOGIN`	A global rule for a login has no place any more: the login is set per route with `AUTH=`. An empty value, and a value that consists only of `NONE` (several words are separated by commas), give `HTTPD048W`. HTTPD ignores the line and the start goes on. Every other value (`ALL`, `CGI`, `GET`, `HEAD`, `POST`, and a word that HTTPD does not know) gives `HTTPD048E` with the value, and the start ends with `HTTPD420E` and CC 0008. Such a value required a login for every route without a policy of its own, and these routes would be open without the refusal. HTTPD does not turn the value into route policies: change the routes.
`TZOFFSET`	HTTPD ignores the value and writes `HTTPD025W` with the offset that applies, and `HTTPD025I`. There is no keyword for the time zone. The offset comes from the variable `TZ`, or from the time zone of the system if there is none. To choose another offset, set `TZ` in the DD name `SYSENV` or `ENVIRON` of the procedure.
`RECLAIM=`	This is an option of a `MOD` route, not a keyword. HTTPD ignores the value and writes `HTTPD422W` for each use. The storage of a module is always released after the request.

Table 7. Retired keywords

Note: A line LOGIN ALL without an equal sign is not a LOGIN line for HTTPD. It is a line without an equal sign, and it gives HTTPD026W only. The start goes on, and the routes keep the policy that they have.

Parameters That Are Not in the Member

Three names look like keywords but are not. HTTPD reads STCUSER= and STCGROUP= from the PARM of the procedure, and not from the member. Chapter 4, “The Started Task and the Package” describes them. A line STCUSER=HTTPD in the member gives HTTPD029W, as for any unknown key.

The third name is CONFIG=. It has no effect. HTTPD writes HTTPD024W and HTTPD024I, which says to choose the member with S HTTPD,M=member.

What Stops the Start

HTTPD ends with CC 0008 and without a listener in these cases. Every other problem in the member gives a message, and the start goes on.

Message	Cause
`HTTPD038E`	A read error before the end of the member.
`HTTPD420E`	A route lost its policy: `HTTPD419E` (a route that could not be registered), `HTTPD411E` (an unknown `AUTH=` value) or `HTTPD048E` (a retired `LOGIN` that required a login). Also `HTTPD427E`, a value of `RES_NOPROFILE` that is neither `ALLOW` nor `DENY`. HTTPD reads the whole member first, so it writes all of these messages before it stops. It stops before it opens the port. Chapter 2, “Routes and Authentication Policy” has the details.
`HTTPD037E`	Another address space already serves the port.
`HTTPD028E`, `HTTPD030E`, `HTTPD031E`	The stack refused the socket, the bind or the listen.

Table 8. Causes of a refused start

Reading Back the Result

The command F HTTPD,D CONFIG writes the values that HTTPD settled on, and the name of the member that it read (Chapter 3, “Console Commands”). It shows the port, the tasks, the time limits, the two login limits, the document root, the code page, the realm, the SMF type and level, the state of RESIDENT and the value of RES_NOPROFILE. It does not show the other keywords. The display module HTTPDSRV shows the whole control block of the server, including those (Chapter 7, “The Display Modules”).