Administrator's Guide

This document contains the following sections:

Introduction

This document describes administration tasks for Kaazing Websocket Gateway - HTML5 Edition. Before you get started with administration tasks, ensure you have followed the steps in Getting Started to download and install the Gateway.

Conventions Used in this Guide

Use of "example.com"

The examples in Kaazing's documentation frequently reference the domain example.com. This domain is only an example, and is not to be used in a real-life scenario. This domain name (in addition to example.org and example.net) are reserved by the W3C for examples in documentation and testing. When you see such domain names in Kaazing's documentation, you must update the domain to a valid domain according to the relevant documentation. For more information about the reservation of this domain name, see the W3C document "Reserved Top Level DNS Names."


Typeface

monospace (or fixed width): Monospace or fixed-width type represent code in examples, URLs, or text that you enter.

bold: Bold type represents user interface elements.

Configuring Kaazing WebSocket Gateway

After you have installed Kaazing WebSocket Gateway as described in Getting Started, you can configure the gateway by modifying the settings in the configuration file GATEWAY_HOME/conf/gateway-config.xml. The individual configuration elements are explained in the following section.

Description of the gateway-config.xml Configuration Elements

The configuration file gateway-config.xml defines the following configuration elements contained in the top-level gateway-config element:

gateway-config

Required? Required; Occurs: exactly one

This is the root-level element for gateway configuration. gateway-config contains the following elements:

Element Description
management The element for gateway management configuration (see management)
session The element for associating a session with one or more services (see session)
security

The element for configuring gateway security (see security)

service The element for configuring a gateway service (see service)
service-defaults The element for configuring default options gateway service (see service-defaults)
network The element for configuring a gateway network address mapping (see network)
cluster The element for configuring gateway clustering (see cluster)

The following is an example gateway-config element:

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

<gateway-config
    xmlns="http://xmlns.kaazing.com/gateway-config/excalibur">
    .
    .
    .
</gateway-config>

Note: Kaazing WebSocket Gateway configuration files must use the namespace
http://xmlns.kaazing.com/gateway-config/excalibur
.

management

Required? Optional; Occurs: zero or one

This is the element for gateway management configuration. management contains the following elements:

Element Description
accept The protocol, network interface (possibly internal), and the port number on which the management agent accepts connections
realm-name The name of the security realm used for authentication
auth-constraint

The user roles that are authorized to perform management operations (see auth-constraint)

auth-constraint

Required? Optional; Occurs: zero or more

This is the element for configuring the user roles that are authorized to perform management operations. auth-constraint contains the following element:

Element Description
require-role The name of the user role to be included in the auth-constraint

The following is an example management element:

<management>
    <!-- specify protocol, network interface (possibly internal) and port -->
    <accept>jmx://localhost:2020/</accept>

    <!-- secure the management using a security realm -->
    <realm-name>demo</realm-name>

    <auth-constraint>
        <require-role>ADMINISTRATOR</require-role>
    </auth-constraint>
</management>

session

Required? Optional; Occurs: zero or more

This is the element that associates a session with one or more services by matching the domain of each service's accept URL. session contains the following elements:

Element Description
service-domain

The domain associated with a service accept URL

Note:

  • To specify a session that spans across multiple hosts, use a wild card and a domain. For example, *.test.local
  • To specify a session that spans across multiple ports on one domain, use the hostname. For example, localhost
authentication-scheme

The method used for authentication: Basic, Application Basic, Negotiate, or Application Negotiate:

  • Use Basic or Negotiate to allow the browser to respond to authentication challenges.
  • Use Application Basic or Application Negotiate to allow the client to respond to authentication challenges. The client in this case is the Kaazing client that is built based on the Kaazing client libraries. To use client-level authentication, the client must be configured to handle the authentication information, as described in the How-Tos.

Note: Use Negotiate or Application Negotiate if using Kerberos Network Authentication. For more information, see Configuring Kerberos Network Authentication.

authentication-connect

The URI for the authentication service. Only use this element if you use Kerberos Network Authentication and are using the Application Negotiate authentication-scheme. The URI must point to the kerberos5.proxy service.

For more information, see Configuring Kerberos Network Authentication.

realm-name The name of the security realm used for authentication
encryption-key-alias The alias for the session cookie encryption key that protects the value of the session token used by the gateway server to identify authenticated users
inactivity-timeout The length of time (in seconds) that the session cookie is active

The following is an example session element:

<session>
    <!-- associate service realms automatically -->
    <service-domain>localhost</service-domain>

    <!-- HTTP authentication configuration -->
    <authentication-scheme>Basic</authentication-scheme>
    <realm-name>demo</realm-name>

    <!-- Session cookie configuration -->
    <encryption-key-alias>session</encryption-key-alias>
    <inactivity-timeout>1800</inactivity-timeout>
</session>

security

Required? Optional; Occurs: zero or one

This is the element for configuring gateway security. security contains the following elements:

Element Description
keystore

The keystore contains the encryption keys for secure communications with Kaazing WebSocket Gateway (see keystore)

truststore

The truststore contains digital certificates for certificate authorities trusted by Kaazing WebSocket Gateway (see truststore)

realm

The realm associates an authenticated user with a set of authorized roles (see realm)

keystore

Required? Optional; Occurs: zero or one

This is the element for configuring the keystore that contains encryption keys for secure communications with Kaazing WebSocket Gateway. keystore contains the following elements:

Element Description
type

The format of the keystore file

file The location of the keystore file (absolute path or path relative to the gateway-config.xml file)
password-file The name of the file that contains the password to unlock the keystore file

truststore

Required? Optional; Occurs: zero or one

This is the element for configuring the truststore that contains digital certificates for certificate authorities trusted by Kaazing WebSocket Gateway. truststore contains the following elements:

Element Description
type

The format of the keystore file

