wrapper.commandfile

Compatibility :3.2.0
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/OSIBM z/Linux

WARNING

DO NOT modify any of these parameters unless you have read this property description. Incorrect settings can cause the Wrapper to fail to operate as expected.

File which will be monitored for commands to be executed. This property is not set by default.

This property has no use for most applications, but it can be useful to external applications which need to control the Wrapper in a cross-platform manner.

If this property is set, the Wrapper will check at regular intervals for the existence of the specified file. When found, the file will be opened and all commands will be executed in order. The file will be deleted at the completion of the commands.

Example:
wrapper.commandfile=./myapp.command

NOTE

Security Risk:

Be aware that the use of this property can pose a security risk, as the Wrapper can be controlled simply by creating a text file. For this reason, make sure that the permissions on the directory containing the command file are set appropriately.

Using the command file

The Wrapper will attempt to obtain a read/write lock on the file when the command file is opened. Once it is opened, all commands will be executed in order and then the file will be deleted at the completion of the commands.

External processes which create command files should always open the command file in "append" mode. This way, if the file does not exist, it will be created newly, but if it already exists, then any new commands will be appended.

The Wrapper will try several times for up to a second to open the command file once it has been determined that it exists. This is done to avoid problems while another process is in the process of writing the file. If the file remains locked for longer than a second, a warning message will appear in the log file. This will not affect the operation of the Wrapper, but to avoid the warnings, it is important that the file be locked as briefly as possible.

The file is formatted as a text file with a single command on each line. Possible commands include:

  • STOP {EXIT_CODE} :

    Requests that the Wrapper shut down cleanly. The optional {EXIT_CODE} can be used to specify the exitCode when the Wrapper actually shuts down.

  • RESTART :

    Requests that the Wrapper restart its JVM. This can be used in combination with the wrapper.restart.reload_configuration property to cause the Wrapper to reload its configuration and then launch a new JVM reflecting the changes. Ignored if the JVM is not running.

  • PAUSE :

    Requests that the Wrapper be paused. Only supported when the wrapper.pausable property is TRUE.

  • RESUME :

    Requests that the Wrapper be resumed. Only supported when the wrapper.pausable property is TRUE.

  • SUSPEND_TIMEOUTS {TIME} (Since version 3.5.40) (Standard / Professional Edition) :

    Tells the Wrapper to suspend all timeouts used when the JVM is not responding. {TIME} specifies the number of seconds to suspend timeouts, and should be in the range 1-3600 (1h). This could be used if the Java application needs to perform a long blocking task and avoid having the Wrapper considering the application as unresponsive.

    Timeouts can also be suspended via action properties or the Java WrapperManager.suspendTimeouts() method.

    If several requests to suspend timeouts are made, the number of seconds specified by each request will not be summed. Instead, the newly specified time will replace the remaining suspension time if it is longer, and will be ignored otherwise.

  • RESUME_TIMEOUTS (Since version 3.5.40) (Standard / Professional Edition) :

    Tells the Wrapper to resume all timeouts previously suspended.

    Timeouts can also be resumed via other action properties or the Java WrapperManager.resumeTimeouts() method.

  • DUMP :

    Requests that the Wrapper cause the JVM to produce a thread dump. The results can be viewed in the Wrapper log file. Ignored if the JVM is not running.

  • GC (Since version 3.5.7) :

    Requests the JVM to perform an immediate full garbage collection sweep. Be aware that doing this frequently can affect performance of the JVM as a full sweep will often cause all threads to freeze for the duration of the GC. Ignored if the JVM is not running.

  • CONSOLE_LOGLEVEL {LOG_LEVEL} :

    Changes the console loglevel of the Wrapper.

  • LOGFILE_LOGLEVEL {LOG_LEVEL} :

    Changes the log file loglevel of the Wrapper.

  • SYSLOG_LOGLEVEL {LOG_LEVEL} :

    Changes the syslog or Event Log loglevel of the Wrapper.

Additional testing commands are also available if and only if the wrapper.commandfile.enable_tests property is TRUE. These commands are disabled by default for safety as some of them could cause security or stability problems for the Wrapper and your application.

