This is an automated email from the ASF dual-hosted git repository. markt pushed a commit to branch 8.5.x in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/8.5.x by this push: new bd29b1eee4 Update docs for procrun (Commons Daemon) bd29b1eee4 is described below commit bd29b1eee445f240dc8ddc556f50493690655e20 Author: Mark Thomas <ma...@apache.org> AuthorDate: Wed Nov 30 15:58:14 2022 +0000 Update docs for procrun (Commons Daemon) --- webapps/docs/windows-service-howto.xml | 660 +++++++++++++++++++-------------- 1 file changed, 379 insertions(+), 281 deletions(-) diff --git a/webapps/docs/windows-service-howto.xml b/webapps/docs/windows-service-howto.xml index c03ef928fa..58c26c1e20 100644 --- a/webapps/docs/windows-service-howto.xml +++ b/webapps/docs/windows-service-howto.xml @@ -33,311 +33,409 @@ <toc/> </section> -<section name="Tomcat service application"> -<p> - <b>Tomcat<version-major/></b> is a service application for running Tomcat - <version-major/> as a Windows service. -</p> -</section> <section name="Tomcat monitor application"> -<p> - <b>Tomcat<version-major/>w</b> is a GUI application for monitoring and - configuring Tomcat services. -</p> - <p>The available command line options are:</p> - <table class="defaultTable"> - <tr><td><b>//ES//</b></td> - <td>Edit service configuration</td> - <td>This is the default operation. It is called if the no option is - provided but the executable is renamed to <b>servicenameW.exe</b></td> + <p><b>Tomcat<version-major/>w</b> is a GUI application for monitoring and + configuring Tomcat services.</p> + + <subsection name="Command line directives"> + + <p>Each command line directive is in the form of + <code>//XX[//ServiceName]</code></p> + + <p>If the <code>//ServiceName</code> component is omitted, then the service + name is assumed to be the name of the file less the w suffix. So the default + service name is <code>Tomcat<version-major/></code>.</p> + + <p>The available command line directives are:</p> + + <table class="defaultTable"> + <tr> + <td><b>//ES</b></td> + <td>Edit service configuration</td> + <td>This is the default operation. It is called if the no option is + provided. Starts the GUI application which allows the service + configuration to be modified, started and stopped.</td> </tr> - <tr><td><b>//MS//</b></td> - <td>Monitor service</td> - <td>Put the icon in the system tray</td> + <tr> + <td><b>//MS</b></td> + <td>Monitor service</td> + <td>Starts the GUI application and minimizes it to the system tray.</td> </tr> - </table> + <tr> + <td><b>//MR</b></td> + <td>Monitor & run service</td> + <td>Starts the GUI application and minimizes it to the system tray. Start + the service if it is not currently running.</td> + </tr> + <tr> + <td><b>//MQ</b></td> + <td>Monitor quit</td> + <td>Stop any running monitor for the service.</td> + </tr> + </table> +</subsection> </section> -<section name="Command line arguments"> -<p> - Each command line directive is in the form of <b>//XX//ServiceName</b> -</p> - <p>The available command line options are:</p> +<section name="Tomcat service application"> + + <p><b>Tomcat<version-major/></b> is a service application for running Tomcat + <version-major/> as a Windows service.</p> + + <subsection name="Command line directives"> + + <p>Each command line directive is in the form of + <code>//XX[//ServiceName]</code></p> + + <p>The available command line directives are:</p> <table class="defaultTable"> - <tr><td><b>//TS//</b></td> + <tr> + <td><b>//TS</b></td> <td>Run the service as console application</td> <td>This is the default operation. It is called if the no option is provided. The ServiceName is the name of the executable without exe suffix, meaning Tomcat<version-major/></td> - </tr> - <tr><td><b>//RS//</b></td> + </tr> + <tr> + <td><b>//RS</b></td> <td>Run the service</td> <td>Called only from ServiceManager</td> - </tr> - <tr><td><b>//SS//</b></td> + </tr> + <tr> + <td><b>//ES</b></td> + <td>Start (execute) the service</td> + <td></td> + </tr> + <tr> + <td><b>//SS</b></td> <td>Stop the service</td> <td></td> - </tr> - <tr><td><b>//US//</b></td> + </tr> + <tr> + <td><b>//US</b></td> <td>Update service parameters</td> <td></td> - </tr> - <tr><td><b>//IS//</b></td> + </tr> + <tr> + <td><b>//IS</b></td> <td>Install service</td> <td></td> - </tr> - <tr><td><b>//DS//</b></td> + </tr> + <tr> + <td><b>//DS</b></td> <td>Delete service</td> <td>Stops the service if running</td> - </tr> + </tr> + <tr> + <td><b>//PS</b></td> + <td>Print service</td> + <td>Prints the command to (re-)create the current configuration</td> + </tr> + <tr> + <td><b>//PP[//seconds]</b></td> + <td>Pause service</td> + <td>Default is 60 seconds</td> + </tr> + <tr> + <td><b>//VS</b></td> + <td>Version</td> + <td>Print version and exit</td> + </tr> + <tr> + <td><b>//?</b></td> + <td>Help</td> + <td>Print usage and exit</td> + </tr> </table> + </subsection> -</section> -<section name="Command line parameters"> -<p> - Each command line parameter is prefixed with <b>--</b>. If the command line - parameter is prefixed with <b>++</b> then it's value will be appended to the - existing option. - If the environment variable with the same name as command line parameter but - prefixed with <code>PR_</code> exists it will take precedence. - For example:</p> -<source>set PR_CLASSPATH=xx.jar</source> - -<p>is equivalent to providing</p> -<source>--Classpath=xx.jar</source> -<p> as command line parameter.</p> + <subsection name="Command line parameters"> + + <p>Each command line parameter is prefixed with <code>--</code>. If the + command line parameter is prefixed with <code>++</code>, and the parameter + supports multiple values, then it's value will be appended to the existing + option. In the table below, parameters that support multiple values are + prefixed with <code>++</code>.</p> + + <p>If the environment variable with the same name as command line parameter + but prefixed with <code>PR_</code> exists it will take precedence. For + example:</p> + + <source>set PR_CLASSPATH=xx.jar</source> + + <p>is equivalent to providing</p> + + <source>--Classpath=xx.jar</source> + + <p> as command line parameter.</p> <table class="defaultTable"> - <tr> - <th>ParameterName</th> - <th>Default</th> - <th>Description</th> - </tr> - <tr> - <td>--Description</td> - <td></td> - <td>Service name description (maximum 1024 characters)</td> - </tr> - <tr> - <td>--DisplayName</td> - <td>ServiceName</td> - <td>Service display name</td> - </tr> - <tr> - <td>--Install</td> - <td>procrun.exe //RS//ServiceName</td> - <td>Install image</td> - </tr> - <tr> - <td>--Startup</td> - <td>manual</td> - <td>Service startup mode can be either <b>auto</b> or <b>manual</b></td> - </tr> - <tr> - <td>--DependsOn</td> - <td></td> - <td>List of services that this service depend on. Dependent services - are separated using either <b>#</b> or <b>;</b> characters</td> - </tr> - <tr> - <td>--Environment</td> - <td></td> - <td>List of environment variables that will be provided to the service - in the form <b>key=value</b>. They are separated using either - <b>#</b> or <b>;</b> characters. If you need to use either the <b>#</b> - or <b>;</b> character within a value then the entire value must be - enclosed inside single quotes.</td> - </tr> - <tr> - <td>--User</td> - <td></td> - <td>User account used for running executable. It is used only for - StartMode <b>java</b> or <b>exe</b> and enables running applications - as service under account without LogonAsService privilege.</td> - </tr> - <tr> - <td>--Password</td> - <td></td> - <td>Password for user account set by --User parameter</td> - </tr> - <tr> - <td>--JavaHome</td> - <td>JAVA_HOME</td> - <td>Set a different JAVA_HOME than defined by JAVA_HOME environment - variable</td> - </tr> - <tr> - <td>--Jvm</td> - <td>auto</td> - <td>Use either <b>auto</b> (i.e. find the JVM from the Windows registry) - or specify the full path to the <b>jvm.dll</b>. - You can use the environment variable expansion here.</td> - </tr> - <tr> - <td>--JvmOptions</td> - <td>-Xrs</td> - <td>List of options in the form of <b>-D</b> or <b>-X</b> that will be - passed to the JVM. The options are separated using either - <b>#</b> or <b>;</b> characters. If you need to embed either <b>#</b> or - <b>;</b> characters, put them inside single quotes. (Not used in - <b>exe</b> mode.)</td> - </tr> - <tr> - <td>--JvmOptions9</td> - <td></td> - <td>List of options in the form of <b>-D</b> or <b>-X</b> that will be - passed to the JVM when running on Java 9 or later. The options are - separated using either <b>#</b> or <b>;</b> characters. If you need to - embed either <b>#</b> or <b>;</b> characters, put them inside single - quotes. (Not used in <b>exe</b> mode.)</td> - </tr> - <tr> - <td>--Classpath</td> - <td></td> - <td>Set the Java classpath. (Not used in <b>exe</b> mode.)</td> - </tr> - <tr> - <td>--JvmMs</td> - <td></td> - <td>Initial memory pool size in MB. (Not used in <b>exe</b> mode.)</td> - </tr> - <tr> - <td>--JvmMx</td> - <td></td> - <td>Maximum memory pool size in MB. (Not used in <b>exe</b> mode.)</td> - </tr> - <tr> - <td>--JvmSs</td> - <td></td> - <td>Thread stack size in KB. (Not used in <b>exe</b> mode.)</td> - </tr> - <tr> - <td>--StartMode</td> - <td></td> - <td>One of <b>jvm</b>, <b>Java</b> or <b>exe</b>. The modes are: - <ul> - <li>jvm - start Java in-process. Depends on jvm.dll, see <b>--Jvm</b>.</li> - <li>Java - same as exe, but automatically uses the default Java - executable, i.e. %JAVA_HOME%\bin\java.exe. Make sure JAVA_HOME is set - correctly, or use --JavaHome to provide the correct location. - If neither is set, procrun will try to find the default JDK (not JRE) - from the Windows registry.</li> - <li>exe - run the image as a separate process</li> - </ul> - </td> - </tr> - <tr> - <td>--StartImage</td> - <td></td> - <td>Executable that will be run. Only applies to <b>exe</b> mode.</td> - </tr> - <tr> - <td>--StartPath</td> - <td></td> - <td>Working path for the start image executable.</td> - </tr> - <tr> - <td>--StartClass</td> - <td>Main</td> - <td>Class that contains the startup method. Applies to the <b>jvm</b> and - <b>Java</b> modes. (Not used in <b>exe</b> mode.) </td> - </tr> - <tr> - <td>--StartMethod</td> - <td>main</td> - <td>Method name if differs then main</td> - </tr> - <tr> - <td>--StartParams</td> - <td></td> - <td>List of parameters that will be passed to either StartImage or - StartClass. Parameters are separated using either <b>#</b> or - <b>;</b> character.</td> - </tr> - <tr> - <td>--StopMode</td> - <td></td> - <td>One of <b>jvm</b>, <b>Java</b> or <b>exe</b>. See <b>--StartMode</b> - for further details. </td> - </tr> - <tr> - <td>--StopImage</td> - <td></td> - <td>Executable that will be run on Stop service signal. Only applies to - <b>exe</b> mode.</td> - </tr> - <tr> - <td>--StopPath</td> - <td></td> - <td>Working path for the stop image executable. Does not apply to <b>jvm</b> - mode.</td> - </tr> - <tr> - <td>--StopClass</td> - <td>Main</td> - <td>Class that will be used on Stop service signal. Applies to the - <b>jvm</b> and <b>Java</b> modes. </td> - </tr> - <tr> - <td>--StopMethod</td> - <td>main</td> - <td>Method name if differs then main</td> - </tr> - <tr> - <td>--StopParams</td> - <td></td> - <td>List of parameters that will be passed to either StopImage or - StopClass. Parameters are separated using either <b>#</b> or - <b>;</b> character.</td> - </tr> - <tr> - <td>--StopTimeout</td> - <td>No Timeout</td> - <td>Defines the timeout in seconds that procrun waits for service to - exit gracefully.</td> - </tr> - <tr> - <td>--LogPath</td> - <td>%SystemRoot%\System32\LogFiles\Apache</td> - <td>Defines the path for logging. Creates the directory if necessary.</td> - </tr> - <tr> - <td>--LogPrefix</td> - <td>commons-daemon</td> - <td>Defines the service log filename prefix. The log file is created in the - LogPath directory with <code>.YEAR-MONTH-DAY.log</code> suffix</td> - </tr> - <tr> - <td>--LogLevel</td> - <td>Info</td> - <td>Defines the logging level and can be either <b>Error</b>, - <b>Info</b>, <b>Warn</b> or <b>Debug</b>. (Case insensitive).</td> - </tr> - <tr> - <td>--StdOutput</td> - <td></td> - <td>Redirected stdout filename. - If named <b>auto</b> then file is created inside <b>LogPath</b> with the - name <b>service-stdout.YEAR-MONTH-DAY.log</b>.</td> - </tr> - <tr> - <td>--StdError</td> - <td></td> - <td>Redirected stderr filename. - If named <b>auto</b> then file is created inside <b>LogPath</b> with the - name <b>service-stderr.YEAR-MONTH-DAY.log</b>.</td> - </tr> - <tr> - <td>--PidFile</td> - <td></td> - <td>Defines the file name for storing the running process id. Actual file is - created in the <b>LogPath</b> directory</td> - </tr> + <tr> + <th>ParameterName</th> + <th>Default</th> + <th>Description</th> + </tr> + <tr> + <td>--Description</td> + <td></td> + <td>Service name description (maximum 1024 characters)</td> + </tr> + <tr> + <td>--DisplayName</td> + <td>ServiceName</td> + <td>Service display name</td> + </tr> + <tr> + <td>--Install</td> + <td>procrun.exe //RS//ServiceName</td> + <td>Install image</td> + </tr> + <tr> + <td>--Startup</td> + <td>manual</td> + <td>Service startup mode can be either <b>auto</b> or <b>manual</b></td> + </tr> + <tr> + <td>++DependsOn</td> + <td></td> + <td>List of services that this service depend on. Dependent services are + separated using either <b>#</b> or <b>;</b> characters</td> + </tr> + <tr> + <td>++Environment</td> + <td></td> + <td>List of environment variables that will be provided to the service + in the form <b>key=value</b>. They are separated using either + <b>#</b> or <b>;</b> characters. If you need to use either the + <b>#</b> or <b>;</b> character within a value then the entire value + must be enclosed inside single quotes.</td> + </tr> + <tr> + <td>--User</td> + <td></td> + <td>User account used for running executable. It is used only for + StartMode <b>java</b> or <b>exe</b> and enables running applications + as service under account without LogonAsService privilege.</td> + </tr> + <tr> + <td>--Password</td> + <td></td> + <td>Password for user account set by --User parameter</td> + </tr> + <tr> + <td>--ServiceUser</td> + <td></td> + <td>Specifies the name of the account under which the service should + run. Use an account name in the form + <code>DomainName\UserName</code>. The service process will be logged + on as this user. if the account belongs to the built-in domain, you + can specify <code>.\UserName</code>. Note that the Service Control + Manager does not accept localised forms of the standard names so to + use them you need to specify <code>NT Authority\LocalService</code>, + <code>NT Authority\NetworkService</code> or <code>LocalSystem</code> + as appropriate.</td> + </tr> + <tr> + <td>--ServicePassword</td> + <td></td> + <td>Password for user account set by --ServiceUser parameter</td> + </tr> + <tr> + <td>--LibraryPath</td> + <td></td> + <td>Directory added to the search path used to locate the DLLs for the + JVM. This directory is added both in front of the <code>PATH</code> + environment variable and as a parameter to the + <code>SetDLLDirectory</code> function.</td> + </tr> + <tr> + <td>--JavaHome</td> + <td>JAVA_HOME</td> + <td>Set a different JAVA_HOME than defined by JAVA_HOME environment + variable</td> + </tr> + <tr> + <td>--Jvm</td> + <td>auto</td> + <td>Use either <b>auto</b> (i.e. find the JVM from the Windows registry) + or specify the full path to the <b>jvm.dll</b>. + You can use the environment variable expansion here.</td> + </tr> + <tr> + <td>++JvmOptions</td> + <td>-Xrs</td> + <td>List of options in the form of <b>-D</b> or <b>-X</b> that will be + passed to the JVM. The options are separated using either + <b>#</b> or <b>;</b> characters. If you need to embed either <b>#</b> or + <b>;</b> characters, put them inside single quotes. (Not used in + <b>exe</b> mode.)</td> + </tr> + <tr> + <td>++JvmOptions9</td> + <td></td> + <td>List of options in the form of <b>-D</b> or <b>-X</b> that will be + passed to the JVM when running on Java 9 or later. The options are + separated using either <b>#</b> or <b>;</b> characters. If you need + to embed either <b>#</b> or <b>;</b> characters, put them inside + single quotes. (Not used in <b>exe</b> mode.)</td> + </tr> + <tr> + <td>--Classpath</td> + <td></td> + <td>Set the Java classpath. (Not used in <b>exe</b> mode.)</td> + </tr> + <tr> + <td>--JvmMs</td> + <td></td> + <td>Initial memory pool size in MB. (Not used in <b>exe</b> mode.)</td> + </tr> + <tr> + <td>--JvmMx</td> + <td></td> + <td>Maximum memory pool size in MB. (Not used in <b>exe</b> mode.)</td> + </tr> + <tr> + <td>--JvmSs</td> + <td></td> + <td>Thread stack size in KB. (Not used in <b>exe</b> mode.)</td> + </tr> + <tr> + <td>--StartMode</td> + <td></td> + <td>One of <b>jvm</b>, <b>Java</b> or <b>exe</b>. The modes are: + <ul> + <li>jvm - start Java in-process. Depends on jvm.dll, see + <b>--Jvm</b>.</li> + <li>Java - same as exe, but automatically uses the default Java + executable, i.e. %JAVA_HOME%\bin\java.exe. Make sure JAVA_HOME + is set correctly, or use --JavaHome to provide the correct + location. If neither is set, procrun will try to find the + default JDK (not JRE) from the Windows registry.</li> + <li>exe - run the image as a separate process</li> + </ul> + </td> + </tr> + <tr> + <td>--StartImage</td> + <td></td> + <td>Executable that will be run. Only applies to <b>exe</b> mode.</td> + </tr> + <tr> + <td>--StartPath</td> + <td></td> + <td>Working path for the start image executable.</td> + </tr> + <tr> + <td>--StartClass</td> + <td>Main</td> + <td>Class that contains the startup method. Applies to the <b>jvm</b> and + <b>Java</b> modes. (Not used in <b>exe</b> mode.) </td> + </tr> + <tr> + <td>--StartMethod</td> + <td>main</td> + <td>Method name if differs then main</td> + </tr> + <tr> + <td>++StartParams</td> + <td></td> + <td>List of parameters that will be passed to either StartImage or + StartClass. Parameters are separated using either <b>#</b> or + <b>;</b> character.</td> + </tr> + <tr> + <td>--StopMode</td> + <td></td> + <td>One of <b>jvm</b>, <b>Java</b> or <b>exe</b>. See <b>--StartMode</b> + for further details. </td> + </tr> + <tr> + <td>--StopImage</td> + <td></td> + <td>Executable that will be run on Stop service signal. Only applies to + <b>exe</b> mode.</td> + </tr> + <tr> + <td>--StopPath</td> + <td></td> + <td>Working path for the stop image executable. Does not apply to + <b>jvm</b> mode.</td> + </tr> + <tr> + <td>--StopClass</td> + <td>Main</td> + <td>Class that will be used on Stop service signal. Applies to the + <b>jvm</b> and <b>Java</b> modes. </td> + </tr> + <tr> + <td>--StopMethod</td> + <td>main</td> + <td>Method name if differs then main</td> + </tr> + <tr> + <td>--StopParams</td> + <td></td> + <td>List of parameters that will be passed to either StopImage or + StopClass. Parameters are separated using either <b>#</b> or + <b>;</b> character.</td> + </tr> + <tr> + <td>++StopTimeout</td> + <td>No Timeout</td> + <td>Defines the timeout in seconds that procrun waits for service to + exit gracefully.</td> + </tr> + <tr> + <td>--LogPath</td> + <td>%SystemRoot%\System32\LogFiles\Apache</td> + <td>Defines the path for logging. Creates the directory if + necessary.</td> + </tr> + <tr> + <td>--LogPrefix</td> + <td>commons-daemon</td> + <td>Defines the service log filename prefix. The log file is created in + the LogPath directory with <code>.YEAR-MONTH-DAY.log</code> + suffix</td> + </tr> + <tr> + <td>--LogLevel</td> + <td>Info</td> + <td>Defines the logging level and can be either <b>Error</b>, + <b>Info</b>, <b>Warn</b> or <b>Debug</b>. (Case insensitive).</td> + </tr> + <tr> + <td>--LogJniMessages</td> + <td>0</td> + <td>Set this non-zero (e.g. 1) to capture JVM jni debug messages in the + procrun log file. Is not needed if stdout/stderr redirection is + being used. Only applies to jvm mode.</td> + </tr> + <tr> + <td>--StdOutput</td> + <td></td> + <td>Redirected stdout filename. + If named <b>auto</b> then file is created inside <b>LogPath</b> with + the name <b>service-stdout.YEAR-MONTH-DAY.log</b>.</td> + </tr> + <tr> + <td>--StdError</td> + <td></td> + <td>Redirected stderr filename. + If named <b>auto</b> then file is created inside <b>LogPath</b> with + the name <b>service-stderr.YEAR-MONTH-DAY.log</b>.</td> + </tr> + <tr> + <td>--PidFile</td> + <td></td> + <td>Defines the file name for storing the running process id. Actual + file is created in the <b>LogPath</b> directory</td> + </tr> </table> - + </subsection> </section> + <section name="Installing services"> <p> The safest way to manually install the service is to use the provided @@ -376,7 +474,7 @@ option.</p> C:\> service.bat install MyService --rename</source> <p> -If using tomcat<version-major/>.exe, you need to use the <b>//IS//</b> parameter.</p> +If using tomcat<version-major/>.exe, you need to use the <b>//IS</b> parameter.</p> <source>Install the service named 'Tomcat<version-major/>' C:\> tomcat<version-major/> //IS//Tomcat<version-major/> --DisplayName="Apache Tomcat <version-major/>" ^ @@ -388,7 +486,7 @@ C:\> tomcat<version-major/> //IS//Tomcat<version-major/> --DisplayName="Apache T </section> <section name="Updating services"> <p> -To update the service parameters, you need to use the <b>//US//</b> parameter. +To update the service parameters, you need to use the <b>//US</b> parameter. </p> <source>Update the service named 'Tomcat<version-major/>' @@ -405,7 +503,7 @@ C:\> tomcat<version-major/> //US//MyService --Description="Apache Tomcat Server </section> <section name="Removing services"> <p> -To remove the service, you need to use the <b>//DS//</b> parameter.<br/> +To remove the service, you need to use the <b>//DS</b> parameter.<br/> If the service is running it will be stopped and then deleted.</p> <source>Remove the service named 'Tomcat<version-major/>' @@ -420,7 +518,7 @@ C:\> tomcat<version-major/> //DS//MyService</source> </section> <section name="Debugging services"> <p> -To run the service in console mode, you need to use the <b>//TS//</b> parameter. +To run the service in console mode, you need to use the <b>//TS</b> parameter. The service shutdown can be initiated by pressing <b>CTRL+C</b> or <b>CTRL+BREAK</b>. If you rename the tomcat<version-major/>.exe to testservice.exe then you can just execute the --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org