file The location of the truststore file (absolute path or path relative to the gateway-config.xml file)

realm

Required? Optional; Occurs: zero or more

This is the element that associates an authenticated user with a set of authorized roles. realm contains the following elements:

Element Description
name

The name of the realm

description The description of the realm
login-module The login module communicates with a user database to validate user's credentials and to determine a set of authorized roles (see login-module)
login-module

Required? Required; Occurs: one or more

This is the element that configures the login module, which communicates with a user database to validate user's credentials and to determine a set of authorized roles. login-module contains the following elements:

Element Description
type

The type of login module: file, ldap, kerberos5, gss, or custom.

Note: You must use the kerberos5 and gss elements together. For information on using the kerberos5 and gss login-module elements, refer to Configuring Kerberos Network Authentication.

success

The behavior of the login module at the time it validates the user's credentials. Possible values are:

  • required
  • requisite
  • sufficient
  • optional

The success status options are defined in the javax.security.auth.login.Configuration class. Authentication succeeds if all required and requisite login modules succeed, or if a sufficient or optional login module succeeds.

options

The configuration options specific to the type of login module (see the following examples):

The following is an example of a file-based login-module element:

<login-module>
  <type>file</type>
  <success>required</success>
  <options>
    <file>jaas-config.xml</file>
  </options>
</login-module>

The following is an example of an LDAP-based login-module element:

<login-module>
  <type>ldap</type>
  <success>required</success>
  <options>
    <userProvider>ldap://ldap-svr/ou=people,dc=example,dc=com</userProvider>
    <userFilter>(&amp;(uid={USERNAME})(objectClass=inetOrgPerson))</userFilter>
    <authzIdentity>{EMPLOYEENUMBER}</authzIdentity>
  </options>
</login-module>

The following is an example of a kerberos5-based login-module element (see the Kerberos5 documentation for a description of the options you can use), which is required when using the Negotiate or Application Negotiate authentication schemes:

  <login-module>
    <type>kerberos5</type>
    <success>required</success>
    <options>
      <useKeyTab>true</useKeyTab>
      <keyTab>/etc/krb5.keytab</keyTab>
      <principal>HTTP/localhost@LOCAL.NETWORK</principal>
      <isInitiator>false</isInitiator>
      <doNotPrompt>true</doNotPrompt>
      <storeKey>true</storeKey>
    </options>
  </login-module>

The following is an example of a gss-based login-module element, which must follow the kerberos5 login-module element, as it authenticates the clients using the credentials obtained by the kerberos5 login module. The gss-based login-module element is required when using the Negotiate or Application Negotiate authentication schemes and the kerberos5-based login-module element.

<login-module>
    <type>gss</type>
    <success>required</success>
</login-module>

Kaazing WebSocket Gateway also supports a plugin mechanism for integration with custom authentication modules based on the Java LoginModule API. For information about creating a custom login module using this API, refer to the Java Authentication and Authorization Service (JAAS) LoginModule Developer's Guide. The following is an example of how you can use your existing custom login module with the Gateway.

  1. Before you begin, you will need the Gateway, your Java custom login module (for demo purposes, you can use the sample custom login module called GATEWAY_HOME/web/samples/login-module/CustomLoginModule.java), and the fully qualified class name of your custom login module.
  2. Compile your Java custom login module file into a JAR file and place it in GATEWAY_HOME/lib. You can also update the CLASSPATH to point to the desired directory containing the JAR file. 
  3. In the gateway-config.xml file, add the custom login-module and set the type to point to class:<the fully qualified class name>. For example, if you are using the sample custom login module provided with the Gateway, the fully qualified class name is com.kaazing.gateway.auth.demo.CustomLoginModule. The following is the login-module entry for this sample, as shown in line 2:
        <login-module>
          <type>class:com.kaazing.gateway.auth.demo.CustomLoginModule</type>
          <success>required</success>
        </login-module>
  4. Next, enable configuration for the services that are required to use this custom login module to authenticate with the back-end server. You can do this using the auth-constraint element. The following is an example of the echo service configured to use this custom login module, as shown in lines 6-8:

        <service>
          <accept>ws://localhost:8001/echo</accept>
          <accept>wss://localhost:9001/echo</accept>
          <type>echo</type>
    
          <auth-constraint>
            <require-role>AUTHORIZED</require-role>
          </auth-constraint>
    
          <cross-site-constraint>
            <allow-origin>http://localhost:8000</allow-origin>
          </cross-site-constraint>
    
          <cross-site-constraint>
            <allow-origin>https://localhost:9000</allow-origin>
          </cross-site-constraint>
        </service>
  5. Save the gateway-config.xml and restart the Gateway.


The following is an example of a complete security element:

<security>
  <keystore>
   <type>JCEKS</type>
   <file>keystore.db</file>
    <password-file>keystore.pw</password-file>
  </keystore>

  <truststore>
    <file>truststore.db</file>
  </truststore>

  <realm>
    <name>demo</name>
    <description>Kaazing WebSocket Gateway Demo</description>
    <login-module>
      <type>file</type>
      <success>required</success>
      <options>
        <file>jaas-config.xml</file>
      </options>
    </login-module>
  </realm>
</security>

service

Required? Optional; Occurs: zero or more

This is the element for configuring a service running on Kaazing WebSocket Gateway. Each service contains the following elements in the following order:

Element Description
accept

The URLs on which the service accepts connections

connect

The URL of a back-end service to which the proxy or broadcast service connects. You can specify a protocol scheme to activate protocol awareness in Kaazing WebSocket Gateway, or use tcp:// to make a basic TCP connection.

balance The URL of a balancer service that balances load for the cluster that the Gateway is part of. See balancer service for details.
type

The type of service. One of the following:

properties The service type-specific properties
accept-options Options for the accept element (see accept-options)
auth-constraint

