# WASD Hypertext Services - Technical Overview

## 9 - Service Configuration

> 9.1 - IPv4 and IPv6
> 9.2 - Service Directives
> 9.3 - Directive Detail
> 9.4 - Administration
> 9.5 - Examples

[next] [previous] [contents] [full-page]

> NOTE

> The service configuration file is optional. If the HTTPD$SERVICE logical is not defined or the file does not exist service configuration is made using the HTTPD$CONFIG [Service] directives. For simple sites, those containing one or two services, the use of a separate service configuration file is probably not warranted. Once the number begins to grow this file offers a specific management interface for those services.

Precedence of service specifications:

1. /SERVICE= command line qualifier

2. HTTPD$SERVICE configuration file (if logical defined and file exists)

3. HTTPD$CONFIG [Service] directive

There is no design limit to the number of services that WASD can support. It can listen on any number of IP ports and for any number of virtual services for any given port.

###
Specific Services

In common with other configuration files, directives associated with a specific virtual services are introduced using a double-bracket delimited host specification (6.3 - Virtual Services). When configuring a service the following three components specify its essential characteristics.

- scheme - HTTP scheme (sometimes refered to as protocol). If http: (or omitted) it is a standard HTTP service. If https: an SSL service is configured.

- host - Host name or dotted-decimal address. If omitted, or specified as an asterisk ("*"), defaults to the system's IP host name.

- port - IP port the service is offered on. If omitted it defaults to 80 for an http: service, and to 443 for an https: (SSL) service.

###
Generic Services

A generic service is one that specifies a scheme and/or port but no specific host name. This is useful in a cluster where multiple systems all provide a basic service (e.g. a port 80 service). If the host name is omitted or specified as an asterisk the service substitutes the system's IP host name. See 9.5 - Examples.

###
SSL Services

Multiple virtual SSL services (https:) sharing the same certificate can essentially be configured against any host name (unique IP address or alias) and/or port in the same way as standard services (http:). Services requiring unique certificates can only be configured for the same port number against individual and unique IP addresses (i.e. not against aliases). This is not a WASD restriction, it applies to all servers for significant SSL technical reasons (17 - Secure Sockets Layer).

For example, unique certificates for https://www.company1.com:443/ and https://www.company2.com:443/ can be configured only if COMPANY1 and COMPANY2 have unique IP addresses. If COMPANY2 is an alias for COMPANY1 they must share the same certificate. During startup service configuration the server checks for such conditions and issues a warning about "sharing" the service with the first configured.

###
Administration Services

When multiple instances are configured Server Administration page access, in common with all request processing, is automatically shared between those instances. There are occasions when consistent access to a single instance is desirable. The [ServiceAdmin] directive indicates that the service port number should be used as a base port and all instances create their own service with unique port for access to that instance alone. The first instance to create an administration service uses the specified port, or the next successive if it's already in use, the next instance will use the next available port number, and so on. A high port number should be specified. The Server Administration page lists these services for all server instances in the cluster. This port configuration is not intended for general request activity, although with appropriate mapping and other configuration there is nothing specifically precluding it's use (remembering that the actual port in use by any particular instance may vary across restarts). In all other respects the services can (and should) be mapped, authorized and otherwise configured as any other. See 9.5 - Examples.

###
9.1 - IPv4 and IPv6

Both IP version 4 and 6 are concurrently supported by WASD. All networking functionality, service creation, SSL, proxy HTTP, proxy FTP and RFC1413 authorization is IPv6 enabled. If system TCP/IP services do not support IPv6 the expected error would be

      %SYSTEM-F-PROTOCOL, network protocol error

during any attempted IPv6 service creation. Of course IPv4 service creation would continue as usual.

Server configuration handles the standard dotted-decimal addresses of IPv4, as well as "normal" and "compressed" forms of standard IPv6 literal addresses, and a (somewhat) standard variation of these that substitutes hyphens for the colons in these addresses to allow the colon-delimited port component of a "URL" to be resolved.

IPv6 Literal Addresses

Normal | Compressed
| 1070:0:0:0:0:800:200C:417B | 1070::800:200C:417B
| 0:0:0:0:0:0:13.1.68.3 | ::13.1.68.3 | 0:0:0:0:0:FFFF:129.144.52.38 | ::FFFF:129.144.52.38 | hyphen-variants | hyphen-variants | 1070-0-0-0-0-800-200C-417B | 1070--800-200C-417B | 0-0-0-0-0-0-13.1.68.3 | --13.1.68.3 | 0-0-0-0-0-FFFF-129.144.52.38 | --FFFF-129.144.52.38

In common with all virtual services, if a connection can be established with the system and service port the HTTPd can respond to that request. If a service needs to be bound to a specific IP address then that can be specified using the [ServiceBind] directive using any of the literal address formats described above.

###
9.2 - Service Directives

Where a service directive has an equivalent configuration directive (e.g. error report path) the service directive takes precedence. This allows specific virtual services to selectively override the generic configuration.

