Domains

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.

Example

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>

Ordering

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.

Syntax

The configuration is written in XML, therefore XML syntax rules apply. Comments, for example, are written as .

`domains` element

All 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` element

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, _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` element

Each 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` element

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 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` element

Each 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` elements

Each 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.

Examples

Example 1

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)

Example 2

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>
      &lt;Location "/">
        Require all denied
        Require local
      &lt;/Location>
    </httpd-conf>
  </domain>
</domains>

Example 3

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>

Example 4

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>

Example 5

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>

Manual configuration of 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>

Validation

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

Domains

Example

Ordering

Syntax

domains element

domain element

ports element

ssl element

alias element

httpd-conf, httpd-conf-http and httpd-conf-https elements

Examples

Example 1

Example 2

Example 3

Example 4

Example 5

Manual configuration of domains

Validation

`domains` element

`domain` element

`ports` element

`ssl` element

`alias` element

`httpd-conf`, `httpd-conf-http` and `httpd-conf-https` elements