The user roles that are authorized to access the service (see auth-constraint)

mime-mapping Mappings of file extensions to MIME types. Each mime-mapping entry defines the HTTP Content-Type header value to be returned when a client or browser requests a file that ends with the specified extension (see mime-mapping)
cross-site-constraint The cross-origin sites (and their methods and custom headers) allowed to access the service. (see cross-site-constraint)

balancer

This type of service is used to balance load for requests from any other gateway service type. When you configure a gateway as a load balancer you specify accept elements that identify the URLs on which the balancer service listens for client requests. Normally, the balancer service is used to balance load for a cluster of gateways and, therefore, you must configure the gateway as a client of a cluster. As with all services, the balancer service needs to have appropriate cross-site constraints defined.

The following is an example of a service element of type balancer. It shows how the service is configured as a client of a gateway cluster. The balancer service accesses the cluster in client mode to retrieve information about the URLs on which cluster member services are accepting connections so it can route the requests to the right cluster members.

<service>
  <accept>ws://balancer.example.com:8081/echo</accept>
  <accept>wss://balancer.example.com:9091/echo</accept>

  <type>balancer</type>

  <cross-site-constraint>
    <allow-origin>http://directory.example.com:8080</allow-origin>
  </cross-site-constraint>
  <cross-site-constraint>
    <allow-origin>https://directory.example.com:9090</allow-origin>
  </cross-site-constraint>
</service>
.
.
.
<cluster>
  <name>kzha</name>
  <connect>tcp://127.0.0.1:5942</connect>
  <connect>tcp://127.0.0.1:5943</connect>
  <mode>client</mode>
</cluster>

broadcast

This type of service is used to broadcast information from a back-end service. The broadcast service has the following property:

  • accept: the URL of the broadcast service to which a back-end service connects

The following is an example of a service element of type broadcast:

<service>
    <accept>sse://localhost:8000/sse</accept>
    <accept>sse+ssl://localhost:9000/sse</accept>
    <type>broadcast</type>

    <properties>
      <accept>udp://localhost:50505</accept>
    </properties>

    <cross-site-constraint>
      <allow-origin>http://localhost:8000</allow-origin>
    </cross-site-constraint>
    <cross-site-constraint>
      <allow-origin>https://localhost:9000</allow-origin>
    </cross-site-constraint>
</service>

In addition, you can also configure the broadcast service with a connect element that contains the URL of the back-end service that the gateway connects to. The following is an example of a service element of type broadcast in which the broadcast service connects to a back-end news server news.example.com:50505. When the service receives information, it broadcasts it to all the SSE channels accepted from clients on www.example.com.

<service>
  <accept>sse://www.example.com:8000/sse</accept>
  <accept>sse+ssl://www.example.com:9000/sse</accept>
  <connect>tcp://news.example.com:50505/</connect>
  <type>broadcast</type>

  <cross-site-constraint>
    <allow-origin>http://www.example.com:8000</allow-origin>
  </cross-site-constraint>
  <cross-site-constraint>
    <allow-origin>https://www.example.com:9000</allow-origin>
  </cross-site-constraint>
</service>

directory

This type of service is used to expose directories or files hosted on the gateway. The directory service has the following properties:

  • directory: Required. The path to the directory to be exposed on the Gateway.
  • welcome-file: Optional. The path to the file to be exposed on the Gateway.
  • error-pages-directory: Optional. The path to the directory containing the 404.html file. By default, the Gateway includes a 404.html file in GATEWAY_HOME/error-pages. If you choose to use this optional property, you can test it by adding the property, saving the gateway-config.xml file, then running the Gateway. Once the Gateway is running, point your browser to a page that does not exist, such as http://localhost:8000/nonexistentpage.html.

Note: The specified path must be relative to the directory GATEWAY_HOME\web (where GATEWAY_HOME is the directory in which Kaazing WebSocket Gateway is installed). For example, C:\kaazing\kaazing-gateway\web. An absolute path cannot be specified.

The following is an example of a service element of type directory:

<service>
  <accept>http://localhost:8000/</accept>
  <accept>https://localhost:9000/</accept>

  <type>directory</type>
  <properties>
    <directory>/</directory>
    <welcome-file>index.html</welcome-file>
    <error-pages-directory>/error-pages</error-pages-directory>
  </properties>

  <!--
    <auth-constraint>
      <require-role>AUTHORIZED</require-role>
    </auth-constraint>
  -->

</service>

Kaazing WebSocket Gateway demo services in the demo bundle are configured to accept connections on localhost by default. The cross-origin sites allowed to access those services are also configured for localhost-only by default. If you want to connect to host names other than localhost you must update your server configuration, and use the fully qualified host name of the host machine.

The following example shows a service configuration section that is used to accept connections for a directory service at the URL http://www.example.com on port 80:

<service>
  <accept>http://www.example.com:80/</accept>

  <type>directory</type>
  <properties>
    <directory>/</directory>
    <welcome-file>index.html</welcome-file>
  </properties>
</service>

echo

This type of service receives a string of characters through a WebSocket connection and returns, or "echoes," the same characters to the sender. This service is primarily used for validating the basic gateway configuration. The default echo service is configured to run on a separate port to verify cross-origin access.

The echo service has the following property:

  • accept: the URL at which the echo service accepts connections

The following is an example of a service element of type echo:

<service>
  <accept>ws://localhost:8001/echo</accept>
  <accept>wss://localhost:9001/echo</accept>

  <type>echo</type>

    <!--
    <auth-constraint>
      <require-role>AUTHORIZED</require-role>
    </auth-constraint>
    -->

    <cross-site-constraint>
      <allow-origin>http://localhost:8000</allow-origin>
    </cross-site-constraint>
    <cross-site-constraint>
      <allow-origin>https://localhost:9000</allow-origin>
    </cross-site-constraint>
  </service>

