Configure Kaazing Gateway Using the GATEWAY_OPTS Environment Variable

On occasion you might want the flexibility to change the configuration that is set up in your Gateway configuration file (see About Kaazing Gateway Configuration Files) or change the Java process temporarily without modifying the configuration file itself. For example, you might want to define your own startup scripts that specify different log4j configurations or different log directories. You can do that by setting the GATEWAY_OPTS environment variable (or any other Java option or command-line setting) to include any of the properties in the following table:

Variable	Description
GATEWAY_HOME	The directory path for the Gateway home
GATEWAY_CONFIG	The name of the Gateway configuration file
GATEWAY_CONFIG_DIRECTORY	The path for the Gateway configuration directory
GATEWAY_WEB_DIRECTORY	The path for the Gateway web directory
GATEWAY_TEMP_DIRECTORY	The path for the Gateway temp files directory
GATEWAY_LOG_DIRECTORY	The path for the Gateway logfiles directory
GATEWAY_USER_LIB_DIRECTORY	The path for the Gateway user library files
LOG4J_CONFIG	The name and path for the Gateway log4j configuration file
GATEWAY_FEATURES	A comma-separated list of values that lists the Early Access features. For more information, see Enable Early Access Features.

For GATEWAY_OPTS environment variable examples, see GATEWAY_OPTS Environment Variable Examples below.

Before You Begin

This procedure is part of Configure the Gateway:

• Configure Kaazing Gateway
• Configure Kaazing Gateway Using the GATEWAY_OPTS Environment Variables
• Verify the Gateway configuration following the instructions for your deployment in Setting Up the Gateway

To Configure the GATEWAY_OPTS Environment Variable

1. Ensure you have followed the steps in Setting Up the Gateway to download and install Kaazing Gateway.
2. Ensure the Gateway is stopped.
   1. To Stop the Gateway on Windows: press CTRL + C in the command prompt that was used to start the Gateway, or close the command prompt.

   2. To Stop the Gateway on Linux, UNIX, and Mac: use the following commands (where process ID is the process ID of the Gateway process):

      ps –ef | grep *process name*
       kill *process ID*
      

3. Specify one or more system property values using -Dproperty=value with the GATEWAY_OPTS environment variable.

   The environment variable GATEWAY_OPTS can contain a space-separated list of command-line arguments. For example, to specify the name of the Gateway configuration and the Gateway log directory at the Linux command line, specify the GATEWAY_OPTS environment variable as follows:

   GATEWAY_OPTS="-DGATEWAY_CONFIG=gateway-config.xml
   -DGATEWAY_LOG_DIRECTORY=/home/myname/gateway/logs"
   

   To learn more about using the -Dproperty=value switch on the Java command line, see the Java Application Launcher documentation.

   Notes:

   • If you define multiple -Dproperty=value variables then there must be a space between each variable, and you must enclose the entire value in quotes. For example:

     GATEWAY_OPTS="-DGATEWAY_CONFIG=gateway-config.xml
     -DGATEWAY_LOG_DIRECTORY=/home/my-company/gateway/logs"
     

   • If the value of a -Dproperty=value variable contains spaces, then use the \" notation around the value. In the following example, the value for -DGATEWAY_LOG_DIRECTORY is wrapped in the \" notation because it contains spaces:

     GATEWAY_OPTS="-DGATEWAY_CONFIG=gateway-config.xml
     -DGATEWAY_LOG_DIRECTORY=\"/home/my company/gateway/logs\""
     

4. Start the Gateway.

   To Start the Gateway on Windows, see Setting Up the Gateway and Clients.

   When you successfully start the Gateway, messages display in your shell or command prompt indicating the services that are hosted by the Gateway. The startup message may differ depending on your Gateway configuration. If the server does not start successfully, contact your administrator or see Troubleshoot the Gateway for help finding the problem.

Next Step

Verify the Gateway configuration following the instructions for your deployment in Setting Up the Gateway

