Appendix A:  HTTP Metainformation

This appendix provides a quick reference to HTTP metainformation, for use in metafiles, PHP scripts, and other mechanisms that can manipulate HTTP header fields. For most transactions, Stronghold determines the proper metainformation to use and you do not need to intervene. There are five kinds of HTTP metainformation fields:

General Headers

Both client requests and server responses use the general header fields listed in this section, although some are more commonly used by one or the other.

Cache-Control

Syntax: Cache-Control: directive1 [directive2 directive3 ...]
Context: general
Cache-Control sets the cache options for the current transactions. Requests and responses use separate directives.

The following are the possible request directives:

Cache Request Directive Description

no-cache

Do not cache the request.

no-store

Remove the information immediately after forwarding the request.

max-age=seconds

Do not send responses older than the value specified by seconds.

max-stale[=seconds]

If max-stale appears alone, Stronghold is allowed to return expired data. If seconds is specified, Stronghold only sends data that has been expired for less than the given number of seconds.

min-fres =seconds

Return the data only if it has not expired by the specified number of seconds.

only-if-cached

Return only cached data.

The following are the possible response directives:

Cache Response Directive Description

public

Any host may cache the data.

private

A shared cache is not allowed to cache the data.

no-cache

Do not cache.

no-store

Remove the information immediately after forwarding the response.

no-transform

Do not convert the data to another format.

must-revalidate

Revalidate the data.

proxy-revalidate

Except when using a private cache, the client must revalidate the data.

max-age=seconds

The data expires in the specified number of seconds.

Connection

Syntax: Connection: option1 [option2 ...]
Context: general
Connection specifies options specific to the current connection. For example, when keepalive is enabled, the client or server can use this field to close the connection:
Connection: close

Date

Syntax: Date: date time
Context: general
This field indicates the current date and time. RFC 1123 specifies the most current format for date and time, which looks like this:

Thu, 14 November 1996 09:46:03 GMT
However, you can also use the older RFC 850 and ANSI C formats for backward compatability:

Thursday, 14-Nov-96 09:46:03 GMT
Thu Nov 6 09:46:03 1996

MIME-Version

Syntax: MIME-Version: version
Context: general
If this field is not included, the default value is 1.0. Otherwise, MIME-Version specifies the version of MIME used in the transaction. It is unnecessary if the message body does not conform to MIME.

Pragma

Syntax: Pragma: no-cache
Context: general
Pragma is generally an HTTP 1.0 field; in HTTP 1.1, Cache Control takes its place. The only value is "no-cache," which instructs a proxy to request the document from a server instead of retrieving it from the local cache.

Transfer-Encoding

Syntax: Transfer-Encoding: type
Context: general
This field specifies the type of encoding applied to the message body. The only value currently defined by HTTP is "chunked."

Upgrade

Syntax: Upgrade: protocol/version
Context: general
When using the response code 101 (Switching Protocols), this field specifies the prefered protocol and version.

Via

Syntax: Via: protocol host ["comment"] ...
Context: general
HTTP 1.1 requires that gateways and proxies use this field to specify which protocols and hosts process the transaction in transit between the client and the server. It is used to track message forwards, avoid request loops, and identify the protocol capabilities of intermediate hosts.

Client Request Headers

Clients include the headers listed in this section when transmitting requests to servers.

Accept

Syntax: Accept: type/subtype1[; q=qvalue][, type/subtype2[; q=qvalue] ...]
Context: request
The Accept header specifies one or more media types that the client can accept, ranked using an optional qvalue. The qvalue is a floating point number between 0 and 1, with 1 being the most preferred media type.

Accept-Charset

Syntax: Accept-Charset: char-set1[; q=qvalue][, char-set2[;q=qvalue]...]
Context: request
This header field specifies one or more character sets that the client can accept, ranked using an optional qvalue. The qvalue is a floating point number between 0 and 1, with 1 being the most preferred character set.

Accept-Encoding

Syntax: Accept-Encoding: encoding-type1[, encoding-type2 ...]
Context: request
This header field specifies one or more encoding schemes that the client can accept. It can contain as many encoding types as needed. If this field is omitted or is empty, then the client does not accept any encoding types.

Accept-Language

