diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-configure.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-configure.adoc index e711d9018eae..39931adfaf12 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-configure.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-configure.adoc @@ -24,7 +24,7 @@ Within the Jetty start mechanism, the source of configurations is layered in thi [[og-start-configure-enable]] ===== Enabling Modules -You can enable Jetty modules with the `--add-modules` command: +You can enable Jetty modules persistently across restarts with the `--add-modules` command: ---- $ java -jar $JETTY_HOME/start.jar --add-modules=server,http @@ -108,6 +108,29 @@ jetty.http.port=9876 When Jetty is started (or re-started) this configuration is applied and Jetty will listen for clear-text HTTP/1.1 on port `9876`. +[[og-start-configure-enable-command-line]] +===== Enabling Modules on Command Line + +You can also enable a module transiently, only for the current execution of the `java -jar $JETTY_HOME/start.jar` command. + +If you have an empty `$JETTY_BASE`, the following command enables the `server` and `http` modules, but does not create any `+$JETTY_BASE/start.d/*.ini+` files. + +---- +$ java -jar $JETTY_HOME/start.jar --module=server,http +---- + +Since there are no `+$JETTY_BASE/start.d/*.ini+` files, you can only customize the properties via the command line, for example: + +---- +$ java -jar $JETTY_HOME/start.jar --module=server,http jetty.http.port=9876 +---- + +Enabling modules on the command line is useful to verify that the modules work as expected, or to try different configurations. + +NOTE: It is possible to enable some module persistently via `--add-modules` and some other module transiently via `--module`. + +Remember that once the current execution terminates, the modules enabled transiently on the command line via `--module` and their configuration are not saved and will not be enabled on the next execution (unless you specify them again on the command line). + [[og-start-configure-custom-module]] ===== Adding Your Own Modules diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/chapter.adoc index d46a4a94eb91..59124b3dbbe2 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/chapter.adoc @@ -35,3 +35,4 @@ IMPORTANT: Make sure you read about how to secure the access to Jetty when using include::troubleshooting-dump.adoc[] include::troubleshooting-logging.adoc[] +include::troubleshooting-debugging.adoc[] diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/remote-debug.mod b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/remote-debug.mod new file mode 100644 index 000000000000..9cae360e33f5 --- /dev/null +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/remote-debug.mod @@ -0,0 +1,5 @@ +[description] +Enables remote debugging + +[exec] +-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/troubleshooting-debugging.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/troubleshooting-debugging.adoc new file mode 100644 index 000000000000..5257adb8a6fc --- /dev/null +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/troubleshooting-debugging.adoc @@ -0,0 +1,74 @@ +// +// ======================================================================== +// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others. +// +// This program and the accompanying materials are made available under the +// terms of the Eclipse Public License v. 2.0 which is available at +// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0 +// which is available at https://www.apache.org/licenses/LICENSE-2.0. +// +// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +// ======================================================================== +// + +[[og-troubleshooting-debugging]] +==== Remote Debugging + +The Java Virtual Machines allows remote processes on different hosts to connect for debugging purposes, by using specific command line options. + +[CAUTION] +==== +While it is possible to enable remote debugging on a Jetty server, it is typically not recommended for security and performance reasons. +Only enable remote debugging on a Jetty server as a last resort to troubleshoot issues that could not be troubleshot otherwise. +==== + +You can easily create a custom Jetty module (see xref:og-modules-custom[this section]) with the following content: + +.remote-debug.mod +---- +include::remote-debug.mod[] +---- + +The `[exec]` directive (documented xref:og-modules-directive-exec[here]) is necessary to pass the `-agentlib:jdwp` JVM option to the forked JVM that runs Jetty, so that you can attach with a debugger. + +[NOTE] +==== +The `address` parameter of the `-agentlib:jdwp` command line option specifies the network address and port the Jetty JVM listens on for remote debugging. + +Please refer to the link:https://docs.oracle.com/en/java/javase/17/docs/specs/jpda/conninv.html[Java Debug Wire Protocol documentation] for additional information about the `-agentlib:jdwp` command line option and its parameters. +==== + +You can now enable the `remote-debug` Jetty module with the following command issued from the `$JETTY_BASE` directory: + +---- +$ java -jar $JETTY_HOME/start.jar --add-modules=server,remote-debug +---- + +The command above minimally adds a Jetty server without connectors (via the `server` Jetty module) and the `remote-debug` Jetty module, and produces the following `$JETTY_BASE` directory structure: + +[source,subs=normal] +---- +$JETTY_BASE +├── modules +│ └── remote-debug.mod +├── resources +│ └── jetty-logging.properties +└── start.d + ├── ##remote-debug.ini## + └── server.ini +---- + +You can easily disable the `remote-debug` Jetty module as explained in xref:og-start-configure-disable[this section]. + +Alternatively, you can enable the `remote-debug` module on the command line, as explained in xref:og-start-configure-enable-command-line[this section]. + +Starting the Jetty server with the `remote-debug` module enabled yields: + +[source,subs=quotes,options=nowrap] +---- +include::jetty[setupModules="src/main/asciidoc/operations-guide/troubleshooting/remote-debug.mod",setupArgs="--add-modules=server,remote-debug",highlight="5005"] +---- + +Note how the JVM is listening on port `5005` to allow remote debuggers to connect. + +If you want to avoid to fork a second JVM to pass the `-agentlib:jdwp` JVM option, please read xref:og-start-configure-dry-run[this section].