tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Tomcat Wiki] Update of "HowTo" by KonstantinKolinko
Date Sun, 31 Jul 2011 23:11:51 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Tomcat Wiki" for change notification.

The "HowTo" page has been changed by KonstantinKolinko:
http://wiki.apache.org/tomcat/HowTo?action=diff&rev1=108&rev2=109

Comment:
Roughly organize Q&A by categories: Meta, Installation, Configuration, Programming, Troubleshooting.

  <<TableOfContents>>
  
  ----
+ = Meta =
  
  == How do I add a question to this page? ==
  Anyone may edit this page to add their own content. That is why this page is part of a Wiki and not a hardcoded static file in the FAQ.
  
  However, ''do not'' add questions without answers to this page. If you have a question about how to do something in Tomcat which has not been addressed yet, ask the [[http://tomcat.apache.org/lists.html#tomcat-users|tomcat-user list]]. Once you've figured out how to fix your problem, come back and update the Wiki to allow the rest of us to benefit from what you've learned!
  
+ == How do I contribute to Tomcat's documentation? ==
+ - Download the source bundle or grab the source XML file from [[http://tomcat.apache.org/svn.html|Subversion repository]].  The docs are in the webapps/docs subdirectory.  They are in XML format and get processed into the HTML documentation as part of the Tomcat release.
+ 
+ - Edit the documentation XML file(s) as you wish.  The xdocs format is self-explanatory: use normal HTML markup, and add <section> or <subsection> tags as you see fit.  Look at the existing docs as examples.  Make sure you use valid XML markup.
+ 
+ - Open a Bugzilla enhancement item with the explanation of your enhancements, and attach a {{{svn diff}}} or {{{diff -u}}} format of your patch.  We will evaluate and commit your patch as needed.  Note that the Tomcat web site is updated with every release, so that documentation changes will not be visible until next Tomcat release.
+ 
+ - If you're interested in previewing your changes, you will need to follow the directions for building Tomcat yourself.  The docs will be generated in the webapps/docs directory just like with any normal Tomcat distributions.
+ 
+ - Documentation for current (unreleased) versions of Tomcat 6 and Tomcat 7 is published by ASF Buildbot. See links on the [[http://tomcat.apache.org/ci.html|buildbot]] page on Apache Tomcat web site.
+ 
+ - If you're not familiar with how to grab files from Subversion, see http://www.apache.org/dev/contributors.html.
+ 
+ 
+ = Installation =
+ 
  == How do I set up and run Tomcat on Macintosh OS X? ==
  See [[TomcatOnMacOS]]
  
  == How do I set up and run Tomcat on Solaris 10? ==
  See TomcatOnSolaris10
  
+ 
+ == How do I set up another tomcat service on Windows, sharing the same Tomcat Home ? ==
+ This script sets up a a tomcat base directory and calls tomcat5.exe to create a windows service which will use the tomcat home given for the binaries and tomcat base you create See TomcatCreateWindowsService
+ 
+ == How do I install Tomcat as a service under Unix? ==
+ Create a shell program to start Tomcat automatically.  Each UNIX varies in how it starts up automatic services, but there are two main variants:
+ 
+ BSD::In a typical BSD system, there are a series of start up scripts in {{{/etc}}} starting with {{{rc.}}}.  Look for, or create, a file called {{{/etc/rc.local}}} and enter the appropriate instructions to start up Tomcat there as a shell script.
+ 
+ System V::In a typical UNIX System V setup, there is a directory containing startup scripts, and other directories which contain links to these startup scripts.  Create the appropriate startup script for your setup, then create the appropriate links.
+ 
+ For more information on each, check your system documentation.
+ 
+  . (!) It also makes a lot of sense to use the JavaServiceWrapper.
+ 
+ 
+ == How to run Tomcat without root privileges? ==
+ The best way is to use jsvc, available as part of the [[http://commons.apache.org/daemon/jsvc.html|commons-daemon]] project.
+ 
+ ----
+ Is there a way to allow normal user(non-root) to start/stop the tomcat server. Tried assigning permission, did not work. Read thru some articles, stated that only root has permission to port below 1025. How can i allow a non-root user to do so ? thks in adv. :)
+ 
+ - malathi ranjit singh
+ 
+ ----
+ One way is to put Apache httpd with mod_jk before your Tomcat servers, and use ports >=1024 in the Tomcat(s). Since we do it that way, it's the only way I know.
+ 
+ BTW, you should read the 1st howto. ;)
+ 
+ Another method is to use SetUID scripts (assuming you have the capability) to do this.  Here's how I do it.
+ 
+ Create a file called foo.c with this content (replace "/path/startupscript" with the tomcat startup script):
+ 
+ #include <unistd.h> #include <stdlib.h>
+ 
+ int main( int argc, char *argv[] ) {
+ 
+  . if ( setuid( 0 ) != 0 ) perror( "setuid() error" ); printf( "Starting ${APPLICATION}\n" ); execl( "/bin/sh", "sh", "/path/startupscript", 0 ); return 1;
+ 
+ }
+ 
+ Run the following as root (replacing tmp with whatever you want the startup script to be and replacing XXXXX with whatever group you want to be able to start and stop tomcat:
+ 
+ gcc tmp.c -o tmp chown root:XXXXX tmp chmod ugo-rwx tmp chmod u+rwxs,g+rx tmp
+ 
+ Now members of the tomcat group should be able to start and stop tomcat.  One caveat though, you need to ensure that that your tomcat startup script is not writable by anyone other than root, otherwise your users will be able to insert commands into the script and have them run as root (very big security hole).
+ 
+ ----
+ - A another way is to use Iptables to redirect Port 80 and 443 to user ports (>1024)
+ 
+ * /sbin/iptables -A FORWARD -p tcp --destination-port 443 -j ACCEPT
+ 
+ * /sbin/iptables -t nat -A PREROUTING -j REDIRECT -p tcp --destination-port 443 --to-ports 8443
+ 
+ * /sbin/iptables -A FORWARD -p tcp --destination-port 80 -j ACCEPT
+ 
+ * /sbin/iptables -t nat -A PREROUTING -j REDIRECT -p tcp --destination-port 80 --to-ports 8080
+ 
+ /sbin/iptables-save or /etc/init.d/iptables save
+ 
+ ----
+ BSD-based Unix systems such as Mac OS X use a tool similar to iptables, called ipfw (for Internet Protocol Fire Wall). This tool is similar in that it watches all network packets go by, and can apply rules to affect those packets, such as "port-forwarding" from port 80 to some other port such as Tomcat's default 8080. The syntax of the rules is different than iptables, but the same idea. For more info, google and read the man page. Here is one possible rule to do the port-forwarding:
+ 
+ {{{
+ sudo ipfw add 100 fwd 127.0.0.1,8080 tcp from any to any 80 in
+ }}}
+ 
+ 
+ 
+ = Configuration =
+ 
  == How do I set up multiple sites sharing the same war application/war file? ==
  See CreateVirtualHosts
- 
- == How do call tomcat ant tasks to deploy webapps? ==
- See AntDeploy
- 
- == How do I load a properties file? ==
- Here are the three most popular ways::
- 
-  * Use a classloader's getResource to get an url to the properties file and load it into the Properties. The properties file must be located within the webapp classpath (i.e. either {{{WEB-INF/classes/...}}} or in a jar in {{{WEB-INF/lib/}}}).
- 
- A challenge is to get the classloader when you are in a static initializer:
- 
- {{{
-   public class Config {
-      private static java.util.Properties prop = new java.util.Properties();
-      private static loadProperties() {
-           // get class loader
-           ClassLoader loader = Config.class.getClassLoader();
-           if(loader==null)
-             loader = ClassLoader.getSystemClassLoader();
- 
-           // assuming you want to load application.properties located in WEB-INF/classes/conf/
-           String propFile = "conf/application.properties";
-           java.net.URL url = loader.getResource(propFile);
-           try{prop.load(url.openStream());}catch(Exception e){System.err.println("Could not load configuration file: " + propFile);}
-      }
- 
-      //....
-      // add your methods here. prop is filled with the content of conf/application.properties
- 
-      // load the properties when class is accessed
-      static {
-         loadProperties();
-      }
-   }
- }}}
- This method even works in a standalone java application. So it is my preferred way. (see also [[http://knowhow.amazers.net/space/dev/java+tips/Loading+properties+in+a+web+application|this article]])
- 
-  * Use a `ResourceBundle`. See the Java docs for the specifics of how the `ResourceBundle` class works. Using this method, the properties file must go into the `WEB-INF/classes` directory or in a jar file contained in the `WEB-INF/lib` directory.
- 
-  * Another way is to use the method `getResourceAsStream()` from the `ServletContext` class. This allows you update the file without having to reload the webapp as required by the first method. Here is an example code snippet, without any error trapping:
- 
- {{{
- // Assuming you are in a Servlet extending HttpServlet
- // This will look for a file called "/more/cowbell.properties" relative
- // to your servlet Root Context
- InputStream is = getServletContext().getResourceAsStream("/more/cowbell.properties");
- Properties  p  = new Properties();
- p.load(is);
- is.close();
- }}}
  
  == How do I log requests ? ==
  See AccessLogValve
@@ -110, +148 @@

  == How do I configure Tomcat to work with IIS and NTLM? ==
  See [[TomcatNTLM]]
  
- == Tomcat crashed! What do I do now? ==
- These steps are in no particular order ...
- 
-  1. Read the Tomcat FAQ
-  1. Read the Tomcat RELEASE NOTES - there is something about Linux in it
-  1. First look at the stack traces. I hope a stack trace was produced before the failure aborted the JVM process. After you get a few stack traces, see if a pattern appears. Trace back to source code if needed.
-  1. Patch (or ''unpatch''!) the operating system as needed.
-  1. Patch (or ''unpatch''!) the JVM (Java Virtual Machine).
-  1. Linux Problem? - read the RELEASE NOTES!
-  1. Look at commercial vendor support for other servlet engines. Sometimes the problem is universal regardless of servlet engine and may be a JVM/OS/application code issue
-  1. Search Google for web pages - maybe someone else had this problem. I'll bet they did.
-  1. Search Google news groups
-  1. If the JVM is from a commercial vendor, (eg: IBM, HP) check their release notes and news groups
-  1. Using a database? Make sure JDBC type 4 drivers are used. Check their release notes.
-  1. Tweak JVM memory parameters. Setting memory too high can be as bad as having memory too low. If your memory settings are set too high, Java 1.3 JVMs may freeze while waiting for the entire garbage collection to finish. Also if the JVM has too much memory, if may be starving other resources on the machine which are needed which may be causing unforeseen exceptions. In a nutshell, throwing more memory doesn't always solve the problem!
-  1. Turn off the Java JIT compiler. See the Java Docs on how to do this.
- 
- == How do I share sessions across web apps? ==
- You cannot share sessions directly across web apps, as that would be a violation of the Servlet Specification.  There are workarounds, including using a singleton class loaded from the common classloader repository to hold shared information, or putting some of this shared information in a database or another data store.  Some of these approaches have been discussed on the [[http://tomcat.apache.org/lists.html#tomcat-users|tomcat-user mailing list]], whose archives you should search for more information.
- 
- Sharing sessions across containers for clustering or replication purposes is a different matter altogether.
- 
- == I'm encountering classloader problems when using JNI under Tomcat ==
- The important thing to know about using JNI under Tomcat is that one cannot place the native libraries OR their JNI interfaces under the WEB-INF/lib or WEB-INF/classes directories of a web application and expect to be able to reload the webapp without restarting the server. The class that calls System.loadLibrary(String) must be loaded by a classloader that is not affected by reloading the web application itself.
- 
- Thus, if you have JNI code that follows the convention of including a static initilaizer like this:
- 
- {{{
- class FooWrapper {
-     static {
-         System.loadLibrary("foo");
-     }
- 
-     native void doFoo();
-   }
- }}}
- then both this class and the shared library should be placed in the `$CATALINA_HOME/shared/lib` directory.
- 
- ''Note that under Windows, you'll also need to make sure that the library is in the {{{java.library.path}}}.  Either add {{{%CATALINA_HOME%\shared\lib}}} to your Windows PATH environment variable, or place the DLL files in another location that is currently on the {{{java.library.path}}}.  There may be a similar requirement for UNIX based system (I haven't checked), in which case you'd also have to add {{{$CATALINA_HOME/shared/lib}}} to the PATH environment variable.  (Note: I'm not the original author of this entry.)''
- 
- The symptom of this problem that I encountered looked something like this -
- 
- {{{
- java.lang.UnsatisfiedLinkError: Native Library WEB-INF/lib/libfoo.so already loaded in another classloader
-         at java.lang.ClassLoader.loadLibrary0(ClassLoader.java:1525)
- }}}
- If the `UnsatisfiedLinkError` is intermittent, it may be related to Tomcat's default session manager.  It restored previous sessions at startup.  One of those objects may load the JNI library.  Try stopping the Tomcat JVM, deleting the SESSIONS.ser file, then starting Tomcat.  You may consider changing the session persistence manager at this time.
- 
- Note that Tomcat 6.0.14 the $CATALINA_HOME/shared/lib directory does not exist. You will need to add this and you will need to edit $CATALINA_HOME/conf/catalina.properties so that the shared.loader line looks like this shared.loader=$CATALINA_HOME/shared/lib
- 
- == How can I access members of a custom Realm or Principal? ==
- When you create a custom subclass of `RealmBase` or `GenericPrincipal` and attempt to use those classes in your webapp code, you'll probably have problems with `ClassCastException`.  This is because the instance returned by `request.getUserPrincipal()` is of a class loaded by the server's classloader, and you are trying to access it through you webapp's classloader.  While the classes maybe otherwise exactly the same, different (sibling) classloaders makes them different classes.
- 
- This assumes you created a `MyPrincipal` class, and put in Tomcat's server/classes (or lib) directory, as well as in your webapp's webinf/classes (or lib) directory.  Normally, you would put custom realm and principal classes in the server directory because they depend on other classes there.
- 
- Here's what you would like to do, but it throws `ClassCastException`:
- 
- {{{
- MyPrincipal p = request.getUserPrincipal();
- String emailAddress = p.getEmailAddress();
- }}}
- Here are 4 ways you might get around the classloader boundary:
- 
- 1) ''Reflection''
- 
- {{{
- Principal p = request.getUserPrincipal();
- String emailAddress = p.getClass().getMethod("getEmailAddress", null).invoke(p, null);
- }}}
- 2) ''Move classes to a common classloader''
- 
- You could put your custom classes in a classloader that is common to both the server and your webapp - e.g., either the "common" or bootstrap classloaders.  To do this, however, you would also need to move the classes that your custom classes depend on up to the common classloader, and that seems like a bad idea, because there a many of them and they a core server classes.
- 
- 3) ''Common Interfaces''
- 
- Rather than move the implementing custom classes up, you could define interfaces for your customs classes, and put the interfaces in the common directory.  You're code would look like this:
- 
- {{{
- public interface MyPrincipalInterface extends java.security.Principal {
-   public String getEmailAddress();
- }
- 
- public class MyPrincipal implements MyPrincipalInterface {
- ...
-   public String getEmailAddress() {
-     return emailAddress;
-   }
- }
- 
- public class MyServlet implements Servlet {
-   protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
-     MyPrincipalInterface p = (MyPrincipalInterface)request.getUserPrincipal();
-     String emailAddress = p.getEmailAddress();
- ...
- }
- }}}
- ''Notice that this method gives you pretty much the webapp code you wanted in the first place''
- 
- 4) ''Serializing / Deserializing''
- 
- You might want to try serializing the response of 'request.getUserPrincipal()' and deserialize it to an instance of [webapp]MyPrincipal.
- 
  == Setting up SSL ==
  Threads from the [[http://tomcat.apache.org/lists.html#tomcat-users|tomcat-user list]]
  
@@ -233, +169 @@

  == HowTo SSL Client Authentication with Fallback to FORM Authentication ==
  See [[SSLWithFORMFallback]]
  
- == How do I set up another tomcat service on Windows, sharing the same Tomcat Home ? ==
- This script sets up a a tomcat base directory and calls tomcat5.exe to create a windows service which will use the tomcat home given for the binaries and tomcat base you create See TomcatCreateWindowsService
- 
- == How do I install Tomcat as a service under Unix? ==
- Create a shell program to start Tomcat automatically.  Each UNIX varies in how it starts up automatic services, but there are two main variants:
- 
- BSD::In a typical BSD system, there are a series of start up scripts in {{{/etc}}} starting with {{{rc.}}}.  Look for, or create, a file called {{{/etc/rc.local}}} and enter the appropriate instructions to start up Tomcat there as a shell script.
- 
- System V::In a typical UNIX System V setup, there is a directory containing startup scripts, and other directories which contain links to these startup scripts.  Create the appropriate startup script for your setup, then create the appropriate links.
- 
- For more information on each, check your system documentation.
- 
-  . (!) It also makes a lot of sense to use the JavaServiceWrapper.
- 
- == How do I get direct access to a Tomcat Realm? ==
- Credit: This code is from a post by Yoav Shapira http://www.yoavshapira.com in the user list
- 
- Sometimes access directly into the Tomcat realm object is needed; to do, this the following code can be used.  Be aware, however, that by using this, your application is relying on a Tomcat extension and is therefore non-standard.
- 
- Note that in order for this to work the Context of the web application in question needs to have its privileged attribute set to "true", otherwise web apps do not have access to the Tomcat classes.
- 
- {{{
- Server server = ServerFactory.getServer();
- //Note, this assumes the Container is "Catalina"
- Service service = server.findService("Catalina");
- Engine engine = (Engine) service.getContainer();
- Host host = (Host) engine.findChild(engine.getDefaultHost());
- //Note, this assumes your context is "myContext"
- Context context = (Context) host.findChild("myContext");
- Realm realm = context.getRealm();
- }}}
  == How do I make Tomcat startup faster? ==
  See HowTo/FasterStartUp
- 
- == How do I contribute to Tomcat's documentation? ==
- - Download the source bundle or grab the source XML file from [[http://tomcat.apache.org/svn.html|Subversion repository]].  The docs are in the webapps/docs subdirectory.  They are in XML format and get processed into the HTML documentation as part of the Tomcat release.
- 
- - Edit the documentation XML file(s) as you wish.  The xdocs format is self-explanatory: use normal HTML markup, and add <section> or <subsection> tags as you see fit.  Look at the existing docs as examples.  Make sure you use valid XML markup.
- 
- - Open a Bugzilla enhancement item with the explanation of your enhancements, and attach a {{{svn diff}}} or {{{diff -u}}} format of your patch.  We will evaluate and commit your patch as needed.  Note that the Tomcat web site is updated with every release, so that documentation changes will not be visible until next Tomcat release.
- 
- - If you're interested in previewing your changes, you will need to follow the directions for building Tomcat yourself.  The docs will be generated in the webapps/docs directory just like with any normal Tomcat distributions.
- 
- - Documentation for current (unreleased) versions of Tomcat 6 and Tomcat 7 is published by ASF Buildbot. See links on the [[http://tomcat.apache.org/ci.html|buildbot]] page on Apache Tomcat web site.
- 
- - If you're not familiar with how to grab files from Subversion, see http://www.apache.org/dev/contributors.html.
  
  == How do I override the default home page loaded by Tomcat? ==
  After successfully installing Tomcat, you usually test it by loading http://localhost:8080 . The contents of that page are compiled into the `index_jsp` servlet. The page even warns against modifying the `index.jsp` files for this reason. Luckily, it is quite easy to override that page. Inside {{{$TOMCAT_HOME/conf/web.xml}}} there is a section called `<welcome-file-list>` and it looks like this:
@@ -308, +200 @@

  
  == How do I edit the default JSP home page loaded by Tomcat? ==
  See [[EditDefaultJSPPage]]
- 
- == How do I redirect System.out and System.err to my web page? ==
- I have met a situation where I needed to redirect a portion of standard ouput (`System.out`, STDOUT) and standard error (`System.err`, STDERR) to my web page instead of a log file. An example of such an application is a compiler research platform that our resarch team is putting online for anybody to be able to quickly compile-test their programs on line. Naturally, the compilers dump some of their stuff to STDERR or STDOUT and they are not web application `.jar`. Thus, I needed badly these streams related to the compiler output to be redirected to my web editor interface. Having found no easy instructions on how to do that lead me writing up this quick HOWTO. The HOWTO is based on Servlets, but similar arrangements can be done for JSPs. The below example shows the essentials, with most non-essentials removed.
- 
- {{{
- public class WebEditor
- extends HttpServlet
- {
-  ...
-         public void doGet
-         (
-                 HttpServletRequest poHTTPRequest,
-                 HttpServletResponse poHTTPResponse
-         )
-         throws IOException, ServletException
-         {
-                 poHTTPResponse.setContentType("text/html");
- 
-                 ServletOutputStream out = poHTTPResponse.getOutputStream();
- 
-                 out.println("<html>");
-                 out.println("<body>");
-                 out.println("<head>");
-                 out.println("<title>WebEditor Test $Revision: 1.6 $</title>");
-                 out.println("</head>");
-                 out.println("<body>");
-                 out.println("<h3>WebEditor Test $Revision: 1.6 $</h3>");
-                 out.println("<hr />");
- 
-                 // Backup the streams
-                 PrintStream oStdOutBackup = System.out;
-                 PrintStream oStdErrBackup = System.err;
- 
-                 // Redired STDOUT and STDERR to the ServletOuputStream
-                 System.setOut(new PrintStream(out));
-                 System.setErr(new PrintStream(out));
- 
- 
-                 try
-                 {
-                         // ... call compiler here that produces
-                         // tons of STDOUT/STDERR messages ...
-                 }
-                 catch(Exception e)
-                 {
-                         out.println(e.toString());
-                 }
- 
-                 // Restore original STDOUT and STDERR
-                 System.setOut(oStdOutBackup);
-                 System.setErr(oStdErrBackup);
- 
-                 out.println("<hr />");
-                 out.println("</body>");
-                 out.println("</html>");
-         }
- }
- }}}
- A few caveats arise, as for instance while the `System.out` and `System.err` are redirected as per above, no logging of these is done to files. You will need more legwork to do to make the additional logging. It is important to backup and restore the original streams as the above example does. Also, notice the use of `getOutputStream()`: when this method is called, the `getWriter()` method can no longer be used in the same response object.
- 
- Corrections and comments are most welcome!
- 
- == How to run Tomcat without root privileges? ==
- The best way is to use jsvc, available as part of the [[http://commons.apache.org/daemon/jsvc.html|commons-daemon]] project.
- 
- ----
- Is there a way to allow normal user(non-root) to start/stop the tomcat server. Tried assigning permission, did not work. Read thru some articles, stated that only root has permission to port below 1025. How can i allow a non-root user to do so ? thks in adv. :)
- 
- - malathi ranjit singh
- 
- ----
- One way is to put Apache httpd with mod_jk before your Tomcat servers, and use ports >=1024 in the Tomcat(s). Since we do it that way, it's the only way I know.
- 
- BTW, you should read the 1st howto. ;)
- 
- Another method is to use SetUID scripts (assuming you have the capability) to do this.  Here's how I do it.
- 
- Create a file called foo.c with this content (replace "/path/startupscript" with the tomcat startup script):
- 
- #include <unistd.h> #include <stdlib.h>
- 
- int main( int argc, char *argv[] ) {
- 
-  . if ( setuid( 0 ) != 0 ) perror( "setuid() error" ); printf( "Starting ${APPLICATION}\n" ); execl( "/bin/sh", "sh", "/path/startupscript", 0 ); return 1;
- 
- }
- 
- Run the following as root (replacing tmp with whatever you want the startup script to be and replacing XXXXX with whatever group you want to be able to start and stop tomcat:
- 
- gcc tmp.c -o tmp chown root:XXXXX tmp chmod ugo-rwx tmp chmod u+rwxs,g+rx tmp
- 
- Now members of the tomcat group should be able to start and stop tomcat.  One caveat though, you need to ensure that that your tomcat startup script is not writable by anyone other than root, otherwise your users will be able to insert commands into the script and have them run as root (very big security hole).
- 
- ----
- - A another way is to use Iptables to redirect Port 80 and 443 to user ports (>1024)
- 
- * /sbin/iptables -A FORWARD -p tcp --destination-port 443 -j ACCEPT
- 
- * /sbin/iptables -t nat -A PREROUTING -j REDIRECT -p tcp --destination-port 443 --to-ports 8443
- 
- * /sbin/iptables -A FORWARD -p tcp --destination-port 80 -j ACCEPT
- 
- * /sbin/iptables -t nat -A PREROUTING -j REDIRECT -p tcp --destination-port 80 --to-ports 8080
- 
- /sbin/iptables-save or /etc/init.d/iptables save
- 
- ----
- BSD-based Unix systems such as Mac OS X use a tool similar to iptables, called ipfw (for Internet Protocol Fire Wall). This tool is similar in that it watches all network packets go by, and can apply rules to affect those packets, such as "port-forwarding" from port 80 to some other port such as Tomcat's default 8080. The syntax of the rules is different than iptables, but the same idea. For more info, google and read the man page. Here is one possible rule to do the port-forwarding:
- 
- {{{
- sudo ipfw add 100 fwd 127.0.0.1,8080 tcp from any to any 80 in
- }}}
- == How do I debug a Tomcat application? ==
- There is nothing magical about debugging a Tomcat application. All you need is an IDE and two environment variables.
- 
-  * If you have not already done so begin by creating a new Tomcat context for your application. Navigate to '''TOMCAT_HOME\conf\Catalina\localhost''' and create a new file, say, myapp.xml. This will become part of your url, so to access your app you'll have to type '''http://localhost:8080/myapp'''.
-  * Enter the following in myapp.xml:
- 
- {{{
- <Context docBase="c:/workspace/myapp/WebRoot" />
- }}}
-  . This assumes you have a web application containing WEB-INF in '''c:/workspace/myapp/WebRoot'''
- 
-  * Create two environment variables:
- 
- {{{
- C:\>set JPDA_ADDRESS=1044
- C:\>set JPDA_TRANSPORT=dt_socket
- }}}
-  * Now, you can launch Tomcat with these debug options:
- 
- {{{
- TOMCAT_HOME\bin\>catalina jpda start
- }}}
-  * Use your IDE to connect to Tomcat through port 1044
- 
- If Eclipse happens to be your IDE of choice, you can get more information at [[http://www.jacoozi.com/index.php?option=com_content&task=view&id=119&Itemid=134|Remote Debugging with Eclipse (Jacoozi Article)]].
- 
- See also:  [[FAQ/Developing]]
- 
- == How do I debug a Tomcat application when Tomcat is run as a Windows service ? ==
- You can debug the tomcat service by editing the service parameters as follows.
- 
-  * Launch a command prompt
- 
-  * Set the proper CATALINA_HOME environment variable : pointing to tomcat home
- 
-  * Run the following command:
- 
- {{{
- %CATALINA_HOME%\bin\tomcat6w.exe //ES//tomcat6
- }}}
-  * Select the Java tab in the properties dialog box,
- 
-  * Add the following two lines to the Java Options text box:
- 
- {{{
- -Xdebug
- -Xrunjdwp:transport=dt_socket,address=127.0.0.1:1044,server=y,suspend=n
- }}}
- If you want to allow remote debugging, replace 127.0.0.1 by your server IP address.
- 
-  * Click on "Apply" and close the dialog by clicking on "OK"
- 
-  * Restart the Apache Tomcat service
- 
-  * Use your IDE to connect to Tomcat through port 1044
- 
- If Eclipse happens to be your IDE of choice, you can get more information at [[http://www.jacoozi.com/index.php?option=com_content&task=view&id=119&Itemid=134|Remote Debugging with Eclipse (Jacoozi Article)]]. For IntelliJ IDEA you choose a remote debug target and set transport to "socket" and mode to "attach" , then you specify the host (127.0.0.1) and port (1044)
  
  == How do I enable Server Side Includes (SSI)? ==
  two things have to be done for tomcat to aknowledge SSI scripts:
@@ -512, +235 @@

  }}}
  additional information can be found at: http://tomcat.apache.org/tomcat-5.5-doc/ssi-howto.html
  
+ == How do I install the Administration web app? ==
+ If you install Tomcat 5.5 binaries, the Administration web app is not bundled with it; this describes how to add the Administration web app to your Tomcat 5.5 installation.  (Tomcat 4.1 comes with the Administration web app as part of the binary).
+ 
+ The following refers to a Tomcat 5.5 set up on Windows 2000, so your path names will be different on *nix platforms.  In this example, Tomcat 5.5.17 in installed in ''c:\Program Files\Apache Software Foundation\Tomcat 5.5'' (this is my '''CATALINA_HOME''').
+ 
+  1. Unzip or untar (be careful to use GNU tar) the file containing the administration web app files (eg. ''apache-tomcat-5.5.17-admin.zip'') to a temporary directory, eg. ''c:\temp''.
+ 
+  1. Copy ''c:\temp\apache-tomcat-5.5.17\conf\Catalina\localhost\admin.xml'' to the directory ''c:\Program Files\Apache Software Foundation\Tomcat 5.5\conf\Catalina\localhost''.
+ 
+  1. Copy the entire directory tree ''c:\temp\apache-tomcat-5.5.17\server\webapps\admin''
+ 
+ to the directory ''c:\Program Files\Apache Software Foundation\Tomcat 5.5\server\webapps''.  This is an overlay, so \server\webapps is just pointing you to the \server\webapps, and the admin directory with its contents will be the only thing you see added there.
+ 
+  1. Add a line to your ''c:\Program Files\Apache Software Foundation\Tomcat 5.5\conf\tomcat-users.xml'' file so that you have a user who has '''admin''' role.  For example, add this line   just before the last line (containing '''</tomcat-users>''') of the file:
+   . <user username="admin" password="makesomethingup" roles="admin,manager"/>
+ 
+  1. Restart Tomcat.
+ 
+  1. Now when you visit ''http://localhost:8080/admin'' you should see a page that asks for a user name and password.  If you still see the "no longer loaded" error message in your browser, you must either force a full reload of the web page (in Firefox, hold down Shift key while clicking on the Reload button) or just restart your browser completely.
+ 
+ 
+ == How do I add JARs or classes to the common classloader without adding them to $CATALINA_HOME/lib? ==
+ 
+ Either
+ 
+ a) Run Tomcat with separate {{{$CATALINA_BASE}}} and {{{$CATALINA_HOME}}} (as documented in {{{RUNNING.txt}}}) and place those classes into {{{$CATALINA_BASE/lib}}}, or
+ 
+ b) Edit the file ''catalina.properties'' under {{{$CATALINA_BASE/conf}}}; there is a property called ''common.loader'' to which you can add additional paths to find JARs or classes for the common classloader.
+ 
+ == How do I authenticate Manager access via JNDI to Active Directory for multiple Tomcat instances? ==
+ ADS insists that the CN of every group be unique, but the Manager app. always uses the group CN=manager.  The default can be changed, but it's hard to find and you have to do it over every time you upgrade.  Instead, pick an attribute other than the common name -- for example, "description" -- that doesn't have to be unique, name it as the `RoleName` attribute of the `Realm` (in server.xml, which you'll be editing anyway), and set that  attribute to "manager" in each group you create.  Create an OU for each Tomcat instance's groups and give that OU's DN as the `RoleBase` in that instance's server.xml.  Create a uniquely-named group in each instance's OU with the chosen attribute ("description" for example) set to "manager".
+ 
+ == Where and how do I set memory related settings to improve Tomcat performance? ==
+ When your web application is using large memory as this memory size default setting can be too small, 64MB by default,thus the application becomes slower because the garbage collector is invoked more often, and it can even run out of memory (outofmemory / heap space error ). One way to address this problem is to set a larger heap size . In Windows system, this can be done by editing / adding JAVA_OPTS variable (should be early in the file) in CATALINA_HOME/bin/catalina.bat or catalina.sh for Linux/Unix systems.Parameters to be added are , let say you want to increase it to 256 MB (as you required but make sure you have enough amount of physical memory/RAM and for 32bit system , use no more than 1-1.1 GB heap space size ) , use '-Xms256m -Xmx256m' .In some cases , it is better to set slightly lower size for -Xms . There are other parameters can be added , some of them :{{{'-XX:MaxNewSize -XX:NewSize -XX:MaxPermSize'}}} , depending on your application and requirements .
+ 
+ For catalina.bat there now should be a line in the file that looks like this:  {{{ set JAVA_OPTS=-Xms256m -Xmx256m }}}
+ 
+ For catalina.sh:  {{{ JAVA_OPTS='-Xms256m -Xmx256m' }}}
+ 
+ For other parameters , go to * http://wiki.apache.org/tomcat/FAQ/Memory * http://wiki.apache.org/tomcat/OutOfMemory
+ 
+ and Google and Yahoo are your friends.
+ 
+ == How do I make my web application be the Tomcat default application? ==
+ Congratulations.  You have created and tested a first web application (traditionally called "mywebapp"), users can access it via the URL "http://myhost.company.com/mywebapp".  You are very proud and satisfied.   But now, how do you change the setup, so that "mywebapp" gets called when the user enters the URL "http://myhost.company.com" ?
+ 
+ The pages and code of your "mywebapp" application currently reside in (CATALINA_BASE)/webapps/mywebapp/. In a standard Tomcat installation, you will notice that under the same directory (CATALINA_BASE)/webapps/, there is a directory called ROOT (the capitals are important, even under Windows).  That is the residence of the ''current'' Tomcat default application, the one that is called right now when a user calls up "http://myhost.company.com[:port]". The trick is to put your application in its place.
+ 
+ First stop Tomcat.<<BR>> Then before you replace the current default application, it may be a good idea to make a copy of it somewhere else.<<BR>> Then delete everything under the ROOT directory, and move everything that was previously under the (CATALINA_BASE)/webapps/mywebapp/ directory, toward this (CATALINA_BASE)/webapps/ROOT directory. In other words, what was previously .../mywebapp/WEB-INF should now be .../ROOT/WEB-INF (and not .../ROOT/mywebapp/WEB-INF).
+ 
+ Just by doing this, you have already made you webapp into the Tomcat ''default webapp''.
+ 
+ One step is left : you also need to have, within your application, a ''default servlet''.  If you don't want to use the standard one supplied by Tomcat that does nothing but deliver static content, you'll need to supply one of your own. This you do by means of an appropriate url-mapping in the WEB-INF/web.xml configuration file of your application. Make sure you have something like this in that file:
+ 
+ {{{
+    <servlet>
+         <servlet-name>My First Servlet</servlet-name>
+         <servlet-class>my.Servlet.Number1</servlet-class>
+     </servlet>
+ 
+     <servlet-mapping>
+         <servlet-name>My First Servlet</servlet-name>
+         <url-pattern>/*</url-pattern>
+     </servlet-mapping>
+ }}}
+ The above will override the mapping for Tomcat's DefaultServlet in the global conf/web.xml file.
+ 
+ Restart Tomcat and you're done.<<BR>> Call up "http://myhost.company.com/" and enjoy.
+ 
+ '''Addendum 1 : If you are deploying your application as a war file..'''
+ 
+ The above instructions relate to the situation where you are "manually" deploying your application as a directory-and-files structure under the /webapps directory.  If instead you are using the "war" method to deploy your application, the principle is about the same :<<BR>> - delete the ROOT directory<<BR>> - name your war file "ROOT.war" (capitals mandatory)<<BR>> - drop the ROOT.war file directly in the /webapps directory.<<BR>> Tomcat will automatically deploy it.
+ 
+ For more information about this topic in general, consult this page :  [[http://tomcat.apache.org/tomcat-6.0-doc/config/context.html|The Context Container]]
+ 
+ '''Addendum 2 : If for some reason you want another method..'''
+ 
+ If, for some reason, you do not want to deploy your application under the CATALINA_BASE/webapps/ROOT subdirectory, or you do not want to name your war-file "ROOT.war", then read on.  But you should first read this : [[http://tomcat.apache.org/tomcat-6.0-doc/config/context.html|The Context Container]] and make sure you understand the implications.
+ 
+ The method described above is the simple method.  The two methods below are more complex, and the second one has definite implications on the way you manage and run your Tomcat.
+ 
+ '''Method 2.1'''
+ 
+ - Place your war file outside of CATALINA_BASE/webapps (it '''must''' be outside to prevent double deployment).<<BR>> - Place a context file named ROOT.xml in CATALINA_BASE/conf/<engine name>/<host name>.  The single <Context> element in this context file MUST have a '''docBase''' attribute pointing to the location of your war file. The path element should not be set - it is derived from the name of the .xml file, in this case ROOT.xml. See the Context Container above for details.
+ 
+ '''Method 2.2'''
+ 
+ If you really know what you are doing..
+ 
+ - leave your war file in CATALINA_BASE/webapps, under its original name<<BR>> - turn off autoDeploy '''and''' deployOnStartup in your Host element in the server.xml file.<<BR>> - explicitly define '''all''' application Contexts in server.xml, specifying both path and docBase. You must do this, because you have disabled all the Tomcat auto-deploy mechanisms, and Tomcat will not deploy your applications anymore unless it finds their Context in the server.xml.
+ 
+ Note that this last method also implies that in order to make any change to any application, you will have to stop and restart Tomcat.
+ 
+ == How do I set up Tomcat virtual hosts in a development environment? ==
+ See TomcatDevelopmentVirtualHosts
+ 
+ 
+ 
+ = Programming =
+ 
+ == How do call tomcat ant tasks to deploy webapps? ==
+ See AntDeploy
+ 
+ == How do I load a properties file? ==
+ Here are the three most popular ways::
+ 
+  * Use a classloader's getResource to get an url to the properties file and load it into the Properties. The properties file must be located within the webapp classpath (i.e. either {{{WEB-INF/classes/...}}} or in a jar in {{{WEB-INF/lib/}}}).
+ 
+ A challenge is to get the classloader when you are in a static initializer:
+ 
+ {{{
+   public class Config {
+      private static java.util.Properties prop = new java.util.Properties();
+      private static loadProperties() {
+           // get class loader
+           ClassLoader loader = Config.class.getClassLoader();
+           if(loader==null)
+             loader = ClassLoader.getSystemClassLoader();
+ 
+           // assuming you want to load application.properties located in WEB-INF/classes/conf/
+           String propFile = "conf/application.properties";
+           java.net.URL url = loader.getResource(propFile);
+           try{prop.load(url.openStream());}catch(Exception e){System.err.println("Could not load configuration file: " + propFile);}
+      }
+ 
+      //....
+      // add your methods here. prop is filled with the content of conf/application.properties
+ 
+      // load the properties when class is accessed
+      static {
+         loadProperties();
+      }
+   }
+ }}}
+ This method even works in a standalone java application. So it is my preferred way. (see also [[http://knowhow.amazers.net/space/dev/java+tips/Loading+properties+in+a+web+application|this article]])
+ 
+  * Use a `ResourceBundle`. See the Java docs for the specifics of how the `ResourceBundle` class works. Using this method, the properties file must go into the `WEB-INF/classes` directory or in a jar file contained in the `WEB-INF/lib` directory.
+ 
+  * Another way is to use the method `getResourceAsStream()` from the `ServletContext` class. This allows you update the file without having to reload the webapp as required by the first method. Here is an example code snippet, without any error trapping:
+ 
+ {{{
+ // Assuming you are in a Servlet extending HttpServlet
+ // This will look for a file called "/more/cowbell.properties" relative
+ // to your servlet Root Context
+ InputStream is = getServletContext().getResourceAsStream("/more/cowbell.properties");
+ Properties  p  = new Properties();
+ p.load(is);
+ is.close();
+ }}}
+ 
+ == How do I share sessions across web apps? ==
+ You cannot share sessions directly across web apps, as that would be a violation of the Servlet Specification.  There are workarounds, including using a singleton class loaded from the common classloader repository to hold shared information, or putting some of this shared information in a database or another data store.  Some of these approaches have been discussed on the [[http://tomcat.apache.org/lists.html#tomcat-users|tomcat-user mailing list]], whose archives you should search for more information.
+ 
+ Sharing sessions across containers for clustering or replication purposes is a different matter altogether.
+ 
+ == How can I access members of a custom Realm or Principal? ==
+ When you create a custom subclass of `RealmBase` or `GenericPrincipal` and attempt to use those classes in your webapp code, you'll probably have problems with `ClassCastException`.  This is because the instance returned by `request.getUserPrincipal()` is of a class loaded by the server's classloader, and you are trying to access it through you webapp's classloader.  While the classes maybe otherwise exactly the same, different (sibling) classloaders makes them different classes.
+ 
+ This assumes you created a `MyPrincipal` class, and put in Tomcat's server/classes (or lib) directory, as well as in your webapp's webinf/classes (or lib) directory.  Normally, you would put custom realm and principal classes in the server directory because they depend on other classes there.
+ 
+ Here's what you would like to do, but it throws `ClassCastException`:
+ 
+ {{{
+ MyPrincipal p = request.getUserPrincipal();
+ String emailAddress = p.getEmailAddress();
+ }}}
+ Here are 4 ways you might get around the classloader boundary:
+ 
+ 1) ''Reflection''
+ 
+ {{{
+ Principal p = request.getUserPrincipal();
+ String emailAddress = p.getClass().getMethod("getEmailAddress", null).invoke(p, null);
+ }}}
+ 2) ''Move classes to a common classloader''
+ 
+ You could put your custom classes in a classloader that is common to both the server and your webapp - e.g., either the "common" or bootstrap classloaders.  To do this, however, you would also need to move the classes that your custom classes depend on up to the common classloader, and that seems like a bad idea, because there a many of them and they a core server classes.
+ 
+ 3) ''Common Interfaces''
+ 
+ Rather than move the implementing custom classes up, you could define interfaces for your customs classes, and put the interfaces in the common directory.  You're code would look like this:
+ 
+ {{{
+ public interface MyPrincipalInterface extends java.security.Principal {
+   public String getEmailAddress();
+ }
+ 
+ public class MyPrincipal implements MyPrincipalInterface {
+ ...
+   public String getEmailAddress() {
+     return emailAddress;
+   }
+ }
+ 
+ public class MyServlet implements Servlet {
+   protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
+     MyPrincipalInterface p = (MyPrincipalInterface)request.getUserPrincipal();
+     String emailAddress = p.getEmailAddress();
+ ...
+ }
+ }}}
+ ''Notice that this method gives you pretty much the webapp code you wanted in the first place''
+ 
+ 4) ''Serializing / Deserializing''
+ 
+ You might want to try serializing the response of 'request.getUserPrincipal()' and deserialize it to an instance of [webapp]MyPrincipal.
+ 
+ == How do I get direct access to a Tomcat Realm? ==
+ Credit: This code is from a post by Yoav Shapira http://www.yoavshapira.com in the user list
+ 
+ Sometimes access directly into the Tomcat realm object is needed; to do, this the following code can be used.  Be aware, however, that by using this, your application is relying on a Tomcat extension and is therefore non-standard.
+ 
+ Note that in order for this to work the Context of the web application in question needs to have its privileged attribute set to "true", otherwise web apps do not have access to the Tomcat classes.
+ 
+ {{{
+ Server server = ServerFactory.getServer();
+ //Note, this assumes the Container is "Catalina"
+ Service service = server.findService("Catalina");
+ Engine engine = (Engine) service.getContainer();
+ Host host = (Host) engine.findChild(engine.getDefaultHost());
+ //Note, this assumes your context is "myContext"
+ Context context = (Context) host.findChild("myContext");
+ Realm realm = context.getRealm();
+ }}}
+ 
+ == How do I redirect System.out and System.err to my web page? ==
+ I have met a situation where I needed to redirect a portion of standard ouput (`System.out`, STDOUT) and standard error (`System.err`, STDERR) to my web page instead of a log file. An example of such an application is a compiler research platform that our resarch team is putting online for anybody to be able to quickly compile-test their programs on line. Naturally, the compilers dump some of their stuff to STDERR or STDOUT and they are not web application `.jar`. Thus, I needed badly these streams related to the compiler output to be redirected to my web editor interface. Having found no easy instructions on how to do that lead me writing up this quick HOWTO. The HOWTO is based on Servlets, but similar arrangements can be done for JSPs. The below example shows the essentials, with most non-essentials removed.
+ 
+ {{{
+ public class WebEditor
+ extends HttpServlet
+ {
+  ...
+         public void doGet
+         (
+                 HttpServletRequest poHTTPRequest,
+                 HttpServletResponse poHTTPResponse
+         )
+         throws IOException, ServletException
+         {
+                 poHTTPResponse.setContentType("text/html");
+ 
+                 ServletOutputStream out = poHTTPResponse.getOutputStream();
+ 
+                 out.println("<html>");
+                 out.println("<body>");
+                 out.println("<head>");
+                 out.println("<title>WebEditor Test $Revision: 1.6 $</title>");
+                 out.println("</head>");
+                 out.println("<body>");
+                 out.println("<h3>WebEditor Test $Revision: 1.6 $</h3>");
+                 out.println("<hr />");
+ 
+                 // Backup the streams
+                 PrintStream oStdOutBackup = System.out;
+                 PrintStream oStdErrBackup = System.err;
+ 
+                 // Redired STDOUT and STDERR to the ServletOuputStream
+                 System.setOut(new PrintStream(out));
+                 System.setErr(new PrintStream(out));
+ 
+ 
+                 try
+                 {
+                         // ... call compiler here that produces
+                         // tons of STDOUT/STDERR messages ...
+                 }
+                 catch(Exception e)
+                 {
+                         out.println(e.toString());
+                 }
+ 
+                 // Restore original STDOUT and STDERR
+                 System.setOut(oStdOutBackup);
+                 System.setErr(oStdErrBackup);
+ 
+                 out.println("<hr />");
+                 out.println("</body>");
+                 out.println("</html>");
+         }
+ }
+ }}}
+ A few caveats arise, as for instance while the `System.out` and `System.err` are redirected as per above, no logging of these is done to files. You will need more legwork to do to make the additional logging. It is important to backup and restore the original streams as the above example does. Also, notice the use of `getOutputStream()`: when this method is called, the `getWriter()` method can no longer be used in the same response object.
+ 
+ Corrections and comments are most welcome!
+ 
  == How do I connect to a Websphere MQ (MQ Series) server using JMS and JNDI? ==
  Basically, this works just as described in  http://tomcat.apache.org/tomcat-5.5-doc/jndi-resources-howto.html: Within your application, you are using the standard JNDI and JMS API calls. In web.xml (the container independent application descriptor), you specify resource references (stub resources). And in context.xml (the container specific application descriptor), you are actually configuring the JMS connection.
  
@@ -606, +615 @@

  == How do I use DataSources with Tomcat? ==
  See UsingDataSources
  
- == How do I install the Administration web app? ==
- If you install Tomcat 5.5 binaries, the Administration web app is not bundled with it; this describes how to add the Administration web app to your Tomcat 5.5 installation.  (Tomcat 4.1 comes with the Administration web app as part of the binary).
+ == How do I use Hibernate and database connection pooling with Tomcat? ==
+ See TomcatHibernate
  
- The following refers to a Tomcat 5.5 set up on Windows 2000, so your path names will be different on *nix platforms.  In this example, Tomcat 5.5.17 in installed in ''c:\Program Files\Apache Software Foundation\Tomcat 5.5'' (this is my '''CATALINA_HOME''').
+ == How do I use DataSourceRealms for authentication and authorization? ==
+ See TomcatDataSourceRealms
  
-  1. Unzip or untar (be careful to use GNU tar) the file containing the administration web app files (eg. ''apache-tomcat-5.5.17-admin.zip'') to a temporary directory, eg. ''c:\temp''.
  
-  1. Copy ''c:\temp\apache-tomcat-5.5.17\conf\Catalina\localhost\admin.xml'' to the directory ''c:\Program Files\Apache Software Foundation\Tomcat 5.5\conf\Catalina\localhost''.
+ = Troubleshooting =
  
-  1. Copy the entire directory tree ''c:\temp\apache-tomcat-5.5.17\server\webapps\admin''
+ == Tomcat crashed! What do I do now? ==
+ These steps are in no particular order ...
  
- to the directory ''c:\Program Files\Apache Software Foundation\Tomcat 5.5\server\webapps''.  This is an overlay, so \server\webapps is just pointing you to the \server\webapps, and the admin directory with its contents will be the only thing you see added there.
+  1. Read the Tomcat FAQ
+  1. Read the Tomcat RELEASE NOTES - there is something about Linux in it
+  1. First look at the stack traces. I hope a stack trace was produced before the failure aborted the JVM process. After you get a few stack traces, see if a pattern appears. Trace back to source code if needed.
+  1. Patch (or ''unpatch''!) the operating system as needed.
+  1. Patch (or ''unpatch''!) the JVM (Java Virtual Machine).
+  1. Linux Problem? - read the RELEASE NOTES!
+  1. Look at commercial vendor support for other servlet engines. Sometimes the problem is universal regardless of servlet engine and may be a JVM/OS/application code issue
+  1. Search Google for web pages - maybe someone else had this problem. I'll bet they did.
+  1. Search Google news groups
+  1. If the JVM is from a commercial vendor, (eg: IBM, HP) check their release notes and news groups
+  1. Using a database? Make sure JDBC type 4 drivers are used. Check their release notes.
+  1. Tweak JVM memory parameters. Setting memory too high can be as bad as having memory too low. If your memory settings are set too high, Java 1.3 JVMs may freeze while waiting for the entire garbage collection to finish. Also if the JVM has too much memory, if may be starving other resources on the machine which are needed which may be causing unforeseen exceptions. In a nutshell, throwing more memory doesn't always solve the problem!
+  1. Turn off the Java JIT compiler. See the Java Docs on how to do this.
  
-  1. Add a line to your ''c:\Program Files\Apache Software Foundation\Tomcat 5.5\conf\tomcat-users.xml'' file so that you have a user who has '''admin''' role.  For example, add this line   just before the last line (containing '''</tomcat-users>''') of the file:
-   . <user username="admin" password="makesomethingup" roles="admin,manager"/>
  
-  1. Restart Tomcat.
+ == I'm encountering classloader problems when using JNI under Tomcat ==
+ The important thing to know about using JNI under Tomcat is that one cannot place the native libraries OR their JNI interfaces under the WEB-INF/lib or WEB-INF/classes directories of a web application and expect to be able to reload the webapp without restarting the server. The class that calls System.loadLibrary(String) must be loaded by a classloader that is not affected by reloading the web application itself.
  
-  1. Now when you visit ''http://localhost:8080/admin'' you should see a page that asks for a user name and password.  If you still see the "no longer loaded" error message in your browser, you must either force a full reload of the web page (in Firefox, hold down Shift key while clicking on the Reload button) or just restart your browser completely.
+ Thus, if you have JNI code that follows the convention of including a static initilaizer like this:
  
- == How do I add JARs or classes to the common classloader without adding them to $CATALINA_HOME/lib? ==
+ {{{
+ class FooWrapper {
+     static {
+         System.loadLibrary("foo");
+     }
  
- Either
+     native void doFoo();
+   }
+ }}}
+ then both this class and the shared library should be placed in the `$CATALINA_HOME/shared/lib` directory.
  
- a) Run Tomcat with separate {{{$CATALINA_BASE}}} and {{{$CATALINA_HOME}}} (as documented in {{{RUNNING.txt}}}) and place those classes into {{{$CATALINA_BASE/lib}}}, or
+ ''Note that under Windows, you'll also need to make sure that the library is in the {{{java.library.path}}}.  Either add {{{%CATALINA_HOME%\shared\lib}}} to your Windows PATH environment variable, or place the DLL files in another location that is currently on the {{{java.library.path}}}.  There may be a similar requirement for UNIX based system (I haven't checked), in which case you'd also have to add {{{$CATALINA_HOME/shared/lib}}} to the PATH environment variable.  (Note: I'm not the original author of this entry.)''
  
- b) Edit the file ''catalina.properties'' under {{{$CATALINA_BASE/conf}}}; there is a property called ''common.loader'' to which you can add additional paths to find JARs or classes for the common classloader.
+ The symptom of this problem that I encountered looked something like this -
  
- == How do I authenticate Manager access via JNDI to Active Directory for multiple Tomcat instances? ==
- ADS insists that the CN of every group be unique, but the Manager app. always uses the group CN=manager.  The default can be changed, but it's hard to find and you have to do it over every time you upgrade.  Instead, pick an attribute other than the common name -- for example, "description" -- that doesn't have to be unique, name it as the `RoleName` attribute of the `Realm` (in server.xml, which you'll be editing anyway), and set that  attribute to "manager" in each group you create.  Create an OU for each Tomcat instance's groups and give that OU's DN as the `RoleBase` in that instance's server.xml.  Create a uniquely-named group in each instance's OU with the chosen attribute ("description" for example) set to "manager".
+ {{{
+ java.lang.UnsatisfiedLinkError: Native Library WEB-INF/lib/libfoo.so already loaded in another classloader
+         at java.lang.ClassLoader.loadLibrary0(ClassLoader.java:1525)
+ }}}
+ If the `UnsatisfiedLinkError` is intermittent, it may be related to Tomcat's default session manager.  It restored previous sessions at startup.  One of those objects may load the JNI library.  Try stopping the Tomcat JVM, deleting the SESSIONS.ser file, then starting Tomcat.  You may consider changing the session persistence manager at this time.
+ 
+ Note that Tomcat 6.0.14 the $CATALINA_HOME/shared/lib directory does not exist. You will need to add this and you will need to edit $CATALINA_HOME/conf/catalina.properties so that the shared.loader line looks like this shared.loader=$CATALINA_HOME/shared/lib
+ 
+ == How do I debug a Tomcat application? ==
+ There is nothing magical about debugging a Tomcat application. All you need is an IDE and two environment variables.
+ 
+  * If you have not already done so begin by creating a new Tomcat context for your application. Navigate to '''TOMCAT_HOME\conf\Catalina\localhost''' and create a new file, say, myapp.xml. This will become part of your url, so to access your app you'll have to type '''http://localhost:8080/myapp'''.
+  * Enter the following in myapp.xml:
+ 
+ {{{
+ <Context docBase="c:/workspace/myapp/WebRoot" />
+ }}}
+  . This assumes you have a web application containing WEB-INF in '''c:/workspace/myapp/WebRoot'''
+ 
+  * Create two environment variables:
+ 
+ {{{
+ C:\>set JPDA_ADDRESS=1044
+ C:\>set JPDA_TRANSPORT=dt_socket
+ }}}
+  * Now, you can launch Tomcat with these debug options:
+ 
+ {{{
+ TOMCAT_HOME\bin\>catalina jpda start
+ }}}
+  * Use your IDE to connect to Tomcat through port 1044
+ 
+ If Eclipse happens to be your IDE of choice, you can get more information at [[http://www.jacoozi.com/index.php?option=com_content&task=view&id=119&Itemid=134|Remote Debugging with Eclipse (Jacoozi Article)]].
+ 
+ See also:  [[FAQ/Developing]]
+ 
+ == How do I debug a Tomcat application when Tomcat is run as a Windows service ? ==
+ You can debug the tomcat service by editing the service parameters as follows.
+ 
+  * Launch a command prompt
+ 
+  * Set the proper CATALINA_HOME environment variable : pointing to tomcat home
+ 
+  * Run the following command:
+ 
+ {{{
+ %CATALINA_HOME%\bin\tomcat6w.exe //ES//tomcat6
+ }}}
+  * Select the Java tab in the properties dialog box,
+ 
+  * Add the following two lines to the Java Options text box:
+ 
+ {{{
+ -Xdebug
+ -Xrunjdwp:transport=dt_socket,address=127.0.0.1:1044,server=y,suspend=n
+ }}}
+ If you want to allow remote debugging, replace 127.0.0.1 by your server IP address.
+ 
+  * Click on "Apply" and close the dialog by clicking on "OK"
+ 
+  * Restart the Apache Tomcat service
+ 
+  * Use your IDE to connect to Tomcat through port 1044
+ 
+ If Eclipse happens to be your IDE of choice, you can get more information at [[http://www.jacoozi.com/index.php?option=com_content&task=view&id=119&Itemid=134|Remote Debugging with Eclipse (Jacoozi Article)]]. For IntelliJ IDEA you choose a remote debug target and set transport to "socket" and mode to "attach" , then you specify the host (127.0.0.1) and port (1044)
  
  == How do I check whether Tomcat is UP or DOWN? There is no status command ==
  Unfortunately, the `org.apache.catalina.util.ServerInfo` class does not determine if Tomcat is UP or DOWN. It is possible to do an HTTP GET on the root url but this is not accurate. In my case I sometimes use a regular Apache HTTPd to display a maintainence message while upgrading, etc. and using that method would give false positives.
@@ -794, +885 @@

    }
  }
  }}}
- == Where and how do I set memory related settings to improve Tomcat performance? ==
- When your web application is using large memory as this memory size default setting can be too small, 64MB by default,thus the application becomes slower because the garbage collector is invoked more often, and it can even run out of memory (outofmemory / heap space error ). One way to address this problem is to set a larger heap size . In Windows system, this can be done by editing / adding JAVA_OPTS variable (should be early in the file) in CATALINA_HOME/bin/catalina.bat or catalina.sh for Linux/Unix systems.Parameters to be added are , let say you want to increase it to 256 MB (as you required but make sure you have enough amount of physical memory/RAM and for 32bit system , use no more than 1-1.1 GB heap space size ) , use '-Xms256m -Xmx256m' .In some cases , it is better to set slightly lower size for -Xms . There are other parameters can be added , some of them :{{{'-XX:MaxNewSize -XX:NewSize -XX:MaxPermSize'}}} , depending on your application and requirements .
- 
- For catalina.bat there now should be a line in the file that looks like this:  {{{ set JAVA_OPTS=-Xms256m -Xmx256m }}}
- 
- For catalina.sh:  {{{ JAVA_OPTS='-Xms256m -Xmx256m' }}}
- 
- For other parameters , go to * http://wiki.apache.org/tomcat/FAQ/Memory * http://wiki.apache.org/tomcat/OutOfMemory
- 
- and Google and Yahoo are your friends.
- 
- == How do I make my web application be the Tomcat default application ? ==
- Congratulations.  You have created and tested a first web application (traditionally called "mywebapp"), users can access it via the URL "http://myhost.company.com/mywebapp".  You are very proud and satisfied.   But now, how do you change the setup, so that "mywebapp" gets called when the user enters the URL "http://myhost.company.com" ?
- 
- The pages and code of your "mywebapp" application currently reside in (CATALINA_BASE)/webapps/mywebapp/. In a standard Tomcat installation, you will notice that under the same directory (CATALINA_BASE)/webapps/, there is a directory called ROOT (the capitals are important, even under Windows).  That is the residence of the ''current'' Tomcat default application, the one that is called right now when a user calls up "http://myhost.company.com[:port]". The trick is to put your application in its place.
- 
- First stop Tomcat.<<BR>> Then before you replace the current default application, it may be a good idea to make a copy of it somewhere else.<<BR>> Then delete everything under the ROOT directory, and move everything that was previously under the (CATALINA_BASE)/webapps/mywebapp/ directory, toward this (CATALINA_BASE)/webapps/ROOT directory. In other words, what was previously .../mywebapp/WEB-INF should now be .../ROOT/WEB-INF (and not .../ROOT/mywebapp/WEB-INF).
- 
- Just by doing this, you have already made you webapp into the Tomcat ''default webapp''.
- 
- One step is left : you also need to have, within your application, a ''default servlet''.  If you don't want to use the standard one supplied by Tomcat that does nothing but deliver static content, you'll need to supply one of your own. This you do by means of an appropriate url-mapping in the WEB-INF/web.xml configuration file of your application. Make sure you have something like this in that file:
- 
- {{{
-    <servlet>
-         <servlet-name>My First Servlet</servlet-name>
-         <servlet-class>my.Servlet.Number1</servlet-class>
-     </servlet>
- 
-     <servlet-mapping>
-         <servlet-name>My First Servlet</servlet-name>
-         <url-pattern>/*</url-pattern>
-     </servlet-mapping>
- }}}
- The above will override the mapping for Tomcat's DefaultServlet in the global conf/web.xml file.
- 
- Restart Tomcat and you're done.<<BR>> Call up "http://myhost.company.com/" and enjoy.
- 
- '''Addendum 1 : If you are deploying your application as a war file..'''
- 
- The above instructions relate to the situation where you are "manually" deploying your application as a directory-and-files structure under the /webapps directory.  If instead you are using the "war" method to deploy your application, the principle is about the same :<<BR>> - delete the ROOT directory<<BR>> - name your war file "ROOT.war" (capitals mandatory)<<BR>> - drop the ROOT.war file directly in the /webapps directory.<<BR>> Tomcat will automatically deploy it.
- 
- For more information about this topic in general, consult this page :  [[http://tomcat.apache.org/tomcat-6.0-doc/config/context.html|The Context Container]]
- 
- '''Addendum 2 : If for some reason you want another method..'''
- 
- If, for some reason, you do not want to deploy your application under the CATALINA_BASE/webapps/ROOT subdirectory, or you do not want to name your war-file "ROOT.war", then read on.  But you should first read this : [[http://tomcat.apache.org/tomcat-6.0-doc/config/context.html|The Context Container]] and make sure you understand the implications.
- 
- The method described above is the simple method.  The two methods below are more complex, and the second one has definite implications on the way you manage and run your Tomcat.
- 
- '''Method 2.1'''
- 
- - Place your war file outside of CATALINA_BASE/webapps (it '''must''' be outside to prevent double deployment).<<BR>> - Place a context file named ROOT.xml in CATALINA_BASE/conf/<engine name>/<host name>.  The single <Context> element in this context file MUST have a '''docBase''' attribute pointing to the location of your war file. The path element should not be set - it is derived from the name of the .xml file, in this case ROOT.xml. See the Context Container above for details.
- 
- '''Method 2.2'''
- 
- If you really know what you are doing..
- 
- - leave your war file in CATALINA_BASE/webapps, under its original name<<BR>> - turn off autoDeploy '''and''' deployOnStartup in your Host element in the server.xml file.<<BR>> - explicitly define '''all''' application Contexts in server.xml, specifying both path and docBase. You must do this, because you have disabled all the Tomcat auto-deploy mechanisms, and Tomcat will not deploy your applications anymore unless it finds their Context in the server.xml.
- 
- Note that this last method also implies that in order to make any change to any application, you will have to stop and restart Tomcat.
  
  == How do I obtain a thread dump of my running webapp ? ==
  You can only get a thread dump of the entire JVM, not just your webapp. This shouldn't be a big deal, but should be made clear: you are getting a dump of all JVM threads, not just those "for your application", whatever that means.
@@ -879, +910 @@

  
  This will produce a thread dump on standard output, but may not be possible to capture to a file.
  
- == How do I use Hibernate and database connection pooling with Tomcat? ==
- See TomcatHibernate
- 
- == How do I set up Tomcat virtual hosts in a development environment? ==
- See TomcatDevelopmentVirtualHosts
- 
- == How do I use DataSourceRealms for authentication and authorization? ==
- See TomcatDataSourceRealms
  
  == How do I add my own custom MBean to monitor my application within Tomcat 5/6? ==
  

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org


Mime
View raw message