Configure Kaazing WebSocket 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 WebSocket 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_LICENSE_DIRECTORY | The path for the Gateway license 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 |
For GATEWAY_OPTS
environment variable examples, see GATEWAY_OPTS
Environment Variable Examples below.
Before You Begin
This procedure is part of Checklist: Configure Kaazing WebSocket Gateway:
- Configure Kaazing WebSocket Gateway
- Configure Kaazing WebSocket Gateway Using the
GATEWAY_OPTS
Environment Variables - Verify the Gateway configuration following the instructions for your deployment in Setting Up Kaazing WebSocket Gateway
To Configure the GATEWAY_OPTS
Environment Variable
- Ensure you have followed the steps in Setting Up Kaazing WebSocket Gateway to download and install Kaazing WebSocket Gateway.
- Ensure the Gateway is stopped.
How do I stop the Gateway?
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.
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 - Specify one or more system property values using
-Dproperty=value
with theGATEWAY_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 theGATEWAY_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
Notes:-Dproperty=value
switch on the Java command line, see the Java Application Launcher documentation.
- 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\""
- If you define multiple
- Start the Gateway.
How do I start the Gateway?
To Start the Gateway on Windows:
- In Windows Explorer, navigate to the GATEWAY_HOME/bin directory where you installed the Gateway.
- Double-click the gateway.start.bat script.
To Start the Gateway on Linux, UNIX, or Mac:
- Navigate to the KAAZING_HOME/bin directory where you installed the Gateway.
- Run the gateway.start script:
./gateway.start
When you successfully start the Gateway, messages similar to the following example
INFO
messages display in your shell or command prompt:INFO Kaazing WebSocket Gateway
Note: The startup message may differ depending on your Gateway configuration. If the server does not start successfully, contact your administrator or see Checklist: Troubleshoot Kaazing WebSocket Gateway for help finding the problem.
INFO Configuration file: GATEWAY_HOME/conf/gateway-config.xml
INFO Checking license information
INFO Found license: Developer License, Maximum 50 connections, See LICENSE.txt
INFO Starting server
INFO Starting services
INFO http://localhost:8000/
INFO http://localhost:8001/
INFO http://localhost:8001/session
INFO http://localhost:9000/
INFO sse://localhost:8001/sse
INFO ws://localhost:8001/echo
INFO Started services
INFO Starting management
INFO jmx://localhost:2020/
INFO Started management
INFO Started server successfully in 0.321 secs at 2044-06-06 22:22:00
Next Step
Verify the Gateway configuration following the instructions for your deployment in Setting Up Kaazing WebSocket 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.
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_LICENSE_DIRECTORY
Windows Example:
> SET GATEWAY_OPTS=-DGATEWAY_CONFIG=C:\Gateway\conf\gateway-config.xml -DGATEWAY_LICENSE_DIRECTORY=C:\Gateway\license
> C:\Gateway\bin\gateway.start.bat
Mac Example:
$ export GATEWAY_OPTS="-DGATEWAY_CONFIG=gateway-config.xml -DGATEWAY_LICENSE_DIRECTORY= \
/Users/johnsmith/Desktop/Gateway/license"
$ /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