Notes

• Any system property values that you define with the GATEWAY_OPTS environment variable before starting the Gateway are used and override the values specified in the default Gateway configuration.

Enable Early Access Features

Early Access features are new features that are made available in Kaazing products for early access and testing purposes before they are ready for production deployments.

Early Access features are identified using the image .

Notes:

• Early Access features should be used for development and testing purposes only. They are not supported for use in a production environment.
• An Early Access feature might change when it is incorporated as a completed, production-ready feature.
• If a Gateway configuration setting must be added to the gateway-config.xml file in order for an Early Access feature to work and you have not added the configuration setting, then the Gateway startup will fail with an error message indicating that you need to configure the Gateway for the feature.
• If you are using an embedded Gateway, you must use the GATEWAY_OPTS environment variable, explained below.

To enable Early Access features, do the following:

1. Ensure the Gateway is stopped.
2. Enable the feature in one of the following ways. For this example, we will specify Early Access features named feature1, feature2, and feature3.
   • Use the GATEWAY_FEATURES environment variable:

     Windows Example:

     > SET GATEWAY_FEATURES=feature1, feature2, feature3

     > C:\Gateway\bin\gateway.start.bat

     Mac Example:

     $ export GATEWAY_FEATURES="feature1, feature2, feature3"
$ /Users/johnsmith/Desktop/Gateway/bin/gateway.start

   • Use the GATEWAY_OPTS environment variable:

     Windows Example:

     > SET GATEWAY_OPTS=-Dfeature.feature1, -Dfeature.feature2, -Dfeature.feature3

     > C:\Gateway\bin\gateway.start.bat

     Mac Example:

     $ export GATEWAY_OPTS="-Dfeature.feature1, -Dfeature.feature2, -Dfeature.feature3"
$ /Users/johnsmith/Desktop/Gateway/bin/gateway.start

   • Use your own Java system properties:

     java -Dfeature.feature1, -Dfeature.feature2, -Dfeature.feature3 ...

Update Check

The Update Check feature checks to see if there are new versions of the Gateway available when the Gateway is started. New versions include patches, and minor and major releases. Update Check is enabled by default.

The update check output information is displayed in the log file (GATEWAY_HOME/log/error.log), the terminal or command prompt screen, and the JMX console.

The Gateway will start regardless of whether the update check is successful. If the update check fails, then a warning is logged to the log file and terminal or command prompt screen.

If you do not want the Gateway to check for updates, start the Gateway using the following GATEWAY_OPTS environment variable:

GATEWAY_OPTS=-Dcom.kaazing.server.UPDATE_CHECK=false

Note: The environment variable org.kaazing.gateway.server.UPDATE_CHECK is deprecated.

GATEWAY_OPTS Environment Variable Examples

GATEWAY_HOME

Windows Example:

> SET GATEWAY_OPTS=-DGATEWAY_HOME=C:\Gateway\

> C:\Gateway\bin\gateway.start.bat

Mac Example:

$ export GATEWAY_OPTS="-DGATEWAY_HOME=/Users/johnsmith/Desktop/Gateway/"
$ /Users/johnsmith/Desktop/Gateway/bin/gateway.start

GATEWAY_CONFIG

Windows Example:

> SET GATEWAY_OPTS=-DGATEWAY_CONFIG=C:\Gateway\conf\gateway-config-test.xml
> C:\Gateway\bin\gateway.start.bat

Here is an alternative way to specify the configuration file:

> gateway.start.bat --config C:\Gateway\conf\gateway-config-test.xml

Mac Example:

$ export GATEWAY_OPTS="-DGATEWAY_CONFIG=/Users/johnsmith/Desktop/Gateway/conf/gateway-config-test.xml"

$ /Users/johnsmith/Desktop/Gateway/bin/gateway.start

Here is an alternative way to specify the configuration file:

./gateway.start --config /Users/johnsmith/Desktop/Gateway/conf/gateway-config-test.xml

