The "How do I configure Tomcat to support remote debugging?" section of the Tomcat Developing FAQ at https://cwiki.apache.org/confluence/display/TOMCAT/Developing?show-miniview#Developing-Debugging contains the following item: > If you are using shell scripts to start Tomcat, start it with the following command: > catalina jpda start > [...] This case visibly refers to *custom* shell scripts. Unfortunately, employees in my organization appear to have (pretty much) followed that advice even though we are using vendor-provided shell scripts (those shipped by Tomcat), which means we effectively modified code that doesn't belong to us (a Bad Idea™). Colleagues modified the last line of startup.sh adding "jpda", meaning our changes are lost at least every time the Tomcat package is upgraded: https://github.com/apache/tomcat/blob/483c3d0adde00a5c6569bd75b2901dc6786d1663/bin/startup.sh#L60 Considering that our case is surely far from rare, it would be important to: 1. at least indicate in the existing item that it treats *custom* shell scripts only 2. ideally, add an item covering the case of official (distributed) shell scripts
Those instructions apply to both custom scripts that call catalina.[sh|bat] and using the standard catalina.[sh|bat] script directly. The catalina.[sh|bat] scripts both document in the initial comment block how to customise the start-up without editing the standard Tomcat scripts. If you need help customising your Tomcat start scripts then the users mailing list is the place to seek help: https://tomcat.apache.org/lists.html
Thanks Mark, The initial comment block in catalina.[sh|bat] scripts unfortunately only covers environment variables, not modifying the startup command. You are however right that fully treating this in catalina.[sh|bat] scripts too would be even better.
setenv.[sh|bat] can also be used to configure debugging. Again, the users list is the place to seek help with this, not Bugzilla.
Mark, this is a bug report combined with an enhancement request, not a support request. If the point you're trying to make is that debugging can be enabled using setenv.sh, you may be the right, but the issue(s) tracked here remain. setenv is *not* designed to start Tomcat with catalina jpda start. We cannot expect users to ask for advice to do such a basic thing, and then follow advice which goes against documentation. Also, thank you for waiting until resolution before marking issues as resolved.
The original bug report is invalid. The wiki covers starting Tomcat with debugging for users of standard scripts (use catalina.[sh|bat] jpda start) and for users with custom scripts (call catalina.[sh|bat] or provide the appropriate JVM options). setenv.[sh|bat] is the standard place for user customisations and options. Yet again, the users list is the place to seek help with that. Always starting Tomcat under debugging is a rare requirement. Even if the FAQ did need updating (it doesn't), such a configuration would not be appropriate in a list *frequently* asked questions. Please use the users list if you require further help or advice. Please do not re-open this report aagin.
(In reply to Mark Thomas from comment #5) > The original bug report is invalid. The wiki covers starting Tomcat with > debugging for users of standard scripts (use catalina.[sh|bat] jpda start) > and for users with custom scripts (call catalina.[sh|bat] or provide the > appropriate JVM options). I'm afraid there's a misunderstanding. The entry is about *configuring* Tomcat to support remote debugging. Not just about *starting* it with remote debugging enabled. > [...] > > Always starting Tomcat under debugging is a rare requirement. It's not; most of our Tomcat servers are setup this way. > Even if the FAQ did need updating (it doesn't), such a configuration would not be > appropriate in a list *frequently* asked questions. That FAQ contains the question "How do I start hacking Tomcat in Eclipse?" In fact, it's even the first question in that FAQ. No matter how you define "frequent", I hope you'll agree there are many more people configuring Tomcat for remote debugging than hacking Tomcat in Eclipse.
I'm a little confused. Tomcat ships with a shell script, catalina.sh, which can be used as documented to start Tomcat in debugging (JPDA) mode. This is not a "custom" shell script. There is a script to "start Tomcat", startup.sh, which basically just invokes "catalina.sh start". If you want more control over the startup process, you need to call catalina.sh directly. There is a customization script you can create, setenv.sh, which will set environment variables before launching your JVM. This is *not* a part of the files shipped by Tomcat and therefore the responsibility of the operator. Invoking "catalina.sh jpda start" is basically the same thing as invoking "catalina.sh start" with some environment variables set. Specifically, "jpda" does this: if [ "$1" = "jpda" ] ; then if [ -z "$JPDA_TRANSPORT" ]; then JPDA_TRANSPORT="dt_socket" fi if [ -z "$JPDA_ADDRESS" ]; then JPDA_ADDRESS="localhost:8000" fi if [ -z "$JPDA_SUSPEND" ]; then JPDA_SUSPEND="n" fi if [ -z "$JPDA_OPTS" ]; then JPDA_OPTS="-agentlib:jdwp=transport=$JPDA_TRANSPORT,address=$JPDA_ADDRESS,server=y,suspend=$JPDA_SUSPEND" fi CATALINA_OPTS="$JPDA_OPTS $CATALINA_OPTS" shift fi So if you *always* want to use JPDA mode, then you have two options: 1. Always run "catalina.sh jpda start" (perhaps in some script that you maintain, no need to edit Tomcat-provided scripts) 2. Create $CATALINA_BASE/bin/setenv.sh and set the appropriate $CATALINA_OPTS such as "-agentlib:..." and run "catalina.sh start" (or "startup.sh", which will do the same thing). Nothing above requires you to modify Tomcat-provided scripts. Everything is documented. In your opinion, how can the documentation be improved -- specifically?
Thank you Christopher, You are entirely right that catalina.sh is not a "custom" shell script. It is what this ticket calls a "distributed shell script". The documentation can be improved in a number of ways: 1. By fixing terminology, as "the following options" are not actually JVM options, but rather option values. 2. By generalizing the required option values, as address does not need to be set to 8000. 3. By fixing and clarifying item #1: 1. Fixing the command (Tomcat does not create a "catalina" command by default.) 2. Not claiming that "catalina jpda start" sets the "above" option values, since it actually indeed sets: 1. JPDA_ADDRESS="localhost:8000" 2. the Java 5+ option (agentlib:jdwp). 3. Fixing the end or making it intelligible. This can probably be done by substituting... > The above mentioned options can be provided by setting certain environment variables. ...with: > The values of the agentlib:jdwp options can be customized by setting certain environment variables. 4. Explaining what you just explained, i.e. that startup.sh basically just invokes "catalina.sh start", so that for more control over the startup process, you need to call catalina.sh directly. 5. Explaining how 3.4 can be achieved in typical systems. Most importantly, those (like Red Hat Enterprise Linux) where Tomcat is started by systemd. That is explaining to modify the value of the ExecStart option in the service unit file.