Chapter 2. Routes and Authentication Policy

A route ties a path of a request to what HTTPD does with it. A route is written in the HTTPPRM member (Chapter 1, “The HTTPPRM Keywords”) as a MOD line or a LOC line. A MOD route names a program, a server module that HTTPD links to. A LOC route has no program: HTTPD serves the path as a static file. Both can carry a policy, which says who may use the route. This chapter is the full description of the syntax, of the matching and of the policy. The HTTPD User’s Guide shows how to build routes for common cases, in “Routes and Server Modules” and in “Authentication and Security”.

The Syntax of MOD and LOC

The rules for the line as a whole:

• The tokens are separated by blanks or tabs. The options may come in any order, but after the pattern.
• HTTPD reads at most 8 tokens. It ignores the rest of the line without a message.
• A token that is not a pattern and not one of the options above gives HTTPD413W with the token, and HTTPD ignores it. The route is still registered. See the warning in “Messages While HTTPD Reads the Routes”.
• An option may stand twice. For AUTH= the last valid mode counts, but a mode that is not valid refuses the route whatever follows. For RES= the last well-formed value counts.
• Each line adds one route. HTTPD does not check for a route that is there already, and it sets no limit on the number of routes.
• CGI= is the old name of MOD=. HTTPD writes HTTPD410W and reads the line as a MOD line.

The member may contain these lines:

MOD=MVSMF /zosmf/restconsoles/*   AUTH=TOKEN RES=FACILITY:MVSMF.CONSOLE
MOD=MVSMF /zosmf/*                AUTH=TOKEN
MOD=HTTPDSRV /.dsrv               AUTH=FORM
LOC=/admin/*                      AUTH=BASIC RES=FACILITY:HTTPD.ADMIN
LOC=/*                            AUTH=NONE

The Pattern Language

HTTPD compares the path of the request with the pattern of each route. The path is the part of the URI before the first question mark. HTTPD decodes it first: each %xx becomes the character. A plus sign stays a plus sign (“URL Decoding and Escaping”). The query string never takes part in the match.

A pattern is a wildcard pattern if it contains * or ?. Any other pattern is a plain path.

Some examples:

A prefix therefore needs a trailing *. The pattern /admin claims only that one path.

The First Match Wins

HTTPD keeps all routes, MOD and LOC together, in one table in the order of the lines. For a request it walks the table from the top and uses the first route that matches. It never looks for the best match, and it does not test prefixes before extensions. The order of the lines is the only thing that sets the priority.

Two consequences follow.

• A route with a general pattern hides every route below it that it also matches. The line LOC=/* before MOD=MVSMF /zosmf/* sends every request to the LOC route. HTTPD gives no message.
• The policy of the first route is the whole policy of the request. The policy of a later route that would match too does not apply.

Write the specific routes first and the general ones last.

A request that no route matches is public. HTTPD serves it as a static file (“Static Routes”).

The Fixed Paths

The paths /login and /logout belong to HTTPD. A request for one of them goes to the login code of HTTPD whatever the routes say and whatever the method is, and no policy applies. The match ignores the case of the letters and needs the whole path. Do not give a route to these two paths.

The paths that match /login.* and /favicon.* are exempt from the policy for the methods GET and HEAD, so that the login page can load its own parts. The case of the letters counts here. The route still applies: HTTPD only skips the check of the login. A MOD route that claims such a path runs its module without a login.

Routes with an Extension

If a MOD line has no pattern, HTTPD builds one from the program name: *. followed by the program name in lower case. The line MOD=REXX becomes the pattern *.rexx.

A pattern that starts with *. makes an extension route, whether HTTPD built it or the line states it. For a request on an extension route HTTPD sets the variable SCRIPT_FILENAME to the document root (DOCROOT, Chapter 1, “The HTTPPRM Keywords”) followed by the path of the request. If HTTPD cannot set the variable, it answers with an internal error (status 500) and does not link to the module. No other route gets this variable from HTTPD.

The pattern is a wildcard pattern, so the match is case sensitive: *.rexx does not match /a/b.REXX. The position in the table counts as for any other route.

The Login Mode of a Route

Each route has one of four modes. The mode says whether the route needs a user, and how HTTPD asks a client that has none.

The rules for a missing or a wrong mode:

• A line with RES= and without AUTH= gets the mode BASIC, because a resource check needs a user.
• A line with AUTH=NONE and with RES= gives HTTPD414W. The mode NONE wins, and HTTPD does not check the resource.
• A mode that is not one of the four gives HTTPD411E with the first 24 characters of the value. HTTPD refuses the route, and the start ends (“Messages While HTTPD Reads the Routes”).

The mode does not choose the way the client proves who it is. Before HTTPD looks for the route, it tries these sources in this order and uses the first one that gives a user.

1. The cookie Sec-Token, if it holds a valid session token.
2. The cookie LtpaToken2, if it holds a valid session token.
3. The header Authorization: Bearer with a session token.
4. The header Authorization: Basic with user and password.

If neither cookie gives a user, HTTPD reads the Authorization header. A Bearer header ends the search, also when its token is not valid. A header that is neither Bearer nor Basic gives no user.

The login is bound to the address of the client. A user that logged in from another address does not count. Every route accepts every source, whatever its mode. The mode only says what HTTPD sends to a client that has no login.

What Each Mode Answers

HTTPD runs the check in two stages, before it serves a file or links to a module. The first stage asks for a user. The second stage applies only if the route has RES=. It asks RACF whether the user may read the resource. The two stages apply to MOD routes and to LOC routes in the same way, for the methods GET, HEAD, PUT, POST and DELETE.

A request with a login, to a route with RES=, goes to the second stage. If the user may not read the resource, HTTPD answers with status 403, the headers Cache-Control: no-store and Content-Type: text/plain, and the body 403 Forbidden. Otherwise HTTPD goes on with the request.

The Resource Check

Limits

Messages While HTTPD Reads the Routes

HTTPD reads the whole member before it decides whether to start. The messages below come while it reads. They go to the console.

A route that asked for a login or for a resource, and that HTTPD cannot build, is never dropped quietly. Without the route the path would be public. HTTPD therefore writes HTTPD419E for each such line. When it has read the whole member, it writes HTTPD420E, ends with CC 0008 and does not open the port. These lines belong to this case:

• A line with an AUTH= value that is not valid.
• A line with RES= for which HTTPD gets no storage.
• A line in which an option stands where the program name or the path belongs. An example is LOC=AUTH=BASIC RES=FACILITY:HTTPD.ADMIN. For such a line HTTPD419E gives the whole line. HTTPD checks the options to decide: a line that asks for a login or a resource ends the start. A line with only AUTH=NONE or without options gives HTTPD421W or HTTPD415W and the start goes on.
• A line for which HTTPD gets no storage to split it into tokens.
• A route with a login or a resource that HTTPD cannot add to the table.

A route with the mode NONE, and a route without any policy, that HTTPD cannot register give a warning (HTTPD035W, HTTPD423W) and the start goes on. Losing them cannot make the path less protected than the line asked.

Static Routes

A LOC route has no program. The two stages of the check apply as described above. If the request passes, HTTPD serves the path as a static file from the document root (DOCROOT, Chapter 1, “The HTTPPRM Keywords”), for the methods GET, HEAD, PUT, POST and DELETE. A request that no route matches is served the same way, without a check.

A LOC route is the way to protect a part of the document tree. The route does not change what HTTPD serves. It decides who may get it.

Three rules help:

• A route with the mode NONE and a general pattern, as in LOC=/* AUTH=NONE, claims every path that is not claimed above it. It is a good last line. As a first line it hides all that follows.
• A pattern that ends in /* does not claim the directory itself. Add a plain-path route for it.
• The login page lives in the document tree. Its paths /login.* are exempt (“The Pattern Language”), so a LOC=/* AUTH=FORM route still lets the page load.

Resident Modules

By default (RESIDENT=YES, Chapter 1, “The HTTPPRM Keywords”) HTTPD loads each module of a MOD route once, after it has read the member and before it serves any request. It holds the copy until the end. A request then finds the module in storage and does not fetch it from the library. HTTPD does this once for each program name, however many routes use the name. The comparison of the names ignores the case.

A module that HTTPD does not hold still works. Each request fetches it, as with RESIDENT=NO. The start shows why in a message.

A module that HTTPD holds is loaded in the main task of the server. The end of the server releases it. The command D CONFIG shows the number of modules held (Chapter 3, “Console Commands”).

When a Module Does Not Run

If HTTPD cannot run the module of a MOD route, or the module ends badly, HTTPD first releases the storage of the module (a failure of that gives HTTPD906W with the program name and the return code). Then it tells the client and the operator.

For the client, HTTPD sends status 503 with the header Content-Type: text/plain if the module has not sent a status line yet. Then it sends the line External program name text to the body, where text is one of the reasons in the table. For the operator, HTTPD writes HTTPD908E with the program name and the same text.

Only the abends leave a dump to look for. The other reasons mean that the module did not run, or ended by itself.