GATEWAY_CONFIG_DIRECTORY

Windows Example:

> SET GATEWAY_OPTS=-DGATEWAY_CONFIG=C:\Gateway\conf\gateway-config-test.xml -DGATEWAY_CONFIG_DIRECTORY=C:\Gateway\conf

> C:\Gateway\bin\gateway.start.bat

Mac Example:

$ export GATEWAY_OPTS="-DGATEWAY_CONFIG=gateway-config-test.xml -DGATEWAY_CONFIG_DIRECTORY= \ /Users/johnsmith/Desktop/Gateway/conf"

$ /Users/johnsmith/Desktop/Gateway/bin/gateway.start

GATEWAY_WEB_DIRECTORY

Windows Example:

> SET GATEWAY_OPTS=-DGATEWAY_CONFIG=C:\Gateway\conf\gateway-config.xml -DGATEWAY_WEB_DIRECTORY=C:\Gateway\web-test

> C:\Gateway\bin\gateway.start.bat

Mac Example:

$ export GATEWAY_OPTS="-DGATEWAY_CONFIG=gateway-config.xml -DGATEWAY\_WEB\_DIRECTORY=/Users/johnsmith/Desktop/Gateway/web-test"

$ /Users/johnsmith/Desktop/Gateway/bin/gateway.start

GATEWAY_TEMP_DIRECTORY

Windows Example:

> SET GATEWAY_OPTS=-DGATEWAY_CONFIG=C:\Gateway\conf\gateway-config.xml -DGATEWAY_TEMP_DIRECTORY=C:\Gateway\temp-test

> C:\Gateway\bin\gateway.start.bat

Mac Example:

$ export GATEWAY_OPTS="-DGATEWAY_CONFIG=gateway-config.xml -DGATEWAY_TEMP_DIRECTORY=/Users/johnsmith/Desktop/Gateway/temp-test"

$ /Users/johnsmith/Desktop/Gateway/bin/gateway.start

GATEWAY_LOG_DIRECTORY

Windows Example:

> SET GATEWAY_OPTS=-DGATEWAY_CONFIG=C:\Gateway\conf\gateway-config.xml -DGATEWAY_LOG_DIRECTORY=C:\Gateway\log

> C:\Gateway\bin\gateway.start.bat

Mac Example:

$ export GATEWAY_OPTS="-DGATEWAY_CONFIG=gateway-config.xml -DGATEWAY_LOG_DIRECTORY=/Users/johnsmith/Desktop/Gateway/log"

$ /Users/johnsmith/Desktop/Gateway/bin/gateway.start

GATEWAY_USER_LIB_DIRECTORY

Windows Example:

> SET GATEWAY_OPTS=-DGATEWAY_CONFIG=C:\Gateway\conf\gateway-config.xml -DGATEWAY_USER_LIB_DIRECTORY=C:\Gateway\lib

> C:\Gateway\bin\gateway.start.bat

Mac Example:

$ export GATEWAY_OPTS="-DGATEWAY_CONFIG=gateway-config.xml -DGATEWAY\_USER\_LIB\_DIRECTORY=/Users/johnsmith/Desktop/Gateway/lib"

$ /Users/johnsmith/Desktop/Gateway/bin/gateway.start

LOG4J_CONFIG

Windows Example:

> SET GATEWAY_OPTS=-DGATEWAY_CONFIG=C:\Gateway\conf\gateway-config.xml -DLOG4J_CONFIG=C:\Gateway\log\log4j.xml

> C:\Gateway\bin\gateway.start.bat

Mac Example:

$ export GATEWAY_OPTS="-DGATEWAY_CONFIG=gateway-config.xml -DLOG4J_CONFIG=/Users/johnsmith/Desktop/Gateway/log/log4j.xml"

$ /Users/johnsmith/Desktop/Gateway/bin/gateway.start

See Also

• About Gateway Configuration
• Configure the Gateway
• Documentation Conventions