Gateway Control Utility

GCU

The Gateway Control Utility, (or GCU), is a lightweight standalone application that provides information about the Gateway. You can use the GCU to monitor the Ignition Gateway and perform high-level tasks that aren't available inside of the web application. It provides basic administrative controls, such as stopping and restarting the server and setting the ports used between the Gateway and clients.

note

The Gateway Control Utility must run on the same machine as the Ignition Gateway and requires administrative privileges.

Lauching the GCU

Windows

From the Start menu, go to All Programs > Inductive Automation > Ignition > Launch Gateway Control Utility.

You can also launch GCU from the command-line or from the Start > Run dialog by typing:

launch -gcu

Linux

Open a command shell and type:

gcu

If you receive an error saying gcu can't be found, add the Ignition installation directory to your system path.

If you are running in a headless Linux environment or you have logged into the Linux machine through an SSH shell, the GCU functions are still available in command-line form. See Command-line Utility section below.

Mac OS X

Open up a Terminal window and enter:

/usr/local/ignition/gcu.sh This assumes that the default install directory was used. If you receive an error about not having the proper permissions, you may need to add 'sudo' to the front of the command.

caution

In some cases, the GCU will not work correctly on Mac OS X. If JAVA_HOME is defined and pointed to the wrong version of Java then the JRE in that path will be used. To fix this, you can define the following in the gcw.sh file:

export JAVA_HOME="/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home"

The path to the JRE will be different for different machines, so adjust your path to match.

GCU Window

When GCU is launched, a window is displayed.

Status

On the upper-left of the window, Status 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 Gateway has failed. For example, this can occur when the Gateway has faulted on startup.

Start and Stop

At the top right of the window sits start and stop button. Start looks like a green play button while stop looks like a red stop sign. These buttons will start and stop the gateway, respectively.

caution

These buttons are only available on windows installations.

Version

The version of Ignition that is running on this computer.

Ports

On the lower-left of the window, Port shows the primary, non-encrypted port used by clients and web pages to communicate with the server. You can see the ports that you are using and you can change the ports and click the Save button to save the ports to the Gateway. Note that Gateway must be restarted for the changes to take effect.

tip

When using any of the functions listed below in the Gateway Control Utility, the Gateway must be running for them to work properly.

Go to web page

On the right side of the window, Go to web page launches a web browser to the Gateway home page.

Restart

On the right side of the window, Restart restarts the Ignition web server. This should only be used while the server is running to stop the gateway then automatically start it back up.

Reset Password

On the right side of the window, Reset Password will reset the root password of the system. This default is Username: admin, password: password and will grant access to the Gateway Webpage. Normally, this is not 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 about this feature 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

On the right side of the window, Thread Dump downloads a file with the current states of all threads in the server. Inductive Automation uses this file for troubleshooting problems.

Gateway Backup

On the right side of the window, Gateway Backup downloads a Gateway backup .gwbk file to the local file system. This creates the exact same file as the Gateway Backup in the Gateway Webpage. A Save dialog opens to let you specify where you want to save t he file.

Gateway Restore

On the right side of the window, Gateway Restore asks for a Gateway backup .gwbk file and restores it. This does the exact same restore as the Gateway Restore in the Gateway Webpage. Note: this will completely overwrite your existing Gateway.

Create offline activation request

On the right side of the window, Create offline activation request creates a file to use on the offline activation process. This is the same file created in the manual activation process.

Apply license.ipl

On the right side of the window, Apply license.ipl asks for an .ipl file to use to complete the offline activation process. This is the same file used in the manual activation process.

Create offline unactivation request

On the right side of the window, Create offline unactivation request creates a file to use on the offline activation process. This is the same file created in the manual unactivation process.

Command-line Utility

All the functions in the GCU are also available as a command-line utility.

To run the utility, open a command shell and type:

gwcmd <option>

Options	Descriptions
a,-–activate <CDk-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 license key to use for activation. The activation_request.txt file is saved in the current directory.
-b,--backup <new filepath>	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. You will be prompted whether it is OK to overwrite the file if another .gwbk file with the same name already exists. You can 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	Restores a gateway backup (.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 you can use to unactivate a license via the Inductive Automation website. The unactivation_message.txt file is 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.