diff --git a/jetty-documentation/src/main/asciidoc/administration/runner/jetty-runner.adoc b/jetty-documentation/src/main/asciidoc/administration/runner/jetty-runner.adoc index 2843a1dd76e..c51fe23d768 100644 --- a/jetty-documentation/src/main/asciidoc/administration/runner/jetty-runner.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/runner/jetty-runner.adoc @@ -200,7 +200,7 @@ To link:#how-to-configure-connectors[configure a https connector], use a Jetty x .... ===== Configuring Stop -You can configure a port number for jetty to listen on for a stop command, so you are able to stop it from a different terminal. +You can configure a port number for Jetty to listen on for a stop command, so you are able to stop it from a different terminal. This requires the use of a "secret" key, to prevent malicious or accidental termination. Use the `--stop-port` and `--stop-key` (or `-DSTOP.PORT=` and `-DSTOP.KEY=`, respectively) parameters as arguments to the `jetty-runner`: diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/start-jar.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/start-jar.adoc index f98ab2c6e60..6d66e389cbd 100644 --- a/jetty-documentation/src/main/asciidoc/administration/startup/start-jar.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/startup/start-jar.adoc @@ -208,17 +208,40 @@ The port to use to stop the running Jetty server. This is an internal port, opened on localhost, used solely for stopping the running Jetty server. Choose a port that you do not use to serve web traffic. + -Required for --stop to function. +Required for `--stop` to function. STOP.KEY=;; The passphrase defined to stop the server. + -Required for --stop to function. +Required for `--stop` to function. STOP.WAIT=;; The time (in seconds) to wait for confirmation that the running Jetty server has stopped. If not specified, the stopper waits indefinitely for the server to stop. + If the time specified elapses, without a confirmation of server stop, then the `--stop` command exits with a non-zero return code. +You can configure a port number for Jetty to listen on for a stop command, so you are able to stop it from a different terminal. +This requires the use of a "secret" key, to prevent malicious or accidental termination. +Use the `STOP.PORT` and `STOP.KEY` (or `-DSTOP.PORT=` and `-DSTOP.KEY=`, respectively, which will set these as system parameters) parameters as arguments to the `start.jar`: + +[source, screen, subs="{sub-order}"] +.... +> java -jar ${JETTY_HOME}/start.jar STOP.PORT=1234 STOP.KEY=secretpassword +.... + +Then, to stop Jetty from a different terminal, you need to supply this port and key information. +You can either use a copy of the Jetty distribution, the link:#jetty-maven-plugin[jetty-maven-plugin], the link:#jetty-ant[jetty-ant plugin], or a custom class to accomplish this. +Here's how to use the Jetty distribution, leveraging `start.jar`, to perform a stop: + +[source, screen, subs="{sub-order}"] +.... +> java -jar start.jar STOP.PORT=8181 STOP.KEY=abc123 --stop +.... + +____ +[NOTE] +To perform a graceful shutdown of Jetty, the `stats` link:#startup-modules[module] *must* be enabled. +____ + ===== Advanced Commands --lib=::