Possible testing commands include:

  • ACCESS_VIOLATION (Since version 3.5.2) :

    Causes the Wrapper process itself to crash and thus fail to shutdown cleanly. When this happens, the JVM should immediately detect that the Wrapper is gone and shut itself down cleanly. Nothing after the access violation will be retained in the Wrapper log file. This is useful for testing how the Wrapper, JVM, and external systems behave if the Wrapper were to crash.

  • CLOSE_BACKEND (Since version 3.5.26) :

    Causes the backend connection with the JVM to be immediately closed. This is useful for testing the JVM's ability to reconnect with the Wrapper. Ignored if the JVM is not running.

  • CLOSE_SOCKET (Since version 3.5.0) :

    Causes the backend socket with the JVM to be immediately closed. This is useful for testing the JVM's ability to reconnect with the Wrapper. Ignored if the JVM is not running.

    Since version 3.5.26, this is an alias to "CLOSE_BACKEND".

  • PAUSE_LOGGER {seconds} (Since version 3.5.11) :

    Causes the Wrapper to pause the next line of log output for the number of seconds specified. This is useful for testing the Wrapper and JVM's ability to handle delays in logging code. The {seconds} parameter can be in the range of "1" to "3600", or "0" (zero) for indefinite. This command is disabled for safety unless wrapper.commandfile.enable_tests is TRUE.

  • PAUSE_THREAD {THREAD} {TIME} (Since version 3.5.8) :

    Causes the specified Wrapper thread with the following parameter to be paused for a fixed amount of time. This is useful for testing how the Wrapper behaves under high load situations which might cause one or more of the Wrapper's threads to be starved of CPU. The most common cause of long pauses is high IO wait times when doing operations like logging.

    Mandatory {THREAD} parameter:

    The {THREAD} parameter is required for the property value PAUSE_THREAD, and can have one of the following values:

    • MAIN :

      The main Wrapper thread, including monitoring and pinging the JVM process.

    • TIMER :

      The timer thread which exists if the wrapper.use_system_time property is FALSE.

    • JAVAIO :

      The Java IO thread which exists if the wrapper.javaio.use_thread property is TRUE.

    • EVENT :

      The thread used to process all event actions. Only available in the Professional Edition.

    Optional {TIME} parameter:

    The optional {TIME} parameter for the property value PAUSE_THREAD is used to specify the number of seconds which the thread will be delayed. Valid values are "-1", or "0" (zero) to "3600" seconds.. A value of "-1" will cause the pause to wait indefinitely. A value of "0" (zero) will have no effect, and larger values will pause for the specified number of seconds. The default value is "-1".

    While the MAIN thread is paused, the Wrapper will be unresponsive so it may be necessary to forcibly kill the Wrapper's process to recover prior to the pause time expiring.

wrapper.commandfile.enable_tests

Compatibility :3.5.0
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/OSIBM z/Linux

Some of the commands related to testing are disabled by default for security reasons. Setting this property to TRUE will make it possible to use test commands. The default value is "FALSE".

Example:
wrapper.commandfile.enable_tests=FALSE

The following Test Commands can be valid:

  • PAUSE_LOGGER {seconds} (Since version 3.5.11) :

    Causes the Wrapper to pause the next line of log output for the number of seconds. See full description above.

  • PAUSE_THREAD {THREAD} {TIME} (Since version 3.5.8) :

    Causes the specified Wrapper thread with the following parameter to be paused for a fixed amount of time. See full description above.

  • CLOSE_SOCKET (Since version 3.5.0) :

    Causes the backend socket with the JVM to be immediately closed. See full description above.

NOTE

Be aware that some test commands can cause the Wrapper or the JVM to become unstable. These are meant only for testing and should never be enabled in production servers.

wrapper.commandfile.poll_interval

Compatibility :3.5.31
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/OSIBM z/Linux

The regular interval at which the existence of the command file is tested can be controlled by using this property. The default value is 5 seconds, with valid values in the range of "1" to "3600" seconds".

Example:
wrapper.commandfile.poll_interval=5

wrapper.command.poll_interval

Compatibility :3.2.0 (Deprecated as of 3.5.31)
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/OSIBM z/Linux

WARNING

Use of this property has been deprecated as of Wrapper version 3.5.31 in favor of the wrapper.commandfile.poll_interval property.

The regular interval at which the existence of the command file is tested can be controlled by using this property. The default value is 5 seconds, with valid values in the range of "1" to "3600" seconds".

Example:
wrapper.command.poll_interval=5

Reference: Command File