kerberos5.proxy

Required when using the Application Negotiate authentication scheme. This type of proxy service is used to connect Kaazing WebSocket Gateway to the Kerberos Key Distribution Center. The following is an example of a service element of type kerberos5.proxy:

<service>
    <accept>ws://localhost:8000/kerberos5</accept>
    <connect>tcp://kdc.example.com:88</connect>

    <type>kerberos5.proxy</type>

    <cross-site-constraint>
      <allow-origin>*</allow-origin>
    </cross-site-constraint>
</service>
  

proxy

This type of service is used to proxy connections to a back-end service. The proxy service enables a client to make a WebSocket connection to a service or back-end server that cannot natively accept WebSocket connections. The proxy service converts the WebSocket protocol used by the client connection into a protocol that you specify (for example, TCP) to connect to the back-end server. Upon client connection, the Gateway establishes a full-duplex connection between itself and the client, and between itself and the back-end server. The result is a full-duplex connection between the client and the back-end server.

The proxy service has the following property:

  • maximum.pending.bytes: the size of data the service will buffer for one client connection before slowing incoming data. The value must be a positive integer with either no specifed unit or appended with k or m (the unit is case insensitive) to indicate kilobytes or megabytes. If no unit is specified, the default unit is bytes. If you do not specify this property, its default value is 64k.

    For example:
    • A value of 2048 sets the buffer to 2048 bytes
    • A value of 128k or 128K sets the buffer to 128 kilobytes
    • No instance of the maximum.pending.bytes property in the gateway-config.xml sets the buffer to 64 kilobytes

    The Gateway uses this buffer when the speed of the data incoming to the proxy service is faster than the speed of the data being consumed by the receiving end, which is either the client or the back-end server. The buffer stores the data up to the limit you specify in this property per client connection, then slows the incoming data, until either the client or the back-end server (whichever is consuming the data) has consumed more of the outgoing data flow. For example, suppose you set this property to 128k. If the back-end server sends 256k of data to a client and the client has only consumed 128k, the remaining 128k (the limit you set in the property) is buffered. During this time, the Gateway suspends reading the data from the back-end server; as the client consumes the buffered data, the Gateway resumes reading the data from the back-end server.

The following is an example of a service element of type proxy. Here, the proxy service accepts incoming connections from clients using WebSocket (ws) and WebSocket Secure (wss), and connects to a back-end service using TCP, with the buffer set to 128k:

<service>
  <accept>ws://localhost:8000/remoteService</accept>
  <accept>wss://localhost:9000/remoteService</accept>
  <connect>tcp://localhost:61613</connect>

  <type>proxy</type>
  <properties>
    <maximum.pending.bytes>128k</maximum.pending.bytes>
  </properties>

  <!--
    <auth-constraint>
      <require-role>AUTHORIZED</require-role>
    </auth-constraint>
  -->

  <cross-site-constraint>
    <allow-origin>http://localhost:8000</allow-origin>
  </cross-site-constraint>
  <cross-site-constraint>
    <allow-origin>https://localhost:9000</allow-origin>
  </cross-site-constraint>
</service>

Kaazing WebSocket Gateway demo services in the demo bundle are configured to accept connections on localhost by default. The cross-origin sites allowed to access those services are also configured for localhost-only by default. If you want to connect to host names other than localhost you must update your server configuration, and use the fully qualified host name of the host machine. The following example shows a service configuration section that is used to accept connections for a proxy service at the URL http://www.example.com on port 80 (you can omit the default ports 80 or 443).

<service>
  <accept>ws://www.example.com:80/service</accept>
  <connect>tcp://localhost:61613</connect>

  <type>proxy</type>
</service>

session

This type of service is used to prevent sessions from timing out.

Note: Communication with the session service should be always be configured to use HTTPS.

The session service does not have any additional properties. The following is an example of a service element of type session:

<service>
  <accept>https://localhost:9000/session</accept>

  <type>session</type>

  <auth-constraint>
     <require-role>AUTHORIZED</require-role>
  </auth-constraint>
</service>

accept-options

Required? Optional; Occurs: zero or one

This is the element for adding options to all accepts for the service (see also the accept element).

Note: You can set accept-options at the service or at the service-defaults level. Setting accept-options for a service only affects the specified service, and overrides any defaults. Setting accept-options for service-defaults affects all services that can use that accept option, and is overridden by any accept-options applied at the service level. See service-defaults for more information.

accept-options contains the following elements:

Element Description
ssl.encryption Signals Kaazing WebSocket Gateway to enable or disable encryption on incoming traffic
protocol.bind

Binds the URL(s) on which the service accepts connections (defined by the accept element). Set protocol to one of the following:

  • ws
  • wss
  • http
  • https
  • ssl
  • tcp
ws.maximum.message.size Configures the maximum incoming WebSocket message size allowed by the Gateway (see ws.maximum.message.size)
ssl.encryption

Required? Optional; Occurs: zero or one; Values: enabled, disabled

This element allows you to enable or disable SSL encryption on incoming traffic. By default (or if you do not specify this element), encryption is enabled.

For example, if you have set up Kaazing WebSocket Gateway behind an SSL offloader, where the front-end traffic is secure over HTTPS and the back-end traffic behind the SSL offloader to the Gateway is not secure, you can disable encryption so that the connection can occur. You can include the accept-options element, then disable encryption by setting the ssl.encryption element to disabled. When encryption is disabled, the Gateway returns the response as HTTPS. If you do not include these elements or set the ssl.encryption element to enabled, the Gateway treats incoming traffic on www.example.com:443 as secure and handles the SSL itself. See the Security Guide for more information on HTTPS.

