When the Wrapper is launched, it is very careful about making sure that the working directory is in a known and constant state. This helps to guarantee that there will be no path related problems caused by a user launching the Wrapper from various locations.

On all platforms, the Wrapper will force its working directory to the directory where its binary is located immediately on startup. This is critical because processes are launched by their parent OS with the same working directory as their parent process.

This means that the working directory would be different in all three of the following commands: bin\wrapper.exe, .\wrapper.exe, ..\bin\wrapper.exe. When running as a Windows Service, the working directory would be set to the Windows system32 directory.

This inconsistency in the working directory would make it impossible to make use of any relative paths within the Wrapper's configuration file.

wrapper.logfile=C:\Program Files\myapp\logs\wrapper.log

Notice how an absolute path needs to be set to a location that is unique for each installation. This means that an installer would be required for the application, and that the installer would need to go in and modify the configuration files. If the user ever moves the application on their hard drive, then the configuration would be broken and no longer work.

wrapper.logfile=../logs/wrapper.log

Relative paths, on the other hand, are very useful. They will work no matter where the application is installed. The paths can also be defined using forward slashes so the exact same configuration file will work both on Windows and UNIX platforms without modification. The configuration will also work correctly even if the user moves the entire application to another location or drive.

Flexible Work "wrapper.working.dir":

There are times however where having the working directory set to the location of the Wrapper binary makes it impossible to run some applications cleanly. An example is an application which expects the working directory to be at the root of the file system. The only way to run such an application under the Wrapper would be to place the Wrapper binary and scripts in the root directory. Not something that most system administrators would want to do.

To allow such exceptional cases, the wrapper.working.dir property was added. It is very important to understand exactly how this property works to avoid problems.

1.Relative path to Wrapper binary:

The wrapper.working.dir property can be specified either in the configuration file "wrapper.conf" or as a parameter to the Wrapper binary. However, the property does not take effect until AFTER the Wrapper's configuration file has been completely loaded. This means that the location of the wrapper.conf file and any include files (cascading style) referenced therein must still be referenced using locations relative to the Wrapper binary. This is necessary to make sure that the configuration file can be loaded reliably.

Any environment variables referenced in the configuration file will be replaced as the individual lines of the configuration file are loaded. This is an important point if they are being used to construct path values within properties.

2.Relative path to a new working directory:

Any and all paths defined in OTHER properties specified either from the command line or within the wrapper.conf file will then be relative to the location specified by the wrapper.working.dir property.

Confused yet? An example or two is in order.

Windows will be used as an example, but the issues are all the same for Linux/UNIX platforms.

C:\myapp\
    bin\
        wrapper.exe
    conf\
        wrapper.conf
        include.conf
    lib\
        wrapper.dll
        wrapper.jar
        myapp.jar
    logs\
        wrapper.log

Without using the wrapper.working.dir property, the working directory will be located in the C:\myapp\bin directory (the location of Wrapper binary). The Wrapper could be launched using the following command.

bin\wrapper.exe -c ../conf/wrapper.conf

Paths in the wrapper.conf file would be configured as follows. (Note this is not a complete configuration file.):

#include ../conf/include.conf
wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=../lib/myapp.jar
wrapper.java.library.path.1=../lib
wrapper.pidfile=./wrapper.pid
wrapper.java.pidfile=./java.pid
wrapper.logfile=../logs/wrapper.log

Note that all paths are relative to the location of the Wrapper binary "wrapper.exe" file (C:\myapp\bin).

The same directory structure used in the previous example will be reused.

C:\myapp\
    bin\
        wrapper.exe
    conf\
        wrapper.conf
        include.conf
    lib\
        wrapper.dll
        wrapper.jar
        myapp.jar
    logs\
        wrapper.log

This time the wrapper.working.dir property will be set the parent of the bin directory in which the wrapper.exe file is located. This is a location that is commonly referred to as the application HOME directory. C:\myapp in this case.

The wrapper.working.dir property can be specified either on the command line used to launch the Wrapper, or within the wrapper.conf file. In either case, the specified directory can be absolute or relative. In the case of a relative directory, the directory will be relative to the location of the Wrapper binary. (As the result: = C:\myapp)

wrapper.working.dir=../

This example will specify the new working directory with using wrapper.working.dir property within the wrapper.conf file. So in this case, the command used to launch the Wrapper is unchanged, meaning that the batch files and scripts that are shipped with the Wrapper can be used without any modification.

