Configure Kaazing WebSocket Gateway

By default, the Gateway uses the values in the gateway-config.xml and gateway-config-minimal.xml files that are located in the GATEWAY_HOME/conf/ directory when you start the Gateway. Although you do not need to update the configuration file to run the Gateway on your local host, you must make some changes to provide services on non localhost machines. The standard way to set up and maintain your Gateway configuration is by editing the settings in the Gateway configuration file. You can modify one of the default files gateway-config.xml and gateway-config-minimal.xml, or create and edit your own copy.

Before You Begin

This procedure is part of Checklist: Configure Kaazing WebSocket Gateway:

To Configure the Gateway

  1. Before you configure the Gateway, ensure you have followed the steps in Setting Up Kaazing WebSocket Gateway to download and install Kaazing WebSocket Gateway.
  2. Configure the Gateway by editing any of the following configuration files:
    • Modify the settings in the configuration file GATEWAY_HOME/conf/gateway-config.xml file.

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

    • Create a customized Gateway configuration by adding specific elements to the configuration file GATEWAY_HOME/conf/gateway-config-minimal.xml file.

      The gateway-config-minimal.xml (recommended) contains the minimal set of properties necessary to run the Gateway.

    • Create and modify your own custom copy of a configuration file.
    • Note: 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, remove any unnecessary elements from the file, and rename the file to gateway-config-minimal.xml. To ensure that the gateway-config.xml file is not used in production, rename the file (for example: test-gateway-config.xml).
  3. At a minimum, the Gateway configuration file must contain the following components (which are included in the default configuration files):

    Here's an example of a simple Gateway configuration file that uses the default (supplied) ports to bind the /base (port 8000) to the Gateway host:

    <?xml version="1.0" encoding="UTF-8" ?>
    <gateway-config xmlns="http://xmlns.kaazing.com/2012/09/gateway">
    
    <service>
      <accept>http://build-macmini.kaazing.test:${gateway.base.port}/</accept>
    
      <type>directory</type>
      <properties>
        <directory>/base</directory>
        <welcome-file>index.html</welcome-file>
        <error-pages-directory>/error-pages</error-pages-directory>
        <options>indexes</options>
      </properties>
    </service> 
    
    </gateway-config>
  4. Customize your Gateway configuration, as necessary.

    The recommended practice for configuring the Gateway for production purposes is to edit the Gateway configuration file and configure only the properties necessary to customize the Gateway for your specific needs. Use the following guidelines to help you customize the Gateway configuration to meet your needs:

    • Use the gateway-config.xml file while developing and testing your configuration. This file can serve as a template for building your custom configuration file because it contains the services and configuration elements and provides detailed comments describing how and why to use them.
    • Assess what other services you might want to configure, or if you need to configure security, clustering and load balancing, internal network access, and so on.

      The gateway-config.xml configuration file is composed of several sections as described in the following table.

      Section Description
      Property defaults Specify default values for configuration elements. Configuring property defaults is optional but recommended because configuring the property defaults allows you to define some property values once and have the value propagated throughout the configuration when the Gateway starts. You can replace any value in the configuration file with a property using the dollar-sign and curly brace format (such as build-macmini.kaazing.test).
      Service Define how the Gateway manages communication for that service. The Gateway is configured by default to provide services only to users on the same machine (localhost) as that on which it is running. You can define one or more services to customize the Gateway for your environment, choosing the appropriate type of service (for example, balancer, broadcast, proxy service, and so on) to signal the Gateway to accept incoming connections from clients using any supported URL scheme.
      Service Defaults Configure default values that apply to all services. Note that any options you set at the service level overrides options you set at the service defaults level. You can configure SSL encryption, protocol bindings, WebSocket message size, keep-alive timeouts, mime-type messages, and more.
      Security Configure security for the service and specify authentication and authorization for users. To better understand how the security parameters that you specify in Kaazing WebSocket Gateway configuration work together, see What's Involved in Secure Communication.
      Management Use the management section to configure a management agent, such as Java's built-in Java Management and Monitoring Console (JConsole), to monitor, track and manage user sessions. For secure management, you can specify the protocol, network interface, and the port number on which the management agent accepts connections, and you can define the user roles that are authorized to perform management operations.
      Additional Services UDP broadcast service, proxy service, session service, multicast addressing, network address mappings, and more.
    • Consider configuring multiple services on the Gateway to use the same hostname and port, for example, as a way to organize multiple connection requests on the same server as the Gateway and avoid conflicts. See Configuring Multiple Services on the Same Host and Port for complete information.
  5. Test the Gateway configuration using the customized configuration file. For detailed instructions about starting and stopping the Gateway, see "How do I start and stop the Gateway?" in Setting Up Kaazing WebSocket Gateway.
  6. Prepare the configuration file for production.

    When you are ready to deploy the Gateway to your production environment, create a copy of your configuration file, remove any unnecessary elements from the file, and rename the file to gateway-config-minimal.xml. By default, if there is no gateway-config.xml file in the GATEWAY_HOME directory when the Gateway is started, then the Gateway is started using gateway-config-minimal.xml.

    To ensure that the gateway-config.xml file is not used in production, rename the file (for example, rename the file to test-gateway-config.xml).

