Solution

Background

Migrating or cloning a virtual appliance can be very useful for deploying previously configured API Gateways into new environments. It allows an administrator to relocate a completely functional API Gateway as if you are moving a physical appliance within the network. In some circumstances, an API Gateway may fail to initialize after the virtual appliance was cloned and/or migrated or a physical API Gateway appliance was moved to a new network configuration.?As a result of this migration, the network configuration of the Gateway appliance may change.

Presentation

The most glaring symptom is the API Gateway will fail to start via the API Gateway configurator (ssgconfig) menu or via the API Gateway initialization script (`service ssg start`). You may also be presented with an error message in the console or API Gateway log files as: ssg dead but pid file exists.

Cause

This error generally occurs when an API Gateway appliance is migrated or cloned and has its network configuration changed as a result. There are two direct issues that can occur during a migration, cloning, or reconfiguration: The API Gateway is stopped improperly or the remote management configuration is not updated.

Remote Management configuration

This issue can present when the network configuration of the API Gateway is modified with Remote Management configured on the API Gateway. The remote management of the API Gateway (via the Enterprise Service Manager) can be configured to allow management only over a specific interface or on all interfaces. If the IP address used for remote management (e.g., 192.168.1.56) does not match the IP address interface used for local management (i.e., eth0), then the API Gateway will fail to start. By default, remote management listens on all interfaces unless configured otherwise.

Improper shutdown of service or appliance

When the service or appliance is stopped properly, it removes a process identifier (PID) file that allows the API Gateway to determine its current state. By design, the API Gateway will remove this PID file when properly shutdown. If the API Gateway is not properly shutdown, then this PID file may still exist and could contain invalid data.

Resolution

Start by reverting the Remote Management configuration of the API Gateway to the default and restarting the service:

1. Log onto the Gateway as the ssgconfig user.
2. Select Option 5: Display Remote Management configuration menu.
3. Select Option 1: Listener IP address.
4. Set the Listener IP address to "*".
5. Select Option S: Save changes and exit.
6. Select Option 2: Display Layer 7 Gateway configuration menu.
7. Select Option 7: Manage Layer 7 Gateway status.
8. Select Option 2: Restart the Layer 7 Gateway.

At this point, the API Gateway should start successfully and be able to take traffic and be accessible via the Policy Manager. If this does not work, follow the following procedure to remove the existing PID file:

1. Terminate all running Java processes:?ps -ef | grep java | awk '{print $2}' | xargs kill -9
2. Remove the invalid PID references:?rm -f /opt/SecureSpan/Gateway/node/default/var/ssg.pid && rm -f /var/lock/subsys/ssg
3. Restart the service:?service ssg restart
4. Verify the PID references are valid. ps -ef | grep `cat /opt/SecureSpan/Gateway/node/default/var/ssg.pid`

Release:
Component: APIGTW

.