bin\wrapper.exe -c ../conf/wrapper.conf

When the Wrapper is launched, it immediately sets its own working directory to the location of the Wrapper binary (C:\myapp\bin). Then loads the configuration file "wrapper.conf" file and any include files (cascading style) using that working directory. After the configuration is loaded, the working directory will be changed to the new location specified by the wrapper.working.dir property (C:\myapp\). All future paths including the launching of the JVM will be done using this new working directory.

For this example, the wrapper.conf fragment used above will be modified as follows:

wrapper.working.dir=../
#include ../conf/include.conf
wrapper.java.classpath.1=lib/wrapper.jar
wrapper.java.classpath.2=lib/myapp.jar
wrapper.java.library.path.1=lib
wrapper.pidfile=bin/wrapper.pid
wrapper.java.pidfile=bin/java.pid
wrapper.logfile=logs/wrapper.log

Notice that the location of the include file (cascading style) and wrapper.working.dir property are both relative to the Wrapper binary location (C:\myapp\bin), but all other paths are now relative to the new working directory (C:\myapp\).

The location of the wrapper.working.dir property within the wrapper.conf file is not important as it is not applied until after the entire configuration file has been parsed.

Problems?

If you encounter any problems related to configuring the Wrapper, the first thing that should be done is to enable the wrapper.debug property and rerun the application. Make sure that the application can be run as a console application before attempting to run it as a Windows Service or UNIX Daemon process.

Some applications need the ability to set their working directory to the location from which the application was run. Most servers want to run in a known location, however most command line applications need to know the context of where they are being run. One simple example is the mkdir command. It needs to know where the command is being executed from to be able to decide where to create the new directory.

Starting with Wrapper version 3.5.6, the WRAPPER_INIT_DIR environment variable will keep track of this location.

In most such cases, you would simply want to pass this value off to your application, but still make sure that your application and all of its log files are written in a known location. This can be done by passing the location off to the JVM in a system property.

wrapper.java.additional.1=-myinit.working.dir="%WRAPPER_INIT_DIR%"
wrapper.java.additional.1.stripquotes=TRUE

String s = System.getProperty("myinit.working.dir");
File f = new File(s, "test1/myout.txt");

If, however, you really want to set the Wrapper and its application directory to the current location, this can be handled by setting the working directory to the initial directory location. Be aware that you will most likely want to set the location of any log file, PID file, etc. to an absolute path to make sure they can always be found. The Wrapper's configuration file will still always be loaded relative to the location of the Wrapper binary.

wrapper.working.dir=%WRAPPER_INIT_DIR%

Environment variables are described in more detail on the Working With Environment Variables page. We will cover a few of the issues directly related to working directories here.

The Wrapper sets 2 environment variables that are directly associated with the working directory.

• The WRAPPER_BIN_DIR variable (Since ver. 3.3.0) will always be set to the location of the Wrapper binary on startup. It can be used as a reference point later in the configuration file even if the working directory is modified.

• The WRAPPER_WORKING_DIR variable (Since ver. 3.3.0) is a little confusing and not really useful when referenced from within the Wrapper configuration file. It is always set to the current working directory, and will be set to the value specified with the wrapper.working.dir property. But any reference to the variable in the configuration file will be replaced as the configuration file is loaded. Remember that at that point, the working directory is still set to the location of the Wrapper binary. This environment variable is only useful within the JVM and its child processes when they request the environment variable on a system level.

It is also possible for users to define their own environment variables within the Wrapper configuration file. These are set into the environment as they are parsed. Because of this, you can do some fancy things. In the following example, we will create a MYAPP_HOME variable and then not only set the working directory, but also make use of it in other properties. Note that the environment variable can also be used when loading in the include files (cascading style).

set.MYAPP_HOME=c:\myapp\
wrapper.working.dir=%MYAPP_HOME%
#include %MYAPP_HOME%/conf/include.conf
wrapper.java.classpath.1=%MYAPP_HOME%/lib/wrapper.jar
wrapper.java.classpath.2=%MYAPP_HOME%/lib/myapp.jar
wrapper.java.library.path.1=%MYAPP_HOME%/lib
wrapper.pidfile=%MYAPP_HOME%/bin/wrapper.pid
wrapper.java.pidfile=%MYAPP_HOME%/bin/java.pid
wrapper.logfile=%MYAPP_HOME%/logs/wrapper.log

This method can be used if the wrapper.exe needs to be placed in a location outside of the Application directory structure. If it is a system-wide command for example.