The Gateway Control Utility, sometimes referred to as simply the "GCU", is a lightweight stand-alone application that can provide information about the Ignition gateway. It also provides basic administrative controls, such as stopping and restarting the server, and setting the ports used between the gateway and clients. Note that the Gateway Control Utility must run on the same machine as the Ignition gateway.
Windows: The GCU can be launched from the start menu under Programs > Inductive Automation > Ignition > Launch Gateway Control Utility. You can also launch the GCU from either a command line or from the Start -> Run dialog by typing launch-gcu
Linux: The GCU can be launched by opening a command shell and typing gcu. If you receive an error saying that "gcu can't be found", then you need to add the Ignition installation directory to your system path. See the Installation (Linux) section for instructions. If you are running in a headless Linux environment, or you have logged into the Linux machine through an SSH shell, then the functions of the GCU are still available in command-line form. See the Command Line Utility section below.
Gateway Status
The upper left side of the screen shows the state of the Tomcat web server and the Ignition Gateway web application. It is possible for the web server to be running while the Gateway has failed. For example, this can occur when the Gateway has faulted upon startup.
Commands
The GCU provides several commands that can be run to administer the Gateway:
Go to webpage
Launches a web browser to the Gateway home page.
Restart
Restarts the Gateway.
Reset Password
Allows you to reset the root password of the system. This is not normally considered a security risk, because the GCU can only be used from the machine the software is installed on, which should be secure. However, it is important to know that this function is here, so that the GCU can be removed if the machine can't be properly secured (for example, when the server is also used as a client).
Thread dump
Downloads a file with the current states of all threads in the server, used by Inductive Automation for troubleshooting problems.
Gateway Backup
Downloads a Gateway backup (.gwbk) file to the local file system. A Save File dialog will open, allowing you to specify where to save the .gwbk file.
Gateway Restoration
Restores a Gateway using a Gateway backup (.gwbk) file that you provide. An Open File dialog will open, allowing you to select the .gwbk file.
WARNING: restoring a Gateway from a .gwbk file will overwrite all information currently saved in the Gateway! This operation will also restart the Gateway after restoration. If possible, you should always attempt to download a Gateway backup before attempting restoration. If your Gateway is totally unresponsive, you should still copy the /data folder to a safe location.
There are two modes for Gateway restoration: normal mode and disaster recovery mode. In normal mode, the GCU sends a restoration request to the Gateway with the .gwbk file that you would like to restore. The Gateway will perform some checks to ensure the provided .gwbk file is compatible, perform the restoration, and restart itself. Normal mode is always attempted first. If the Gateway is totally unresponsive to all requests, then disaster recovery mode is automatically selected. This mode copies the selected .gwbk to the /data folder as __restore.gwbk. A configuration file called ignition.conf is extracted from the .gwbk folder and overwrites the existing IGNITION_LOWER%>.conf in the /data folder. You may need to edit some paths in this file if you have modified the file in the past. You will also need to start the Gateway manually. When the Gateway starts, it will read __restore.gwbk and then perform the restoration.
Create offline activation request
Creates a license activation_request.txt file that you can use to request a license.ipl file from the Inductive Automation website (see the Offline Activation section for more details). You will be prompted to enter a CD-key to create the activation file. Use this function only if online activation through the Internet is not available.
Apply license.ipl
Applies a license.ipl file that was downloaded from the Inductive Automation website. An Open File dialog will open, allowing you to select the license.ipl file to use.
Create offline unactivation request
Creates an unactivate_message.txt file that you can use to unactivate a license via the Inductive Automation website (see the Unactivation section for more details). Use this function only if online unactivation through the Internet is not available. Also, the Gateway returns to trial mode immediately after the unactivate_message.txt file is generated. It is not possible to unactivate a Gateway again after it is already been unactivated once. Do not lose the unactivate_message.txt file until after it has been used on the Inductive Automation website!
Port
Sets the primary, non-encrypted port used by clients to communicate with the server. Click the Save button to apply the port change to the gateway. The gateway must be restarted for the change to take effect.
SSL Port
Sets the port that will be used by clients for SSL communication. Click the Save button to apply the port change to the gateway. The gateway must be restarted for the change to take effect.
Stop Service and Start Service
Windows users get two additional buttons at the top. The stop button stops the Ignition Windows service, and the start button starts the Ignition Windows service. Linux users can stop and start the gateway with these command-line commands:
/etc/init.d/ignition start
/etc/init.d/ignition stop
Command Line Utility
All the functions in the GCU are also available as a command line utility for both Windows and Linux. To run the utility, open a command shell and type in:
gwcmd <option>
Options are as follows:
-a,--activate <CD-key> |
Offline activation: creates an activation_request.txt file that can be used to request a license.ipl file from the Inductive Automation website. You must specify the CD-key to use for activation. The activation_request.txt file will be saved in the current directory. |
-b,--backup <new file path> |
Downloads a Gateway backup (.gwbk) file and saves the file to the specified path. The path can be either an absolute path or a relative path.If a new file name is not specified at the end of the path, then the file name will become the current date and time along with the .gwbk extension. You will be prompted whether it is OK to overwrite the file if another .gwbk file with the same name already exists (override with the -y option to force the file to always be overwritten). |
-h,--help |
Shows the usage for this command |
-i,--info |
Retrieves server status and port information from the Gateway if it is running |
-k,--port <new port> |
Changes the Gateway http port |
-l,--sslport <new port> |
Changes the Gateway https port |
-p,--passwd |
Resets the Gateway login password |
-r,--restart |
Restarts the Gateway |
-s, --restore <.gwbk path> |
Restores a Gateway from the provided .gwbk file |
-t,--tdump |
Performs a thread dump in the Gateway and prints the dump to the command line |
-u,--unactivate |
Offline unactivation: creates an unactivation_message.txt file that can be used to unactivate a license via the Inductive Automation website. The unactivation_message.txt file will be saved in the current directory. |
-w,--uselicense <license.ipl path> |
Applies a license.ipl file that was downloaded from the Inductive Automation website. You must supply the location of the license.ipl file. If it is in the current directory, use license.ipl for the location. |
-y,--promptyes |
Automatically answers "yes" to any prompt that may appear in the above commands (such as permission to overwrite an existing file). |