The following example shows a service element containing the accept-options and ssl.encryption elements, which signal Kaazing WebSocket Gateway to listen on address www.example.com:443, with encryption disabled. Alternatively, the IP address can be used in the configuration parameters as shown in the following example (you can also specify an IP address and port for the external address). Typically when you disable encryption on the incoming traffic, as Kaazing WebSocket Gateway is behind a SSL offloader, you will also have a network mapping section mapping www.example.com:443 to internal address gateway.dmz.net:9000.

<service>
  <accept>wss://www.example.com:443/remoteService</accept>
  <connect>tcp://localhost:6163</connect>

  <type>proxy</type>

  <accept-options>
    <ssl.encryption>disabled</ssl.encryption>
  </accept-options>
</service>
protocol.bind

Required? Optional; Occurs: zero or more; Where protocol can be ws, wss, http, https, ssl, or tcp

This element allows you to bind URL(s) on which the service accepts connections. See the How to Configure Kaazing WebSocket Gateway on an Internal Network document for more information. The following example shows external addresses (that users will see) for the WebSocket (ws) and WebSocket Secure (wss) protocols on localhost:8000 and localhost:9000. Internally, however, these addresses are bound to ports 8001 and 9001 respectively.

<service>
  <accept>ws://localhost:8000/echo</accept>
  <accept>wss://localhost:9000/echo</accept>

  <accept-options>
    <ws.bind>8001</ws.bind>
    <wss.bind>9001</wss.bind>
  </accept-options>
</service>
ws.maximum.message.size

Required? Optional; Occurs: zero or one

This element configures the size of message the service will accept from one client WebSocket (WebSocket (ws) or WebSocket Secure (wss)) connection. The value must be a positive integer with either no specifed unit or appended with k or m (the unit is case insensitive) to indicate kilobytes or megabytes. If no unit is specified, the default unit is bytes. If you do not specify this property, its default value is 128k. For example:

  • A value of 2048 sets the buffer to 2048 bytes
  • A value of 128k or 128K sets the buffer to 128 kilobytes
  • No instance of the ws.maximum.message.size element in the gateway-config.xml sets the buffer to 128 kilobytes
  • If an incoming message from a client exceeds the value set by ws.maximum.message.size, the Gateway terminates the connection with the client. Setting this element can be useful in preventing denial of service attacks, since you can limit the size of the message (such as a particularly large message) incoming to the Gateway from a client. When the Gateway disconnects the client, a message displays in the Gateway log.

The following example shows a service element containing a maximum incoming message limit of 64k, as shown in line 8:

<service>
  <accept>ws://localhost:8000/echo</accept>
  <accept>wss://localhost:9000/echo</accept>
  <accept-options>
    <ssl.encryption>disabled</ssl.encryption>
    <ws.bind>8001</ws.bind>
    <wss.bind>9001</wss.bind>
    <ws.maximum.message.size>64k</ws.maximum.message.size>
  </accept-options>
</service>

auth-constraint

Required? Optional; Occurs: zero or more

This is the element for configuring the user roles that are authorized to access the service. auth-constraint contains the following element:

Element Description
require-role The name of the user role to be included in the auth-constraint or * to indicate any valid user

The following is an example of a proxy service element with an auth-constraint, as shown in lines 7-9:

<service>
   <accept>ws://localhost:8000/remoteService</accept>
   <connect>tcp://localhost:61613</connect>

   <type>proxy</type>

   <auth-constraint>
      <require-role>AUTHORIZED</require-role>
   </auth-constraint>
</service>

mime-mapping

Required? Optional; Occurs: zero or more

See the the main description for mime-mapping (service-defaults). You can override the default configuration or add a new MIME type mapping for a particular service by adding a mime-mapping element to the service entry. You can only add mime-mapping elements immediately before any cross-site constraints for a service.

The following example shows a directory service that includes two mime-mapping elements for files with the PNG and and HTML extensions. The Gateway sets the content or MIME type for files with the PNG extension as a PNG image and files with the HTML extension as an HTML text file:

<service>
  <accept>ws://localhost:8000</accept>
  <accept>wss://localhost:9000</accept>

   <type>directory</type>

  <accept-options>
    <ws.bind>8001</ws.bind>
    <wss.bind>9001</wss.bind>
  </accept-options>

  <mime-mapping>
    <extension>png</extension>
    <mime-type>image/png</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>html</extension>
    <mime-type>text/html</mime-type>
  </mime-mapping>

  <cross-site-constraint>
  <allow-origin>http://localhost:8000</allow-origin>
  </cross-site-constraint>
  <cross-site-constraint>
    <allow-origin>https://localhost:9000</allow-origin>
  </cross-site-constraint>
  </service>

If your client does not properly render a file type as expected, check to ensure that the MIME type is properly mapped, and that you do not have multiple entries for the same extension type within the same section. If two or more mime-mapping entries for the same extension are given in a single service or in service-defaults, the Gateway applies the last mime-mapping entry; that is, within a given service or service-defaults section, the Gateway applies the mime-mapping entry closest to the end of the service (or service-defaults) section.

cross-site-constraint

Required? Optional; Occurs: zero or more

This is the element for configuring how a cross-origin site is allowed to access a service. cross-site-constraint contains the following elements:

Element Description
allow-origin The protocol scheme, fully qualified host name, and port number of the cross-origin site that is allowed to access this service. Specify the value * if you want to allow access to all cross-site origin sites, including connections to gateway services from pages loaded from the file system rather than a web site. Specifying * may be for appropriate for services that restrict HTTP methods or custom headers, but not the origin of the request.
allow-methods A comma-separated list of methods that can be invoked by the cross-origin site. For example: <allow-methods>POST,DELETE</allow-methods>.
allow-headers A comma-separated list of custom header names that can be sent by the cross-origin site when it accesses the service. For example, <allow-headers>X-Custom</allow-headers>.

