What are the safe or unsafe ways to shut down / stop agent servers?

Resolving The Problem

What are the safe or unsafe ways to shut down / stop agent servers?

First, let's cover what is considered 'safe' vs. 'unsafe'
---------------------------------------------------------

- A 'safe' stop is one in which a running process is signalled to go through a series of steps to shut down properly. This would include things such as finishing up on a pending transaction, closing all open contexts within the JVM, unbinding the JNDI entry used for cache refreshes, etc. Given the cleanup that happens, the process may not shut down instantaneously.

- An 'unsafe' stop is one where a running process is terminated without regard to what the process is currently doing; none of the cleanup steps are given a chance to be executed. It is considered 'unsafe' from the view that there may be erroneous pieces of data left out in other processes or systems running.

Even in the case of an unsafe stop, there are coding practices or other processes that are used to help clean up anything that was left incomplete:

- Incomplete database transactions will be rolled back; when the agent is restarted, the rolled back transaction will be reprocessed, so there is no loss of data.

- Orphaned JVM contexts will be cleaned up as part of the next Garbage Collection.

- Orphaned, or stale, JNDI entries will be cleaned up during the next running of the System Management Console or Health Monitor; in addition, the JNDICleanup.sh script file can be run, as well as it (optionally) happening during the next time an Agent Server is started.

So, a safe stop is more desirable, but an unsafe stop can be done if the situation dictates.


Safe stops
----------

The Sterling Supply Chain Application suite provides two graceful, application-controlled mechanisms to shutdown an agent server:

1. Via the System Management Control
2. Programmatically, via the modifyServer API; a sample input XML is:
<Server Action="SHUTDOWN" Id="Server_1">
</Server>

If using one of these methods is not practical, then Unix/Linux "kill" command can be used.

In general, the 'kill' command is used to send a signal to a process, telling it what you would like to be done. Many of the signals are handled by 'hooks' within the Agent Server code framework; when 'kill' sends the signal number to the process, the process itself looks at the signal and decides what to do. For example, when you use the command "kill -3 <process-id>", you are telling the process to keep running, but to also dump out a thread trace.

The following kill commands can be used to safely shut down an Agent Server process - each of them have been set up within the Sterling code to properly shut things down, as described above. (Note: the signal names, such as SIGHUP, or 'Signal Hangup', are the same across all flavors of Unix. The actual numbers assigned to them can vary, but for most systems the values below are correct. If in doubt, check with your system manuals.)

kill <process-id>
kill -1 <process-id> or kill -SIGHUP <process-id>
kill -2 <process-id> or kill -SIGINT <process-id>
kill -15 <process-id> or kill -SIGTERM <process-id>

Control + C, for a process running in the foreground, is also the equivalent to 'kill -2'


Unsafe stops
------------

There is one kill command that will not actually signal the process, but will tell the operating system to kill of the process. This cannot be controlled by coding, since the agent never hears about the requested signal.

kill -9 <process-id> or kill -SIGKILL <process-id>

This command terminates the process with no cleanup, so it should be used sparingly, and as a last resort (such as when an agent doesn't appear to be responding to a normal 'kill <process-id>' command. As mentioned above, the other methods/processes should be used to clean up remaining issues, such as stale JNDI entries.