Syntax: Accept-Language: language1[; q=qvalue][, language2
[; q=qvalue] ...]
Context: request
This header field specifies one or more languages that the client can accept, ranked using an optional qvalue. The qvalue is a floating point number between 0 and 1, with 1 being the most preferred characters set. Language is a two-character abbreviation such as "en" for English, "de" for German, and so on.

Authorization

Syntax: Authorization: scheme credentials
Context: request
When Stronghold responds to a request with a WWW-Authenticate header, the client replies with the Authorization header, specifying an authentication scheme (such as basic or digest) and credentials (a username and password).

Cookie

Syntax: Cookie: name=value
Context: request
If a cookie is set for the requested URL, the client sends the cookie name with the request. If the client specifies multiple cookies, they must be separated by semicolons.

From

Syntax: From: email-address
Context: request
The From header specifies the email address of the user sending the request.

Host

Syntax: Host: hostname[:port]
Context: request
This header specifies the hostname and, optionally, the port number of the URI. HTTP 1.1 requires this field, for distinguishing between multiple hosts on the same server platform when the URL is ambiguous.

If-Modified-Since

Syntax: If-Modified-Since: date
Context: request
Clients can use this header to instruct the server to send the document only if it has been modified since the date. If the document has not been modified since the given date, Stronghold responds with status code 304 (Not Modified). Usually, the client then retrieves a local cached copy.

If-Match

Syntax: If-Match: entity-tag
Context: request
This is a conditional header that requests the document only if it matches the specified entity-tag, which can take wildcard strings.

If-None-Match

Syntax: If-None-Match: entity-tag
Context: request
This is a conditional header that requests the document only if it does not match the specified entity-tag, which can take wildcard strings.

If-Range

Syntax: If-Range: entity-tag|date
Context: request
This is a conditional header that can only be used in conjunction with a Range header. The value can be either an entity tag or a date, indicating a partial entity that the client has already received.

If-Unmodified-Since

Syntax: If-Unmodified-Since: date
Context: request
This is a conditional header that requests a document only if it has not been modified since the given date. The value for date should follow the format specified in the Date header.

Max-Forwards

Syntax: Max-Forwards: n
Context: request
This header limits the number of hops between the client and server to n.

Proxy-Authorization

Syntax: Proxy-Authorization: credentials
Context: request
When Stronghold acts as a proxy server, clients use this header instead of the Authorization header.

Range

Syntax: Range: bytes=n-m[,n-m ...]
Context: request
A client can use this header to request one or more segments of a document. The segments are specified with bytes ranges separated by commas.

Referer

Syntax: Referer: URL
Context: request
The Referer header indicates the URL of the document that refers to the requested URL, meaning the document in which the user followed a link to the request document.

User-Agent

Syntax: User-Agent: string
Context: request
This header gives information about the client, such as the application, version number, platform, and so on.

Server Response Headers

Stronghold uses the headers listed in this section to respond to client requests.

Accept-Ranges

Syntax: Accept-Ranges: bytes|none
Context: response
When a client requests a segment of a document using the Range header, Stronghold responds with Accept-Ranges to indicate a successful range request.

Age

Syntax: Age: seconds
Context: response
Stronghold can use this header to specify the age of the message body in seconds.

Proxy-Authenticate

Syntax: Proxy-Authenticate: scheme realm
Context: response
When Stronghold responds with the 407 (Proxy Authentication Required) status code, is also sends this header to indicate the authentication scheme (such as basic or digest) and the authentication realm (set with the AuthName directive).

Public

Syntax: Public: method1[,method2,method3 ...]
Context: response
Public indicates one or more request methods that Stronghold supports. To indicate methods supported only for an individual URI, use the Allow header instead.

Retry-After

Syntax: Retry-After: date|seconds
Context: response
When Stronghold uses the 503 (Service Unavailable) status code, it also sends this header to indicate when the client should resubmit the request. The value can be either a date (in a format specified by the Date header) or an integer indicating a period of seconds.


Server

Syntax: Server: string
Context: response
The Server header specifies the name and version number of the server, including its Apache core. In Stronghold Web Server 3.0 Administration Guide's case, this is
Server: Stronghold/3.0 Apache/1.3.1

Set-Cookie

