The FIT engine requires a specific configuration for the Apache HTTPd virtual host to function correctly. To ensure a consistent and correct environment, virtual hosts should be configured using
/opt/sevenval/fit14/conf/domains.xml.d/*.xml. The configuration files for the Apache HTTPd are generated from those files using
fitadmin config generate. In order for FIT to be able to provide URLs with the desired protocol if the source switches from HTTP to HTTPS or vice versa, the domain on the FIT Server should be configured using a single
The following example generates a virtual host that connects the hostname
www.example.com to the site
mySite in the project
<domains> <domain name="www.example.com" project="myProject" site="mySite"> <ports public-http="80" listen-http="80"/> </domain> </domains>
The order in which virtual hosts are configured is important if wildcards are used for names or aliases or if no matching name or alias is found.
fitadmin config generate reads
conf/domains.xml first, then, in lexicographical order, all
.xml files in
conf/domains.xml.d/. The collation order (
LC_COLLATE) corresponds to the
fitadmin config generate checks the XML configuration files and, for each domain contained therein, it generates a corresponding virtual host configuration file in
/opt/sevenval/fit14/conf/vhosts/. To enforce the order in which the virtual hosts are included into the Apache configuration, the names of the output file names are numbered sequentially starting from
001, followed by
-, the domain name and the extension
fitadmin config generate automatically removes all files in the
conf/vhosts/ directory that follow this scheme, before generating new files. Other files in
conf/vhosts/ with names ending in
.conf are evaluated by the Apache HTTPd, but not managed by
fitadmin config generate.
The configuration is written in XML, therefore XML syntax rules apply. Comments, for example, are written as
<!-- … -->.
All configuration files must have one
domains element at the top level.
domains element may contain zero or more
domain elements. It has no attributes.
name="…"(required) defines the hostname of the virtual host. Wildcards may be used, if appropriate.
project="…"(required) defines the project to be used for this virtual host. Either a specific project name can be chosen,
_pathto use the first path component of the URL as the project name, or
_hostto use the hostname as the project name. If the value is
_path, and no matching project is found, FIT attempts to fall back to the project named
site="…"(required) defines the site to be used for this virtual host. Either a specific site name can be chosen,
_pathto use the first (second, if
projectis also set to
_path) path component of the URL as the site name, or
_hostto use the hostname as the site name. If the value is
_path, and no matching site is found, FIT attempts to fall back to the site named
domain element requires the
site attributes and must contain exactly one
ports element. Note that the order of the child elements is fixed, i.e.
port must be the first child of
domain, followed by (if required)
domain element must contain exactly one
ports element. For each protocol (HTTP or HTTPS) to be supported by the domain, a listen port and a public port must be set. At least one protocol must be provided.
public-http="…"defines the port used by clients for HTTP URLs.
public-https="…"defines the port used by clients for HTTPS URLs.
listen-http="…"defines the port the Apache HTTPd accepts HTTP traffic on.
listen-https="…"defines the port the Apache HTTPd accepts HTTPS traffic on.
If and only if a
public-https port are defined for a domain, a
ssl element must be provided to configure the mode, and, if required, keys, certificates and chain files for SSL operation.
If the listen ports (
listen-https) are below 1024, the
FIT_USER will have to be set to
Note that the listen ports are set in the
domains.xml, while the IP address is configured in the
fit.ini configuration file with
FIT_VHOST_DEFAULT_IP, which defaults to
mode="…"(required) sets the method used to establish HTTPS connections with clients. Possible values are
decrypt(the FIT Server terminates SSL connections),
offloaded(a load balancer decrypts SSL traffic and passes it unencrypted on a separate HTTP port to the FIT Server) or
offloaded, but the load balancer additionally sets the
X-Forwarded-Protorequest header to
HTTPSexactly if the client’s incoming request used HTTPS. Identical ports may be used for HTTP and HTTPS).
key-file="…"points to the key file belonging to the certificate for this domain (required if mode is
cert-file="…"points to the certificate file for this domain (required if mode is
chain-file="…"Obsolete. Points to a file providing the entire chain of intermediate certificates for the certificate (optional if mode is
decrypt). Please include the intermediate CA certificates in the server certificate file instead.
domain element may contain any number of
alias elements. Each
alias element must have a
name="…"defines an alternative name for the domain.
While FIT accepts requests from clients that use the alias, it will never generate absolute URLs using that alias. For example, a client switching from HTTP to HTTPS and back will always be directed to the hostname given in the
domain and may lose access to cookies in the process.
domain element may contain one each of the
httpd-conf element can be used to set configuration options for the Apache HTTPd for a specific domain. The syntax and the permitted statements are documented in the Apache HTTP Server Version 2.4 Documentation. Note that less than (
<) and ampersand (
&) characters must be escaped as
httpd-conf element has no attributes.
httpd-conf-https elements are equivalent to the
httpd-conf element, except that they only apply to the protocol specified.
The following example generates the default virtual host as provided by a fresh installation of FIT. Note that, while the name is
localhost, the domain is actually reachable on all IP addresses of the system by default, because
FIT_VHOST_DEFAULT_IP defaults to
<domains> <domain name="localhost" project="_path" site="_path"> <ports public-http="8080" listen-http="8080"/> </domain> </domains>
This configuration is useful for development systems, since it can be used to access any project and site available on the FIT Server. FIT first attempts to use the first path component as a project name (
project="_path"), and the second path component as a site name (
site="_path"). If no matching site is found, but the project exists, the site named
_default in the project identified by the first path component is used. If no such site exists, FIT attempts to use a site in the project named
_default, with the name taken from the first path component. If such a site can not be found, the site named
_default in the project
_default is used, if it exists. Finally, if no site has been found, an error message is displayed.
The following graph illustrates the file system locations and the matching order for a
_path/_path domain for the URL
|- projects | |- myExample | | |- sites | | | |- _default (1. match) | |- _default | | |- sites | | | |- myExample (2. match, if 1. match does not exists) | | | |- _default (3. match, if 1. and 2. matches do not exist)
A virtual host that is fixed to a specific site (
shop) in a specific project (
example). FIT will handle SSL decryption itself (
mode="decrypt" on the
ssl). You can use the script
createCertificate.sh to create the required SSL files (
httpd-conf element permits access only from
localhost. Note the escaped
< character (
<domains> <domain name="shop.example.com" project="example" site="shop"> <ports public-http="80" listen-http="80" public-https="443" listen-https="443" /> <ssl mode="decrypt" key-file="conf/ssl/shop.example.com.key" cert-file="conf/ssl/shop.example.com.crt"/> <httpd-conf> <Location "/"> Require all denied Require local </Location> </httpd-conf> </domain> </domains>
A virtual host that uses the project
example, while the site name is taken from the first path component (
site="_path"). If no matching site is found,
_default is used if it exists. Otherwise an error message is displayed. SSL traffic is decrypted by a load balancer (
mode="offloaded" on the
ssl) and forwarded as HTTP to port 1443 (
listen-https) on the FIT Server; HTTP traffic is forwarded to port 1080 (
<domains> <domain name="m.example.com" project="example" site="_path"> <ports public-http="80" listen-http="1080" public-https="443" listen-https="1443" /> <ssl mode="offloaded"/> </domain> </domains>
This example constructs a virtual host that takes the site name from the hostname (
site="_host"), the project is fixed to
foo. SSL is decrypted by a load balancer and, just like HTTP traffic, is forwarded to port 1080 on the FIT Server. The
X-Forwarded-Proto header indicates whether the client originally sent the request via HTTP or HTTPS (
mode="xfp" on the
<domains> <domain name="foo.example.com" project="foo" site="_host"> <ports public-http="80" listen-http="1080" public-https="443" listen-https="1080" /> <ssl mode="xfp"/> <alias name="*.example.com"/> <alias name="*.*.example.net"/> </domain> </domains>
A virtual host named
foo.example.com that uses a fixed site and project name of
ports element offers no support for HTTPS communication with the client. The incoming requests are forwarded from port 80 (
public-http) to port 1080 (
listen-http) on the FIT Server. An additional domain
bar.example.com is configured that immediately redirects all incoming requests on arbitrary hosts in the
example.net domain to the first virtual host.
<domains> <domain name="foo.example.com" project="foo" site="foo"> <ports public-http="80" listen-http="1080" /> </domain> <domain name="bar.example.com" project="foo" site="foo"> <ports public-http="80" listen-http="1080" /> <alias name="*.example.com"/> <alias name="*.*.example.net"/> <httpd-conf> #Redirect permanent / http://foo.example.com/ RedirectMatch .* http://foo.example.com/ </httpd-conf> </domain> </domains>
FIT uses the Apache environment variables
FitSite to determine the project and site to be started, as well as
FitHTTPBase to determine which part of the URL is local and which applies to the source, as well as how to switch between HTTP and HTTPS. Under specific circumstances, e.g. if you want multiple HTTP domains to share one HTTPS domain, or if you want FIT to use URLs with specific or longer paths, you may need to set those variables manually. You should use
SetEnvIf (with a tautological condition, if necessary) or
RewriteRule to set the variables to make sure that your values are available to the rewrite rules used by FIT.
The following example shows how the domains
en.example.com, both with a separate, fixed site, share the use of
ssl.example.com for HTTPS.
<domains> <domain name="de.example.com" project="example" site="de"> <ports public-http="80" listen-http="1080" /> <httpd-conf> SetEnvIf Request_URI ^ FitHTTPSBase=https://ssl.example.com/de </httpd-conf> </domain> <domain name="en.example.com" project="example" site="en"> <ports public-http="80" listen-http="1080" /> <httpd-conf> SetEnvIf Request_URI ^ FitHTTPSBase=https://ssl.example.com/en </httpd-conf> </domain> <domain name="ssl.example.com" project="example" site="_path"> <ports public-https="443" listen-https="1443" /> <ssl mode="decrypt" key-file="conf/ssl/ssl.example.com.key" cert-file="conf/ssl/ssl.example.com.crt"/> <httpd-conf> SetEnvIf Request_URI ^/de FitHTTPBase=http://de.example.com/ SetEnvIf Request_URI ^/en FitHTTPBase=http://en.example.com/ </httpd-conf> </domain> </domains>
You may validate your current domain configuration with
fitadmin validate domain. This will provide a list of the files that have been validated, as well as any errors that have been detected, including their location. If any errors are encountered, the exit status will be
0 otherwise. Example:
# fitadmin validate domain --verbose Validating /opt/sevenval/fit14/conf/domains.xml... OK.
After you’ve modified your domain configuration you might want to check your changes before generating new virtual hosts:
# fitadmin validate domain && fitadmin config generate
You can also validate arbitrary domain configuration files simply by appending the filenames like so:
# fitadmin validate domain /tmp/mydomains.xml /tmp/moredomains.xml