Service Directives

[[virtual-service]] | scheme://host:port
| [ServiceAdmin] | an instance Server Administration page service
| [ServiceBind] | if different to host's | [ServiceBodyTag] | <BODY> tag for server reports., etc | [ServiceClientSSLcipherList] | proxy SSL connect ciphers | [ServiceClientSSLverifyCA] | verify CA of proxied requests | [ServiceClientSSLverifyCAfile] | location of proxy CA file | [ServiceClientSSLversion] | proxy SSL version to use | [ServiceErrorReportPath] | path to script, SSI or "flat" error document | [ServiceNoLog] | suppress logging | [ServiceNoTrack] | suppress user tracking | [ServiceProxy] | proxy service | [ServiceProxyAuth] | require proxy authorization | [ServiceProxyCache] | proxy caching | [ServiceProxyChain] | chained proxy service host | [ServiceProxySSL] | proxy SSL enable | [ServiceProxyTrack] | user track proxy access | [ServiceProxySSL] | provide proxy of SSL (connect:) | [ServiceSSLcert] | SSL service certificate | [ServiceSSLcipherList] | list of accepted SSL ciphers | [ServiceSSLkey] | SSL service private key | [ServiceSSLverifyPeer] | access only using verified peer certificate | [ServiceSSLverifyPeerCAfile] | location of CA file | [ServiceSSLversion] | SSL version to use

###
9.3 - Directive Detail

Some of these directives control the behaviour of proxy services. Refer to 16 - Proxy Services for further detail. Other directive are Secure Sockets Layer (SSL) specific. This is an optional package described in 17 - Secure Sockets Layer.

1. [[virtual-service]] (default: none)

   Specifies the scheme, host name (or asterisk) and port of a service.

2. [ServiceAdmin] `ENABLED|DISABLED` (default: DISABLED)

   Marks the port as administration service (Administration Services).

3. [ServiceBind] literal address (default: none)

   If the system has a multi-homed network interface this binds the service to the specific IP address and not to INADDR_ANY. Generally this will not be necessary. The literal address may be in IPv4 dotted-decimal or IPv6 normal or compressed hexdecimal.

4. [ServiceBodyTag] string (default: <BODY>)

   Specifies the HTML <BODY> tag for server error and other report pages. This allows some measure of site "look-and-feel" in page colour, background, etc. to be maintained.

5. [ServiceClientSSL] `ENABLED|DISABLED` (default: DISABLED)

   Enables a proxy service to originate HTTP-over-SSL requests. This is different to the CONNECT service enabled using [ServiceProxySSL]. It allows requests to be gatewayed between standard HTTP and Secure Sockets Layer (see 16.5 - Gatewaying Using Proxy).

6. [ServiceClientSSLcipherList] string (default: none)

   A comma-separated list of SSL ciphers to be used by the gateway to connect to SSL services. The use of this parameter might allow the selection of stronger ciphers to be forced to be used or the connection not allowed to procede.

   > NOTE

   > These ServiceClientSSL.. directives are used to control behaviour when outgoing SSL connections are established (as with HTTP-to-SSL gatewaying). This should not be confused with verification of client certificates, which is better refered to as peer verification. See [ServiceSSLverifyPeer] and [ServiceSSLverifyPeerCAfile] directives.

7. [ServiceClientSSLverifyCA] `ENABLED|DISABLED` (default: DISABLED)

   Unless this directive is enabled the Certificate Authority (CA) used to issue the service's certificate is not verified. Requires that a CA file be provided. See note in [ServiceClientSSLcipherList] above.

8. [ServiceClientSSLverifyCAfile] string (default: none)

   Specifies the location of the collection of Certificate Authority (CA) certificates used to verify the connected-to server's certificate (VMS file specification). See note in [ServiceClientSSLcipherList] above.

9. [ServiceClientSSLversion] string (default: SSLV2/V3)

   The abbreviation for the SSL protocol version to be used to connect to the SSL service. See note in [ServiceClientSSLcipherList] above.

10. [ServiceErrorReportPath] string (default: none)

    Specifies the URL-format path to an optional, error reporting SSI document or script (6.9 - Error Reporting). This path can subsequently be remapped during request processing.

11. [ServiceNoLog] `ENABLED|DISABLED` (default: DISABLED)

    When request logging is enabled then by default all services are logged. This directive allows logging to be suppressed for this service.

12. [ServiceNoTrack] `ENABLED|DISABLED` (default: DISABLED)

    When use tracking is enabled then by default all requests on non-proxy services are tracked. This directive allows tracking to be suppressed for this service.

13. [ServiceProxy] `ENABLED|DISABLED` (default: DISABLED)

    Enables and disables proxy request processing for this service (16 - Proxy Services).

