Hudson-ci/features/Restart Within Hudson
Restart Within Hudson
Configuration changes that require Hudson restart to take effect should provide a
Restart link or button.
Currently, restart is external, e.g., by sending SIGINT or SIGTERM to the process or by restarting the Hudson application in the server. The CLI restart or soft-restart methods, which call
Hudson.safeRestart, respectively, don't handle many of the necessary use cases by default. A Hudson restart link based on these methods would too often fail. It is one thing to leave an opening for plugins to implement, but quite another to depend on the kindness of plugins for basic Hudson operations. The default Lifecycle implementation needs to be in some sense universal, even if it requires the cooperation of system administrators.
In the following, "correct restart" means restart specifically tailored to the environment in which the Hudson instance is running. "System administrator" is a person who provisions and deploys the Hudson instance. "Hudson admin" is a person with admin privileges in Hudson. Sometimes these are the same people; sometimes not.
- The current Lifecycle API must be preserved, for compatibility with existing plugin extensions. The new default mechanism will only be invoked if the
hudson.lifecyclesystem property is not specified.
- It must be possible for a system administrator to preconfigure Hudson for correct restart. This is particularly important for "no-admin" uses of Hudson.
- If the system administrator permits, it should be possible for a Hudson admin user to configure Hudson for correct restart. Note that this is necessary, but not sufficient, as a Hudson admin may not necessarily know how Hudson is deployed. For example, in robust Hudson installations, the instance of Hudson reachable by the same URL may change dynamically in response to system failure.
- Restart must require Hudson admin privileges (ACL.SYSTEM).
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.
Two new ways are provided for the system administrator to configure correct restart:
- by providing a
hudson-restartfile in the $HUDSON_HOME provisioned for the Hudson instance and
- by specifying a restart command on the command line when Hudson is invoked.
In a nutshell, restart within Hudson will invoke a system administrator- or Hudson admin-supplied command.
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 the restart command fails, restart will fail.
If the restart command is not specified, the existing default Lifecycle mechanism will be invoked.
hudson.lifecycle system property is specified, the restart command, if any, will not be used.
If allowed by system administrators, Hudson admins will be provided the ability, in the System Configurations page, 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.
Default Restart Script
To allow system administrators to pre-configure Hudson for correct 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
The script or program may have an extension, e.g.,
.bat on Windows or
.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.
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:
The value of the
restartCommand option will be used to initialize the restart command. The correct order of initialization is:
--restartCommandis specified, use that.
- Otherwise, if a restart script is present, use a command that invokes the script.
- Otherwise, the restart command is not specified initially.
If the option is not specified or is specified as
true, the admin will be able to view and change the restart command as above. If it is
false, the restart command will not appear in the Configure System page.
Restart Links or Buttons
Restart links should not be shown unless
true. Otherwise, a message like "Restart required for changes to take effect" should be displayed.
A restart link should show the single word Restart and should call
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