About Gateway Configuration

After you install the Gateway, you can configure it by modifying the settings in the configuration file GATEWAY_HOME/conf/gateway-config.xml file. The actual location of the GATEWAY_HOME directory depends on your operating system and the method (standalone or installer) used to install the Gateway. You can find more information about GATEWAY_HOME and the directory structure that is set up during installation in Setting Up the Gateway. This document describes the types of configuration files and Configuration Element Index provides a list of the individual configuration elements.

By default, the Gateway uses the values in the Gateway configuration file when you start the Gateway. Optionally, you can override one or more Gateway configuration settings by specifying the GATEWAY_OPTS environment variable before you start the Gateway. This method is described in Configure Kaazing Gateway Using the GATEWAY_OPTS Environment Variable.

This topic covers the following information:

About Kaazing Gateway Configuration Files
About Kaazing Gateway Configuration File Elements and Properties
About Kaazing Gateway Namespace Declarations

About Kaazing Gateway Configuration Files

The Gateway provides the following configuration file:

gateway-config.xml contains a complete set of gateway properties, including the properties and services needed to run the Gateway.

Notes

By default, the Gateway configuration accepts connections on localhost, and the cross-origin sites allowed to access those services are also configured for localhost by default. The default configuration is convenient for quickly trying the Gateway out of the box, but the default configuration is not production ready nor is it secure. You should customize the Gateway configuration for your needs by modifying settings in the GATEWAY_HOME/conf/gateway-config.xml file. For example, you might customize the Gateway to accept connections on a non-localhost host name or IP address and add authorization constraints for services. After you modify the gateway-config.xml file, you must restart the Gateway for the changes to take effect.
Consider using the gateway-config.xml file during your development and testing phase. Then, when you are ready to deploy the Gateway to your production environment, create a copy, and remove any unnecessary elements from the file. To ensure that the full gateway-config.xml file is not used in production, rename the file (for example: test-gateway-config.xml).
For more information about setting up additional, and more advanced configurations, see the descriptions and examples of services for the Gateway configuration in the Service Reference.
For additional information about the location of your GATEWAY_HOME, the configuration files and starting the Gateway, see Setting Up the Gateway.

About Kaazing Gateway Configuration File Elements and Properties

Kaazing Gateway configuration file (gateway-config.xml or gateway-config.xml) can include a number of configuration elements and properties contained within the top-level gateway-config element.

At a minimum, the Gateway configuration file must contain the following components (which are included in the default configuration files):

The Gateway namespace declaration, as described in About Kaazing Gateway Namespace Declarations
The Gateway name element.
The service element with the directory type to specify the path of your static files relative to GATEWAY_HOME/web, where GATEWAY_HOME is the directory where you installed Kaazing Gateway.

For example, the following is an example of a minimally configured Gateway configuration file:

<?xml version="1.0" encoding="UTF-8" ?>

<gateway-config
    xmlns="http://xmlns.kaazing.org/2016/06/gateway">
    ...
    <properties>
        <property>
            <name>gateway.hostname</name>
            <value>localhost</value>
        </property>
        <property>
            <name>gateway.base.port</name>
            <value>8000</value>
        </property>
    </properties>
    ...
    <service>
        <name>Base Directory Service</name>
        <accept>http://${gateway.hostname}:${gateway.base.port}/</accept>

        <type>directory</type>
        <properties>
            <directory>/base</directory>
            <welcome-file>index.md</welcome-file>
            <error-pages-directory>/error-pages</error-pages-directory>
            <options>indexes</options>
        </properties>
    </service>
    ...
</gateway-config>

To customize your configuration, see the Configure Kaazing Gateway topic for a step-by-step procedure to configure the Gateway. Also, you can find a complete list of elements in the Configuration Element Index.

About Kaazing Gateway Namespace Declarations

Your Kaazing Gateway configuration file must contain a namespace declaration. Each release of the Gateway has a unique namespace declaration. The namespace is defined by the xmlns attribute in the gateway-config element and has the syntax: xmlns=**"URI"** as shown in the following examples.

Example: gateway-config.xml file

The namespace for gateway-config.xml is shown in line 1:

<gateway-config xmlns="http://xmlns.kaazing.org/2016/06/gateway">
  ...
</gateway-config>

Example: jaas-config.xml file

The namespace for jaas-config.xml is shown in line 1:

<jaas-config xmlns="http://xmlns.kaazing.com/jaas-config/centurion">
  ...
</jaas-config>

When the Gateway starts, it uses the namespace declaration (which corresponds to a particular XML schema definition) to determine how to parse the XML file. Thus, when you start the Gateway:

When you use the default gateway-config.xml configuration file, and the jaas-config.xml configuration file that are installed in GATEWAY_HOME/conf/, then you can start the Gateway without making any changes to the namespace declaration. This is because the default configuration files that are installed with the Gateway explicitly set the namespace declaration to the most current namespace.
If you create your own configuration files, then you must ensure that the files contain a namespace declaration that is appropriate for your Gateway release before you start the Gateway. See About Kaazing Gateway Namespace Declarations to ensure the elements used in your configuration file match what is supported by the namespace specified in the configuration file.

Notes:
Configuration files that contain a wrong or an out-of-date namespace declaration can result in one of the following scenarios when the Gateway starts:

If the Gateway configuration file contains an out-of-date namespace declaration, then the Gateway automatically upgrades the configuration in memory and writes the modified configuration file to disk and appends a ‘.new’ extension (for example, gateway-config.xml.new). The Gateway starts using the up-to-date set of in-memory configuration objects.

If you run the Gateway again with the same out-of-date namespace, then the translation of the configuration file occurs again (the modified configuration .new file is written again, and so on). You can avoid going through the translation process again if, once a .new file is created, you delete the current (old) configuration file and rename the .new configuration file (for example, rename gateway-config.xml.new to be gateway-config.xml) so that the Gateway uses the up-to-date configuration the next time it starts.
If the Gateway configuration file contains a completely wrong namespace declaration, then the Gateway returns an error and stops. For example: ERROR Error upgrading XML: Unknown/unsupported XML namespace URI 'http://xmlns.kaazing.com/2011/zzz/gateway'.
If the Gateway configuration file contains a very old namespace declaration, then the Gateway returns an error and stops. For example: ERROR Gateway config file 'gateway-config.xml' from prior release in use. The Gateway writes the configuration file to disk and appends a “.migrated” extension (for example, gateway-config.xml.migrated.