The following is an example of a proxy service element with a cross-site-constraint (as shown in lines 13-15), allowing access to the back-end service by the site http://localhost:8000 (note the different port number). Cross-site access to back-end services is denied by default and cross-site-constraints allow you to "white-list" cross-origin sites.

<service>
  <accept>ws://localhost:8001/remoteService</accept>
  <connect>tcp://localhost:61613</connect>

  <type>proxy</type>

  <auth-constraint>
    <require-role>AUTHORIZED</require-role>
  </auth-constraint>

  <cross-site-constraint>
    <allow-origin>http://localhost:8000</allow-origin>
  </cross-site-constraint>
</service>

service-defaults

Required? Optional; Occurs: zero or one

This is the element for configuring certain options across all services running on the Gateway. This element contains the following:

Element Description
accept-options Options for the accept element (see accept-options (service-defaults))
mime-mapping Mappings of file extensions to MIME types. Each mime-mapping entry defines the HTTP Content-Type header value to be returned when a client or browser requests a file that ends with the specified extension (see mime-mapping (service-defaults))

accept-options (service-defaults)

The service-defaults section can contain the following accept-options (in the order listed):

  • ssl.encryption: signals Kaazing WebSocket Gateway to enable or disable encryption on incoming traffic
  • protocol.bind: binds the URL(s) on which the service accepts connections (defined by the accept element)
  • ws.maximum.message.size: configures the maximum incoming WebSocket message size allowed by the Gateway

If you then specify values for the accept-options on a particular service, the service accept options supercede the default values with your specified values. If there are no explicit accept-options for a particular service, the service uses these default values.

The following example shows ssl.encryption disabled, ws.maximum.message.size set to 256k, and sample network protocol bindings, just above the default mime-mapping entries, as shown in lines 2-9:

<service-defaults>
  <accept-options>
    <ssl.encryption>disabled</ssl.encryption>
    <ws.bind>8050</ws.bind>
    <wss.bind>192.168.10.25:8055</wss.bind>
    <http.bind>192.168.10.25:8060</http.bind>
    <https.bind>192.168.10.25:8065</https.bind>
    <ws.maximum.message.size>256k</ws.maximum.message.size>
  </accept-options>

  <mime-mapping>
    <extension>html</extension>
    <mime-type>text/html</mime-type>
  </mime-mapping>
  .
  .
  .
  </service-defaults>

mime-mapping (service-defaults)

The service-defaults section contains default MIME type mappings that apply to all services on the Gateway. The mime-mapping element defines the way the Gateway maps a file extension to a MIME type. When the Gateway responds to a file request, such as from the directory service, the response includes a Content-Type header based on the filename extension of the requested file. The Content-Type header value is the specified MIME type for that extension. If the file extension is not mapped to a MIME type by a mime-mapping element, the Gateway does not include a Content-Type header in its response.

You can specify MIME types for file extensions either in the service-defaults section or in a service. Specifying MIME types for file extensions in a service overrides any existing corresponding mime-mapping entries in the service-defaults section. See service for more information.

If you specify two or more mime-mapping entries for the same extension in a single service or in service-defaults, the Gateway only applies the last mime-mapping entry for that extension. The following example shows two entries for the same file extension; in this case, when the Gateway receives a request for a file with an HTML extension, the Gateway will respond with a Content-Type header value of text/html (not image/png) as shown in lines 1-4 and 9-12:

  <mime-mapping>
    <extension>html</extension>
    <mime-type>image/png</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>js</extension>
    <mime-type>text/javascript</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>html</extension>
    <mime-type>text/html</mime-type>
  </mime-mapping>

The service-defaults section in the default Gateway configuration includes the following standard mappings. You can modify these entries, but keep in mind that all mime-mapping entries must come after any accept-options you add to this section.

Note: The Gateway has hard-coded internal MIME mappings that are equivalent to those provided in the service-defaults section of the gateway-config.xml, for backward compatibility with earlier releases of Kaazing WebSocket Gateway. You cannot remove these internal settings. You can, however, override them with new MIME-type values.

The default Gateway mime-mapping entries are:
<service-defaults>
  <mime-mapping>
    <extension>html</extension>
    <mime-type>text/html</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>js</extension>
    <mime-type>text/javascript</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>png</extension>
    <mime-type>image/png</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>gif</extension>
    <mime-type>image/gif</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>jpg</extension>
    <mime-type>image/jpeg</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>jpeg</extension>
    <mime-type>image/jpeg</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>css</extension>
    <mime-type>text/css</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>swf</extension>
    <mime-type>application/x-shockwave-flash</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>xap</extension>
    <mime-type>application/x-silverlight-app</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>htc</extension>
    <mime-type>text/x-component</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>jnlp</extension>
    <mime-type>application/x-java-jnlp-file</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>manifest</extension>
    <mime-type>text/cache-manifest</mime-type>
  </mime-mapping>
</service-defaults>

network

This element has been deprecated. Use the protocol.bind accept option instead. Refer to the How to Configure Kaazing WebSocket Gateway on an Internal Network document for more information.

Required? Optional; Occurs: zero or one

This is the element for network configuration. network contains the following elements:

Element Description
address-mapping Mapping configuration for externally visible addresses on a firewall or a load-balancing router to a local internal address on which Kaazing WebSocket Gateway is listening (see address-mapping)

Note: If you are using an existing configuration that includes the network and address-mapping elements, you can continue to use them. If you include protocol.bind elements that overlap with existing network address mappings, the protocol.bind values will override your existing configuration.

address-mapping

This element has been deprecated. Use the protocol.bind accept option instead. Refer to the How to Configure Kaazing WebSocket Gateway on an Internal Network document for more information.

Required? Optional; Occurs: zero or more

