Manual Reference Pages  - XSCONF (5)


.xsconf - XS-httpd local configuration file


     Configuration Directives
     Module Configuration Directives
See Also


An .xsconf file allows the user to set special directives for handling certain files in a directory. Using simple file matching commands, the user can set the mime-type, interpreter, character set or other options that are specific to a certain file or file pattern.

The file consists of block which apply to a specific filename pattern. The pattern should be listed in square brackets and the options listed below will apply to all files that match the given pattern. See the EXAMPLE section below for an illustration. These patterns are standard fnmatch(3) patterns. The special case [*] will match all files in a directory.

The filename may be prefixed by a method name and a slash to indicate that the following block only applies when the specified method is used. For instance [POST/*.cgi] would only match post requests for .cgi files. Alternatively the filename may be prefixed by the literal ./’ to indicate that it matches only files in the current directory, rather than applying to all subdirectories as well, which is the default. Note that this is a special case and not part of the filename match: it is not possible to match filenames in subdirectories in this way.

    Configuration Directives

All directives can only be used once in a block, unless explicitly mentioned otherwise (e.g. Restrict).
  Set the Content-Type for this file. This overrides the global mimetypes(5) file. A type must be of the form major/minor, e.g. text/html’.
  Specify the character of the document. Common character sets include US-ASCII’, UTF-8’, ISO-8859-1’, KOI8-R’ and EUC-JP’.
  Specify the natural language(s) of intended audience for the specified document. Note that this might not be equivalent to all the languages used within the entity-body. For example en-GB, nl’.
  An execute command sets the program (full path name) that should be used as an interpreter (preprocessor) for the file. This overrides any settings in the global scripttypes configuration file. You can use this, for example to have all *.pl files interpreted by /usr/bin/perl. The special internal commands (such as internal:404’) may also be used here. See xsscripts(5) for more details.

If the command line contains whitespace characters or special shell (redirection) characters the command will be executed in the system Bourne shell /bin/sh after appending the requested filename to the command line. The command line may also contain the special string %f’ which will be replaced by the filename. If %f’ is present, then the filename won’t be appended at the end of the command line.

Execute commands can be disabled globally by setting the UseLocalScript to false’ in httpd.conf(5).

  The argument to a restrict command should be a list of one or more IP addresses, IP prefixes or IP subnets in CIDR notation. Multiple arguments should be separated by commas. Access to the matching files will only be granted if the IP of the visitor matches one of the restrict address blocks. All other visitors will be presented with a 403 Permission Denied’ error.
  Boolean setting; if set to true’ then all matching files will be retrieved using the unpriviliged account of the webserver (by default nobody/nogroup’) instead of under your own UID. This can be useful if you want a file permission of say 600 to mean: do not allow retrieval. The default is false’: all file are retrieved under your own UID.
  Specify a password file that should be used to decide who is granted access to the matching file. Users who cannot produce the required credentials will be presented with a 401 Access Denied’ error. See xsauth(5) for the layout of such a file.

Multiple filenames may be given and if any contains a matching username/password combination, access will be granted. Never combine basic and digest authentication files, as browsers will not be able to deal with this.

  Set an alternative index file to be displayed if the default index.html does not exist. This setting only makes sense in a general [*] block. Note that the index is still subject to options that match this filename in other block. For example one can set as the index and add a [*.py] block that sets Python as a local interpreter for all *.py files.
  Full pathname of the CGI program that should handle HTTP PUT requests for files in this directory. The requested resource (filename) is passed on through the PATH_TRANSLATED environment variable. See httpd_cgi(7) for dealing with CGI scripts. Note that PUT requests require special status codes. Only available when UsePut is enabled in the global server configuration.
  Full pathname of the CGI program that should handle HTTP DELETE requests for files in this directory. Works analogous to PutScript.
  Override the default timeout that is used to restrict the execution time of all CGI scripts (wall time in minutes). Other limits will still apply though, specifically the per process CPU limit.
  Set the URL that contains the full P3P specification which describes the privacy policy for the requested file. This URL should refer to a correctly formatted XML document. The default location for a site is /w3c/p3p.xml. Don’t set this option if you wish to use the default.
  In stead of, or in addition to a policy reference, it’s possible to specify the full P3P policy in a compact notation (consisting of a string of short abbreviations). If set, this policy will be added to the headers of the requested document.
  Set the content security policy for the selected resource. If set, this policy will be added to the headers of the requested document(s).

Extra authentication options are available when SSL and PCRE are compiled in and SSL client certificates are used. SSL client certificates must be enabled explicitly via the SSLAuthentication option in httpd.conf(5).
  The argument should be a regular expression that is matched against the distinguished name’ field of the subject mentioned on the SSL client certificate. The contents of this field is also available through the SSL_CLIENT_S_DN environment variable. Access is only granted if this information is available and matches the data in the certificate. Multiple SSLSubjectMatch directives are allowed, in which case access is granted if any of these match the certificate subject.
  A regular expression that is matched against the issuer information of the client certificate. Usage is similar to the SSLSubjectMatch directive.

    Module Configuration Directives

Optional modules can be enabled for the webserver. In this case, extra configuration directives for the specific modules are available as well. These settings will be silently ingored when the relevant webserver module is not loaded.


If LDAP support is enabled, then special directives can be used to enable password checks through a remote authentication server.
  Set the hostname or IP address of the LDAP authentication server.
  Set the LDAP authentication server name in URL format, starting with ldap:// or ldaps://. Setting LdapURI overrides the LdapHost setting - and vice versa.
  Set username attribute. The LDAP server will be queried for a matching $LdapAttr=$username’ entry. The default is uid.
  Set the base DN (directory name) for the LDAP query. Setting a DN is mandatory.
  Protocol version to use. The default is 3, but for older servers one may want to use 2 instead.
  List of groups of which the user should be a member. If the username is found in any of these groups, then access will be granted. If no groups are specified, then a matching username and password will be enough to be granted access.
  Using a custom filter is the most flexible way to select a user. This allows full LDAP filter expressions to be used. In this expression %u may be used (more than once) to match the user to be authenticated. A filter rule may be used in combination with LdapAttr and LdapGroups for convenience. But when %u is used in this expression, there is no need to set attr or groups.


An .xsconf file in a directory tree that can only be accesses by authenticated users from the local network, might look something like this,
MimeType        text/html
Charset         utf-8
Execute         /usr/local/bin/php-cgi
AuthFile        /wwwsys/xsauth


httpd(1), httpd.conf(5), xsauth(5), xsredir(5), xsscripts(5)

The project homepage:

February 10, 2007 XSCONF (5) xs-httpd/3.5