Caucho Technology
  • resin 4.0
  • command-line configuration


    While most configuration options have been made available in resin.xml, this section describes some common command-line options.

    ./configure options

    The ./configure; make; make install step is important for all Unix users. It configures and compiles low level JNI code that enables Resin to provide a number of features not normally available to Java programs and also provides significant performance improvements.

    The most commonly used options for ./configure are documented below, the full set of available command line options is available by running ./configure --help.

    --helpHelp for all ./configure command line options
    --enable-64bitCompiles the JNI using 64-bits, requires <jvm-arg>-d64</jvm-arg> entry in resin.xml
    --enable-sslEnable OpenSSL, see the OpenSSL documentation for details.
    --with-apxs=/path/to/apxsEnable Apache integration and produce mod_caucho
    --enable-debugEnables extended logging for mod_caucho, isapi_dll and resin_jni. Log files corresponding to these modules can be found respectively in /tmp/mod_caucho.log, /temp/isapi_dll.log and stderr for the JVM running Resin.

    The 64-bit JNI compilation must match the JDK you're using, i.e. you'll need to add a <jvm-arg>-d64</jvm-arg> entry in resin.xml to indicate that the jvm should start in 64-bit mode.

    Startup Options

    As of Resin 4.0, startup options should be declared in the configuration file using <jvm-arg>. However, some startup options are available via the command line.

    Command-line arguments

    ARGUMENTMEANINGDEFAULT
    -conf xxxSelects the Resin configuration fileconf/resin.xml
    -server xxxSelects the <server> in the resin.xml""
    -verboseShow the Java environment before starting Resin.off
    -resin-home xxx Deprecated. Sets the Resin home directory. Use environment variable RESIN_HOME or <jvm-arg>-Dresin.home=xxx</jvm-arg> in resin.xml. The parent directory of resin.jar
    consoleStarts Resin in console mode for development and debuggingn/a
    startStarts Resin as a daemon, starting the watchdog if necessaryn/a
    statusShow the status of Resin as a daemon.n/a
    stopStops Resin as a daemon by contacting the watchdog.n/a
    restartRestarts Resin as a daemon by contacting the watchdog.n/a
    killKill Resin as a daemon by contacting the watchdog, a killed process is destroyed and not allowed to clean up or finish pending connections.n/a
    shutdownShutdown the watchdog and all of the Resin daemons.n/a
    help [command]Prints general help message or command help message when command is specifiedn/a

    JDK arguments

    Resin 4.0 has moved all JDK arguments into the resin.xml file, in the <jvm-arg> tag. Because the Resin 4.0 watchdog starts each Resin server instance, it can pass the arguments defined in the configuration file to the JVM. By moving the Java arguments to the configuration file, server configuration is easier and more maintainable.

    resin.xml with Java arguments
          <resin xmlns="http://caucho.com/ns/resin">
            <cluster id="app-tier">
    
              <server-default>
                <jvm-arg>-Xms32m</jvm-arg>
                <jvm-arg>-Xmx512m</jvm-arg>
                <jvm-arg>-Xss1m</jvm-arg>
                <jvm-arg>-verbosegc</jvm-arg>
                <jvm-arg>-Dfoo=bar</jvm-arg>
                <jvm-arg>-Dcaucho.smallmem</jvm-arg>
                <jvm-arg>-agentlib:resin</jvm-arg>
                <jvm-arg>-Xdebug</jvm-arg>
                
                <http port="8080"/>
              </server-default>
    
              <server id="a" address="192.168.2.1" port="6800"/>
    
              ...
            </cluster>
          </resin>
          

    Heap size

    The allocation of memory for the JVM is specified using -X options when starting Resin (the exact options may depend upon the JVM that you are using, the examples here are for the Sun JVM).

    JVM OPTION PASSED TO RESINMEANING
    -Xmsinitial java heap size
    -Xmxmaximum java heap size
    -Xmnthe size of the heap for the young generation
    Example: resin.xml startup with heap memory options
    <resin xmlns="http://caucho.com/ns/resin">
    <cluster id="">
    
      <server id="" address="127.0.0.1" port="6800">
        <jvm-arg>-Xmx500M</jvm-arg>
        <jvm-arg>-Xms500M</jvm-arg>
        <jvm-arg>-Xmn100M</jvm-arg>
    
        <http port="80"/>
      </server>
    
      ...
    
    </cluster>
    </resin>
    

    It is good practice with server-side Java applications like Resin to set the minimum -Xms and maximum -Xmx heap sizes to the same value.

    For efficient garbage collection, the -Xmn value should be lower than the -Xmx value.

    Heap size does not determine the amount of memory your process uses

    If you monitor your java process with an OS tool like top or taskmanager, you may see the amount of memory you use exceed the amount you have specified for -Xmx. -Xmx limits the java heap size, java will allocate memory for other things, including a stack for each thread. It is not unusual for the total memory consumption of the VM to exceed the value of -Xmx.

    Garbage collection

    (thanks to Rob Lockstone for his comments)

    There are essentially two GC threads running. One is a very lightweight thread which does "little" collections primarily on the Eden (a.k.a. Young) generation of the heap. The other is the Full GC thread which traverses the entire heap when there is not enough memory left to allocate space for objects which get promoted from the Eden to the older generation(s).

    If there is a memory leak or inadequate heap allocated, eventually the older generation will start to run out of room causing the Full GC thread to run (nearly) continuously. Since this process "stops the world", Resin won't be able to respond to requests and they'll start to back up.

    The amount allocated for the Eden generation is the value specified with -Xmn. The amount allocated for the older generation is the value of -Xmx minus the -Xmn. Generally, you don't want the Eden to be too big or it will take too long for the GC to look through it for space that can be reclaimed.

    Stack size

    Each thread in the VM gets a stack. The stack size will limit the number of threads that you can have, too big of a stack size and you will run out of memory as each thread is allocated more memory than it needs. 2048k is an appropriate value for most situations.

    Stack configuration
    <JVM-ARG>MEANING
    -Xssthe stack size for each thread

    -Xss determines the size of the stack: -Xss1024k. If the stack space is too small, eventually you will see a java.lang.StackOverflowError.

    Some people have reported that it is necessary to change stack size settings at the OS level for Linux. A call to ulimit may be necessary, and is usually done with a command in /etc/profile:

    Limit thread stack size on Linux
    unix> ulimit -s 2048
    

    Monitoring the JVM

    JDK 6 includes a number of tools that are useful for monitoring the JVM. Documentation for these tools is available from the Sun website.

    The most useful tool is jconsole. Details on using jconsole are provided in the Administration section of the Resin documentation.

    Example: jconsole configuration
    <resin xmlns="http://caucho.com/ns/resin">
    <cluster id="">
    
      <server-default>
        <jvm-arg>-Dcom.sun.management.jmxremote</jvm-arg>
      </server-default>
    
      <server id="" address="127.0.0.1" port="6800"/>
    
      ...
    </cluster>  
    </resin>
    
    Example: jconsole launching
     ... in another shell window ... 
    
    win> jconsole.exe
    unix> jconsole
    
    Choose Resin's JVM from the "Local" list.

    jps and jstack are also useful, providing a quick command line method for obtaining stack traces of all current threads. Details on obtaining and interpreting stack traces is in the resin-admin console documentation.

    jps and jstack
    # jps
    12903 Jps
    20087 Resin
    # jstack 20087
    Attaching to process ID 20087, please wait...
    Debugger attached successfully.
    Client compiler detected.
    JVM version is 1.5.0-beta2-b51
    Thread 12691: (state = BLOCKED)
     - java.lang.Object.wait(long) (Compiled frame; information may be imprecise)
     - com.caucho.util.ThreadPool.runTasks() @bci=111, line=474 (Compiled frame)
     - com.caucho.util.ThreadPool.run() @bci=85, line=423 (Interpreted frame)
     - java.lang.Thread.run() @bci=11, line=595 (Interpreted frame)
    
    
    Thread 12689: (state = BLOCKED)
     - java.lang.Object.wait(long) (Compiled frame; information may be imprecise)
     - com.caucho.util.ThreadPool.runTasks() @bci=111, line=474 (Compiled frame)
     - com.caucho.util.ThreadPool.run() @bci=85, line=423 (Interpreted frame)
     - java.lang.Thread.run() @bci=11, line=595 (Interpreted frame)
    
    ...
    
    

    Copyright © 1998-2011 Caucho Technology, Inc. All rights reserved.
    Resin ® is a registered trademark, and Quercustm, Ambertm, and Hessiantm are trademarks of Caucho Technology.