This is the element for configuring address mapping of externally visible addresses on a firewall or a load-balancing router to a local internal address on which Kaazing WebSocket Gateway is listening. address-mapping contains the following elements:

Element Description
internal-address The local address on which Kaazing WebSocket Gateway is listening
external-address The address of a firewall or a load-balancing router as observed by the devices on the external network, such as a Web browser

The following is an example network element:

<network>

    <address-mapping>
      <internal-address>gateway.dmz.net:8000</internal-address>
      <external-address>www.example.com:80</external-address>
    </address-mapping>

    <address-mapping>
      <internal-address>192.168.0.1:9000</internal-address>
      <external-address>www.example.com:443</external-address>
    </address-mapping>

</network>

cluster

Required? Optional; Occurs: zero or one

This is the element for cluster configuration. Kaazing WebSocket Gateway can be clustered to achieve high availability. You can configure a cluster by specifying the address on which the gateway instance is listening for other cluster members and the addresses used to discover other cluster members. If the cluster element is missing, the server cannot participate as a cluster member.

Note: Example cluster configuration files can be found in GATEWAY_HOME/conf/cluster. The files cluster-member-1-config.xml and cluster-member-2-config.xml are used to configure a two-member demo cluster that can be started by running the startup scripts located in the directory GATEWAY_HOME/bin/cluster (for example, cluster-member-1.start.bat and cluster-member-2.start.bat on Windows).

cluster contains the following elements:

Element Description
name The name of the cluster.The name can be used by a service to participate in a cluster.
accept The IP address and port number on which the gateway instance is listening for other cluster members. You have to specify at least one. Other members connect to this address in their cluster configuration. The accept value must contain a protocol scheme, IP address or fully qualified host name, and port number.
connect

The IP address and port number used to discover other cluster members. You have to specify at least one. The connect value must contain a protocol scheme, IP address or fully qualified host name, and port number.

A cluster member has to connect to only one other cluster member to join a cluster. Therefore, each member can be configured with a subset of cluster members, and the union of all members makes up the entire cluster. The connect information is used for cluster-discovery purposes and once a member has successfully joined a cluster, it will have the information for all the members of that cluster.

mode

The mode in which the Gateway connects to the cluster: peer or client. In peer mode, the Gateway instance becomes a cluster member and in client mode, the Gateway instance becomes a client of the cluster. The latter is used by balancer Gateways that are configured as load-balancing routers using the balancer service, as described in the section "Load Balancing Services" in the How to Configure Kaazing WebSocket Gateway for High Availability document.

The following is an example cluster element, illustrating a three-member cluster, with the current member 192.0.2.10 listening on port 5942. Refer to Overview of Gateway Clustering for more information about high availability and clustering.

<cluster>
  <name>example-cluster</name>
  <accept>tcp://192.0.2.10:5942</accept>

  <connect>tcp://192.0.2.15:5942</connect>
  <connect>tcp://192.0.2.20:5942</connect>

  <mode>peer</mode>
</cluster>

Troubleshooting

The following are some things that can go wrong during Kaazing Gateway installation:

Port Conflicts

One of the most common problems occurs when another web server or process is already using the default port 8000. This is the default HTTP port that Kaazing WebSocket Gateway attempts to bind to at startup. To change this, perform the following steps:

  1. Open the file GATEWAY_HOME/conf/gateway-config.xml and search for instances of 8000.
  2. Change them to a port number that is not in use, and greater than 1024, as ports less than or equal to 1024 require superuser access to bind to under UNIX.
  3. Restart the Gateway.
  4. Access the Gateway at http://localhost:<new-port-number>/ in your browser. For example: http://localhost:8884/.

Localhost Not Configured

It can happen that “localhost” is not found when you try to access Kaazing WebSocket Gateway. This can happen if your browser is configured to use a proxy server. If this is the case, make sure your proxy configuration bypasses the proxy to access localhost.

Number of Connections Reached or Exceeded

The terms of your Kaazing WebSocket Gateway license specify a maximum number of allowed concurrent client connections. For example, the developer's version of the Kaazing WebSocket Gateway demo bundle allows only a limited number of concurrent client connections.

If you see the following warning message in the file GATEWAY_HOME/log/error.log file:

WARN Maximum number of connections reached.

You have exceeded the soft limit of allowed connections. To give you time to to upgrade the terms of your license and to avoid closed connections, additional connections are still allowed. However, if you see the following error message:

ERROR Maximum number of connections exceeded. Closing connection.

You have exceeded the hard limit of allowed connections and all new incoming connections are closed until you have upgraded the terms of your license. To upgrade your license, contact sales@kaazing.com.

Too Many Open Files Warning

If you see the following warning message in the file GATEWAY_HOME/log/error.log file on Unix or Linux:

java.io.IOException: Too many open files

Your server must be configured to be able to open more files to handle the number of open client connections. By default, a Unix or Linux user may only be able to open a maximum of a few hundred or thousand files. A number of file handles are used for each client connection that is established with Kaazing WebSocket Gateway: typically one for the client connection (double that in case of WebSocket emulation) and one for the back-end service connection. To avoid running out of available file handles, you should increase the limit of files that the user can open to handle your expected load.

To check the open file limit on Unix or Linux, use the ulimit command as shown in the following example:

ulimit -n

To temporarily update the open file limit, use the ulimit command as shown in the following example:

ulimit -n <new_value>

To permanently apply the ulimit value, you may need to restart and reconfigure your server settings. Refer to the documentation for your operating system for more information.

Error Starting Kaazing WebSocket Gateway on the Microsoft Vista Operating System

If you are running Kaazing WebSocket Gateway on the Microsoft Vista operating system and you receive an error with the following message:

java.net.SocketException: Address family not supported by protocol family: bind

