XSCONF(5) BSD File Formats Manual XSCONF(5)NAME
.xsconf — XS-httpd local configuration file
DESCRIPTION
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 EXAM‐
PLE 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 indi‐
cate 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 pos‐
sible to match filenames in subdirectories in this way.
Configuration Directives
All directives can only be used once in a block, unless explicitly men‐
tioned otherwise (e.g. Restrict).
MimeType
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’.
Charset
Specify the character of the document. Common character sets
include ‘US-ASCII’, ‘UTF-8’, ‘ISO-8859-1’, ‘KOI8-R’ and ‘EUC-JP’.
Language
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’.
Execute
An execute command sets the program (full path name) that should
be used as an interpreter (preprocessor) for the file. This over‐
rides 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).
Restrict
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.
NoPrivs
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.
AuthFile
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.
IndexFile
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 index.py as the index and add a [*.py] block that sets
Python as a local interpreter for all *.py files.
PutScript
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.
DeleteScript
Full pathname of the CGI program that should handle HTTP DELETE
requests for files in this directory. Works analogous to
PutScript.
ScriptTimeout
Override the default timeout that is used to restrict the execu‐
tion time of all CGI scripts (wall time in minutes). Other lim‐
its will still apply though, specifically the per process CPU
limit.
p3pPolicyReference
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.
p3pCompactPolicy
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.
ContentSecurityPolicy
Set the content security policy for the selected resource. If
set, this policy will be added to the headers of the requested
document(s).
PublicKeyPins
Set the HTTP public key pinning header for the selected resource.
The value will be used unchanged in the Public-Key-Pins header.
It should contain the hash values of the public keys that are
used for the website. It is recommended to always include an
additional key hash, for a key which is stored offline. Note
that this value is independent of a certificate: a certificate
may be renewed without changing the private key, in which case
the header does not need to be updated. A max-age value of
5184000 (60 days) is recommended for default use. See RFC 7469
for more details.
AccessControlAllowOrigin
Sets the value of the Access-Control-Allow-Origin HTTP header.
The value should either be a URI or the special value *, indicat‐
ing that all cross-origin requests are allowed.
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).
SSLSubjectMatch
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.
SSLIssuerMatch
A regular expression that is matched against the issuer informa‐
tion 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 mod‐
ule is not loaded.
mod_ldap
If LDAP support is enabled, then special directives can be used to enable
password checks through a remote authentication server.
LdapHost
Set the hostname or IP address of the LDAP authentication server.
LdapURI
Set the LDAP authentication server name in URL format, starting
with ldap:// or ldaps://. Setting LdapURI overrides the LdapHost
setting - and vice versa.
LdapAttr
Set username attribute. The LDAP server will be queried for a
matching ‘$LdapAttr=$username’ entry. The default is uid.
LdapDN Set the base DN (directory name) for the LDAP query. Setting a DN
is mandatory.
LdapVersion
Protocol version to use. The default is 3, but for older servers
one may want to use 2 instead.
LdapGroups
List of groups of which the user should be a member. If the user‐
name 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.
LdapFilter
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.
EXAMPLES
An .xsconf file in a directory tree that can only be accesses by authen‐
ticated users from the local network, might look something like this,
[*.shtml]
Restrict 131.155.140.0/23
MimeType text/html
Charset utf-8
Execute /usr/local/bin/php-cgi
AuthFile /wwwsys/xsauth
SEE ALSOhttpd(1), httpd.conf(5), xsauth(5), xsredir(5), xsscripts(5)
The project homepage: http://www.xs-httpd.org/
xs-httpd/3.5 February 10, 2007 xs-httpd/3.5
