Issue #7299 - Enabling the logging-logback module prevents eclipse re…

…mote debugging.

Added documentation as discussed in the issue.

Signed-off-by: Simone Bordet <[email protected]>

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
 

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[]

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

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].