Next Step

Configure Kaazing WebSocket Gateway Using the GATEWAY_OPTS Environment Variables is optional. It is an alternative method for configuration the Gateway.

Notes

  • For helpful tips about editing files on a cloud machine, see Setting Up Kaazing WebSocket Gateway on a Cloud Server.
  • The actual location of the GATEWAY_HOME directory depends on your operating system and the method (standalone or installer) used to install the Gateway. To learn more about GATEWAY_HOME, see:
  • If you want to start a Gateway (downloaded from kaazing.com) on a private Amazon EC2 instance, you can configure the optional cloud.host and cloud.instanceid parameters to quickly deploy the Gateway to the EC2 instance.

    Note: Amazon dynamically allocates a hostname and instance ID to the new instance. By default, the hostname is the public DNS name. If you have referenced the cloud.host and cloud.instanceid parameters in the Gateway configuration, then when the Gateway is started on the EC2 instance, the hostname and ID of the instance on which the Gateway is running are substituted for the cloud.host or cloud.instanceid parameters.

    • You can add the cloud.host and value parameters to the GATEWAY_HOME/conf/gateway-config.xml file. In the following example, the Gateway resolves the accept element (shown in line 4) to the public DNS name for the AWS instance:
       <service>
         <name>base-direcctory</name>
         <description>Directory service for base files</description>
         <accept>http://${cloud.host}:${gateway.base.port}</accept>
         
         <type>directory</type>
         .
         .
         .
       </service>

      You can override the default connection via the public DNS name by setting the value for cloud.host to your preferred hostname for the AWS instance. In the following example, lines 3 and 4 in the properties section start the Gateway on URL gateway.example.com, overriding the default Amazon-supplied hostname:

       <properties>
         <property>
           <name>cloud.host</name>
           <value>gateway.example.com</value>
         </property>
         <property>
           <name>gateway.base.port</name>
           <value>8000</value>
         </property>
         <property>
           <name>gateway.extras.port</name>
           <value>8001</value>
         </property>
       </properties>

      You must also set the protocol.bind element to enable AWS to resolve the hostname to the machine name. For example, in the Gateway configuration file, bind the URI in the accept-options element to the address of the network interface:

       <accept-options>
         <tcp.bind>gateway.example.net:8001</tcp.bind>
       </accept-options>

      See Integrate Kaazing WebSocket Gateway into an Internal Network for more information about setting network protocol bindings with the protocol.bind element.

      If you configured the cloud.host property but the Gateway fails to find the host when it starts, the following errors might result:

      GatewayConfigParameter INFO ${cloud.host} found in config, attempting resolution by searching cloud provider
      GatewayConfigParameter WARN ${cloud.host} detected in config but could not determine cloud enviroment and find valid replacement for it
      GatewayConfigParameter INFO Detected configuration parameter [${cloud.host}], replaced with [${cloud.host}], as a result of resolution strategy [UNRESOLVED_PARAMETER_DEFINITION]
      GatewayConfigParameter INFO ${cloud.host} found in config, attempting resolution by searching cloud provider
      GatewayConfigParser ERROR Validation errors in gateway configuration file
      GatewayConfigParser ERROR Could not determine non-null value for parameter definition ${cloud.host}

    • You can add the cloud.instanceid parameter to the GATEWAY_HOME/conf/jaas-config.xml file to configure the Command Center password. Line 3 in the following example shows the cloud.instanceid parameter in the GATEWAY_HOME/conf/jaas-config.xml file:
       <user>
         <name>joe</name>
         <password>${cloud.instanceId}</password>
         <role-name>AUTHORIZED</role-name>
       </user>

      When you start the Gateway on Amazon Marketplace, the cloud.instanceid parameter is automatically replaced with your default Amazon EC2 instance ID. However, because the instance ID is the Command Center password used to authorize monitoring the Gateway on a private Amazon EC2 instance, the best practice is to either replace ${cloud.instanceId} with your-own-super-secret-password, or use token-based security. See How to Configure Security with Kaazing WebSocket Gateway to securely configure Gateway access and monitoring.

    Refer to Using Kaazing WebSocket Gateway on Amazon Web Services (AWS) Marketplace for more information.

  • Optionally, you can override one or more Gateway configuration settings by specifying the GATEWAY_OPTS environment variable before you start the Gateway. This is described in Configure the Gateway Using the GATEWAY_OPTS Environment Variable.
  • See Troubleshoot Kaazing WebSocket Gateway Configuration and Startup for help resolving issues when you set up and configure the Gateway.

See Also

TOP