14. [ServiceProxyAuth] `none|AUTH|LOCAL` (default: none)

    Makes a proxy service require authorization before a client is allowed access via it (16.1.4 - Controlling Proxy Serving). `NONE` disables authorization. `PROXY` enables HTTP proxy authorization. `LOCAL` enables standard server authorization.

15. [ServiceProxyCache] `ENABLED|DISABLED` (default: DISABLED)

    Enables and disables proxy caching for a proxy service.

16. [ServiceProxyChain] string (default: none)

    Specifies the next proxy host if chained.

17. [ServiceProxyTrack] `ENABLED|DISABLED` (default: DISABLED)

    When user tracking is enabled only non-proxy services have it applied by default. This directive allows proxy service usage tracking to be enabled.

18. [ServiceProxySSL] `ENABLED|DISABLED` (default: DISABLED)

    Specifies the service as providing proxying of SSL requests. This is sometimes refered as a "CONNECT" service. This proxies "https:" requests directly and is different to the HTTP-to-SSL proying described in 16.3 - CONNECT Serving and enabled using [ServiceProxyHttpSSL].

19. [ServiceSSLcert] string (default: none)

    Specifies the location of the SSL certificates (VMS file specification) (17.3 - SSL Configuration).

20. [ServiceSSLcipherList] string (default: none)

    A comma-separated list of SSL ciphers allowed to be used by clients to connect to SSL services. The use of this parameter might allow the selection of stronger ciphers to be forced to be used or the connection not allowed to procede.

21. [ServiceSSLkey] string (default: none)

    Specifies the location of the SSL private key (VMS file specification).

22. [ServiceSSLverifyPeer] `ENABLED|DISABLED` (default: DISABLED)

    To access this service a client must provide a verified CA client certificate (17.3.7 - Authorization Using X.509 Certification).

23. [ServiceSSLverifyPeerCAfile] string (default: none)

    Specifies the location of the collection of Certificate Authority (CA) certificates used to verify a peer certificate (VMS file specification, 17.3.7 - Authorization Using X.509 Certification).

24. [ServiceSSLversion] string (default: SSLV2/V3)

    The abbreviation for the SSL protocol version allowed to be used to connect to an SSL service. Using the directive a service may select prefered (read stronger) protocols.

###
9.4 - Administration

A service configuration file can be maintained using a simple text editor and HTTPD$SERVICE.

Alternatively the Server Administration page may be used (18 - Server Administration). When using this interface for the first time ensure the HTTPD$SERVICE logical is correctly defined. If the file did not exist at server startup any services will have been created from the HTTPD$CONFIG [Service] directive. These will be displayed as the existing services and will be saved to the configuration file the first time it is saved.

The [IncludeFile] is a directive common to all WASD configuration, allowing a separate file to be included as a part of the current configuration (6.12 - Include File Directive).

Not all configuration directives may be shown depending on the type of service. For instance, unless a service is configured to provide proxy, only the [ServiceProxy] directive is displayed. To fully configure such a service enable it as proxy, save the file, then reload it. The additional directives will now be available.

There is always one empty service displayed each time the configuration menu is generated. This information may be changed appropriately and then saved to add new services to the configuration (of course, these will not be available until the server is restarted). To configure multiple new services add one at a time, saving each and reloading the file to provide a new blank service.

###
9.5 - Examples

1. The following example shows three services being configured. The first is standard HTTP on the default (and well-known) port 80. The second is a proxy service on port 8080. This service provides both standard HTTP (with response caching enabled), SSL (connect:) access and proxy authorization required. The third service is SSL, with a host-specific certificate and key.

         [[http://alpha.domain.name:80]]

         [[http://alpha.domain.name:8080]]
         [ServiceProxy]  enabled
         [ServiceProxyAuth]  PROXY
         [ServiceProxyCache]  enabled
         [ServiceProxySSL]  enabled

         [[https://alpha.domain.name:443]]
         [ServiceSSLcert] ht_root:[local]alpha.pem

2. This example shows a generic service service being configured on the well-known port 80.

         [[http://*:80]]

   If a cluster of four systems, ALPHA, BETA, GAMMA and DELTA all use this configuration each will have a service accessable via the following four URLs.

         http://alpha.domain.name/
         http://beta.domain.name/
         http://gamma.domain.name/
         http://delta.domain.name/

3. The following example show two services configured against specific IP addresses. The first is an IPv4 and the second a compressed IPv6.

         [[http://alpha4.domain.name:80]]
         [ServiceBind]  168.192.0.3

         [[https://alpha6.domain.name:80]]
         [ServiceBind]  fe80::200:f8ff:fe24:1a22

4. An administration port is a special configuration used to support the Server Administration page (18 - Server Administration) when multiple per-node instances are configured (6.2 - Server Instances). See description above.

         [[https://alpha.domain.name:44443]]
         [ServiceAdmin]  enabled
         [ServiceSSLcert] ht_root:[local]alpha.pem
         [ServiceSSLkey] ht_root:[local]alpha.pem

[next] [previous] [contents] [full-page]