Hudson-ci/features/Restart Within Hudson

Restart Within Hudson

Several Hudson administration changes require Hudson restart. Currently, restart is external, e.g., by sending SIGINT or SIGTERM to the process, by restarting the Hudson application in the server or by using the CLI restart or soft-restart methods. As a convenience, configuration changes that require restart should provide a restart link.

Design Approach

A simple way to implement restart is to call Hudson.safeRestart (which is what the CLI method does) which calls Hudson.restart. Unfortunately, restart doesn't work in a number of cases.

• It doesn't work by default on Windows.
• On Unix by default it:
  • restarts the entire process, e.g., the server, not just the Hudson application.
  • does not restart as a daemon, even if it currently is.

Correct restart is a multi-dimensional problem, different for each OS, service implementation and container (Tomcat, Jetty, GlassFish, etc.). The Lifecycle extension point is not well suited for multi-dimensional invocation, e.g., the OS is X AND the container is Y and (the container does not support single application restart OR the application name/war file location in the container is Z). While certain tricks, like replacing the Hudson WAR file, work to restart the application in many containers, to cover all the possibilites, Lifecycle would need an extension for every possible combination.

Yet, every system administrator already knows or can easily discover a command or script to restart any running Hudson instance. The best and most likely to be correct restart mechanism would leverage those commands/scripts and not try to replace it with Java code. The feature described below provides a generic Lifecycle that does.

Restart Command

In the System Configurations page Hudson admins will be provided the ability to specify a Restart Command to be executed when Hudson.restart is called. Typically, the command would execute a shell script or bat file, though this is not required.

Since the command is presumed to restart Hudson, it may not return at all. If it does return, it is expected to return successfully. If no Restart Command is specified or if the command fails, the current Lifecycle mechanism will be invoked.

If the Restart Command is not specified, the existing Lifecycle mechanism will be invoked.

Default Restart Script

To make it easier for admins to pre-configure Hudson for proper restart, if a Restart Script is present in HUDSON_HOME the initial value of the Restart Command will be set to invoke the script. The script must be named hudson_restart[.extension].

The script may have an extension, e.g., .bat on Windows or .sh, .bash, .py, etc. on Unix, but it doesn't matter what it is; in all cases, it will be invoked as a program.

The script must be executable.

The script should be specific to the environment in which the HUDSON_HOME is used.

Restart Options

Even if a Restart Script is present in HUDSON_HOME, a Hudson admin may change the Restart Command to do something else, effectively ignoring the script. This may be overridden by the command line switch:

--changeRestartCommand=true|false

If the option is not specified or is specified as true, the admin will be able to reconfigure the Restart Command as above. If it is false, the Restart Command will not appear in the Configure System page.

--restartCommand=value

The value of the restartCommand option will be used to initialize the Restart Command. The correct order of initialization is:

• If --restartCommand is specified, use that.
• Otherwise, if a Restart Script is present, use a command that invokes the script.
• Otherwise, the Restart Command is initially not specified.

Restart Links

Restart links should not be shown unless Hudson.canRestart returns true. A restart link should show the single word Restart and should call Hudson.softRestart.

Plugin Manager

The Plugin Manager will show a restart link if a) a plugin is updated or a plugin is loaded that requires restart, and b) if Hudson.canRestart returns true