Syntax: Set-Cookie: name=value[; expires=date; path=pathname; domain=domain; secure]
Context: response
The Set-Cookie header passes a cookie to the client for use with the requested URL. Only the name value is required.

Vary

Syntax: Vary: *|headers
Context: response
The Vary header indicates that the requested document exists in more than one form, and that the form sent with the response is affected by one or more specified request headers. The value is "*" if the document form is affected by factors other than request headers.

Warning

Syntax: Warning: code host[:port] "string"
Context: response
Stronghold uses the Warning header to expound on status code information. This is usually used by caching proxies. Code is a two-digit code, and string is the recommended descriptive string for the code, as follows:

Code String

10

Response is stale

11

Revalidation failed

12

Disconnected operation

13

Heuristic expiration

14

Transformation applied

99

Miscellaneous warning (or an arbitrary string)

Host is the hostname of the server or one of its virtual hosts, with an optional port number.

WWW-Authenticate

Syntax: WWW-Authenticate: scheme realm
Context: response
When Stronghold responds with the 401 (Unauthorized) status code, it also sends this header to indicate the authentication scheme (such as basic or digest) and the realm (set with the AuthName directive), so that the client can return the appropriate username and password.

Entity Headers

Entity headers supply information about the message body in an HTTP message, which can be either a client request or a server response.

Allow

Syntax: Allow: method1[,method2,method3 ...]
Context: entity
This header indicates acceptable request methods for the requested URI. When Stronghold uses this header in a response, it is combined with the 405 (Method Not Allowed) status code.

Content-Base

Syntax: Content-Base: URI
Context: entity
Content-Base specifies an absolute URI to use as a base for all relative URLs.

Content-Encoding

Syntax: Content-Encoding: encoding-type[,encoding-type,encoding-type ...]
Context: entity
This header specifies one or more encoding types used to encode the message body, in the order in which they were used. The possible values for encoding-type are as follows:
"gzip" "x-gzip" "compress" "x-compress"

Content-Language

Syntax: Content-Language: language
Context: entity
Content-Language specifies the language used in the message body, using a two-character code such as "en" for English, "de" for German, and so on.

Content-Length

Syntax: Content-Length: bytes
Context: entity
This header gives the length of the message body in bytes. In dynamic requests, this figure is often unknown; in that case, the header can be omitted.

Content-Location

Syntax: Content-Location: URI
Context: entity
When a document exists in several locations, Stronghold can include this header in the response to indicate the source of the copy it sends to the client.

Content-MD5

Syntax: Content-MD5: digest
Context: entity
The client can use this header to check the integrity of the message. Digest is an MD5 digest of the message body.

Content-Range

Syntax: Content-Range: bytes n-m/length
Context: entity
When the client requests a partial document using the Range header, Stronghold can respond with the Content-Range header to indicate which segment is enclosed in the message body. The values are a byte range and the total number of bytes in the segment.

Content-Transfer-Encoding

Syntax: Content-Transfer-Encoding: scheme
Context: entity
If Stronghold transforms the message body for transfer over the network, it uses this header to specify the encoding type, such as "7bit," "8bit," "binary," "base64," or "quoted-printable."

Content-Type

Syntax: Content-Type: type/subtype
Context: entity
Stronghold uses this header to specify the media type and subtype of the message body. Generally, the server returns media types that the client specifies with the Accept header.

ETag

Syntax: ETag: entity-tag
Context: entity
When a client send an If-Match or If-None-Match header, Stronghold responds using the ETag header, which specifies the entity tag for the requested document.

Expires

Syntax: Expires: date
Context: entity
Stronghold can use this header to indicate when the requested document expires. After the given date, a proxy server may refresh its cached copy of the document.

Last-Modified

Syntax: Last-Modified: date
Context: entity
The Last-Modified header indicates when the document was last modified.

Location

Syntax: Location: URI
Context: entity
When Stronghold responds with a status code such as 201 (Created), 301 (Moved Permanently), or 302 (Moved Temporarily), it includes the Location header to indicate the source of the requested document. URI must be absolute.

URI

Syntax: URI: <URI>
Context: entity
HTTP 1.1 deprecates this header in favor of Location, but it can still be used for backward compatability.