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
or /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 domain
element.
The following example generates a virtual host that connects the hostname www.example.com
to the site mySite
in the project myProject
.
<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 en_US.UTF8
locale.
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 .conf
(e.g. 001-www.example.com.conf
).
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 <!-- … -->
.
domains
elementAll configuration files must have one domains
element at the top level.
A domains
element may contain zero or more domain
elements. It has no attributes.
domain
elementname="…"
(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, _path
to use the first path component of the URL as the project name, or _host
to use the hostname as the project name. If the value is _host
or _path
, and no matching project is found, FIT attempts to fall back to the project named _default
.site="…"
(required) defines the site to be used for this virtual host. Either a specific site name can be chosen, _path
to use the first (second, if project
is also set to _path
) path component of the URL as the site name, or _host
to use the hostname as the site name. If the value is _host
or _path
, and no matching site is found, FIT attempts to fall back to the site named _default
.Each domain
element requires the name
, project
and 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) ssl
, alias
etc.
ports
elementEach 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 listen-https
and 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-http
, listen-https
) are below 1024, the FIT_USER
will have to be set to root
in fit.ini
.
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 *
.
ssl
elementmode="…"
(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 xfp
(as offloaded
, but the load balancer additionally sets the X-Forwarded-Proto
request header to HTTPS
exactly 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 decrypt
).cert-file="…"
points to the certificate file for this domain (required if mode is decrypt
).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. alias
elementEach domain
element may contain any number of alias
elements. Each alias
element must have a name
attribute.
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.
httpd-conf
, httpd-conf-http
and httpd-conf-https
elementsEach domain
element may contain one each of the httpd-conf
, httpd-conf-http
and httpd-conf-https
elements.
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 <
and &
, respectively.
The httpd-conf
element has no attributes.
The httpd-conf-http
and 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 http://www.example.com/myExample
:
|- 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 (key-file
, cert-file
).
Since listen-http
and listen-https
in the ports
element are set to 80 and 443, the FIT_USER
will have to be root
in fit.ini
The provided 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 (listen-http
).
<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 ssl
).
<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 foo
. The 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.com
or 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 FitProject
and FitSite
to determine the project and site to be started, as well as FitHTTPSBase
and 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 de.example.com
and 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 1
, 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