It could be that you have an IPv6 address specified for localhost in your hosts file. To start the server successfully, perform the following steps:

  1. Open your hosts file (typically C:\Windows\System32\drivers\etc\hosts).
  2. Replace:

    ::1 localhost

    With:

    127.0.0.1 localhost

  3. Save the file and restart Kaazing WebSocket Gateway.

Demos Do Not Work When Using Fiddler Web Debugger as an HTTP Proxy

When Fiddler is used as an HTTP proxy, it can handle both http:// and https:// traffic. However, in order to monitor the https:// traffic, it must be able to decrypt the traffic. It can only do this if it serves a [fake] SSL certificate. When Kaazing WebSocket Gateway detects that traffic is flowing through an HTTP proxy (such as Fiddler), it attempts to automatically use an SSL downstream for the emulated WebSocket because unencrypted streaming responses can be buffered by the HTTP proxy, causing potentially lengthy delays in message delivery. The browser will automatically fail when attempting to download an https:// URL with untrusted (fake) certificate.

When the main URL for the entire page is from the fake URL, then the page displays some links allowing the user to "trust" the fake certificate anyway. For example, surfing to https://localhost:9000/ with Fiddler as the HTTP proxy will present the opportunity to trust the fake localhost certificate served by Fiddler. Once the browser has been instructed to trust the fake Fiddler certificate, then the demos should continue to work as before.

For more information, refer to http://www.fiddler2.com/Fiddler/help/httpsdecryption.asp.

Error: Host is Configured as a Secure Port in a Service

An error can occur when the same host and port is configured as secure in one service and not secure in another service. For example, your gateway-config.xml file may contain the following:

Service 1 (where wss:example.com:443 is configured as secure):

          <service>
          <accept>wss:example.com:443/service1</accept>
          ..
          </service>

Service 2 (where wss:example.com:443 is configured as not secure by disabling ssl.encryption):

          <service>
          <accept>wss:example.com:443/service2</accept>
            <accept-options>
              <ssl.encryption>disabled</ssl.encryption>
            </accept-options>
          </service>

At runtime, you may see an error similar to the following:

example.com<IP>:443 is configured as a secure port in a service already and cannot be bound as an unsecure port in service[wss://example.com:443/echo]

This error may occur when there is more than one service in use and one or more of the services is behind an SSL offloader. In this situation, you can resolve this error by moving the services being offloaded as a separate service (which uses a different port number), and disabling ssl.encryption.

Error: Unable to bind to resource: [network address] @ [network address] cause: Address already in use.

On Gateway startup, you see in the log an exception similar to the following:

java.lang.RuntimeException: Unable to bind to resource: wss://localhost:9001/echo @ wss://localhost:9111/echo cause: Address already in use
    at com.kaazing.gateway.server.transport.nio.AbstractNioAcceptor.bind(AbstractNioAcceptor.java:98)...

This exception can be caused by the following:

  • The port being bound is in use by another external process running on the host, such as an Apache HTTP server.
  • The port listed in the error has already been bound to another incompatible protocol in the gateway-config.xml. For example, you cannot bind HTTP and HTTPS to the same host and port combination. Check the protocol.bind element in your services (you may need to check the service-defaults section, as well) to ensure that multiple services are not bound to same port. Also, check that secure and unsecure protocols are not bound to the same port.

Missing Certificate Entry in Keystore When Starting the Gateway

When starting the Gateway, you see an error stating the following:

Keystore does not have a certificate entry for host:port.

This message usually occurs when the directory service in the Gateway is configured to access a secure URL for which it does not have a corresponding certificate in the keystore.db file, which is located in GATEWAY_HOME/conf.

To resolve this issue, ensure that you have imported the appropriate certificate into the keystore and that the directory service in the gateway-config.xml points to the same host and port as the certificate. For information on how to perform these steps, see Configuring Wire Traffic Encryption.

No Import Certificate Prompt in Browser

When using a WebSocket Secure (wss) connection, you navigate to your site that is using a self-signed certificate for testing purposes. When you access the URL, you are not prompted to import the self-signed certificate, as expected.

This prompt only displays when you access an HTTPS page. To resolve this issue, point your browser to an HTTPS page (for example, if you have retained the default directory service configuration in your gateway-config.xml, you can navigate to https://localhost:9000). For information on how to import a self-signed certificate into your browser, see Importing Self-Signed Certificates into a Browser.

Error When Starting the Gateway: String Value ['value'] does not match pattern for DataSize in namespace

When you start the Gateway, you see errors that look like the following:

ERROR Validation errors in gateway-config.xml
ERROR   Line: 15 Column: 33
ERROR   string value '128KB' does not match pattern for DataSizeString in namespace http://xmlns.kaazing.com/gateway-config/excalibur
ERROR   <xml-fragment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>

This error displays when the maximum.pending.bytes property contains an invalid value. For information on setting the maximum.pending.bytes property, see the proxy service description.

Warning: Error on WebSocket connection

In the Gateway log, you see something similar to the following:

2044-06-06 16:19:28,621 WARN Error on WebSocket connection, closing connection: incoming message size exceeds permitted maximum of 131072 bytes (Hexdump:...)

This warning occurs when a message incoming from a client to the Gateway exceeds the maximum size either specified by ws.maximum.message.size or by the default Gateway configuration of 128k.

To resolve this issue, the client can simply reconnect to the Gateway. If you wish to adjust the maximum message size that the Gateway can accept from a client, see ws.maximum.message.size.

Warning: ERROR string value 'value' does not match pattern

On Gateway startup, you see something similar to the following:

ERROR string value some_value does not match pattern for DataSizeString in namespace http://xmlns.kaazing.com/gateway-config/excalibur

This warning occurs when the ws.maximum.message.size element is set to an invalid value (indicated by "value" in the example warning).

To resolve this issue, open the GATEWAY_HOME/conf/gateway-config.xml and set the ws.maximum.message.size to a valid value.