Running dm Server as daemon

On UNIX platforms, you can use nohup $SERVER_HOME/bin/startup.sh& to allow the dm Server’s shell process tree to become child of the init (or launchd) process and thus survive SIGHUP signal.

Configuring dm Server as Windows service

On Windows platforms, you can use Project Kenai’s winsw to run the dm Server as Windows service. The service wrapper can execute arbitrary executable file and pass it different command line arguments on service startup and shutdown.

To get started, download winsw from its homepage at http://projectkenai.com/projects/winsw/pages/Home. Once you have downloaded the winsw.exe, rename it to, for example, dmss.exe and copy it to %SERVER_HOME%\bin. The listing of %SERVER_HOME%\bin should now show files in Listing 1.

Listing 1. Files in %SERVER_HOME%\bin

C:\>dir %SERVER_HOME%\bin
 Volume in drive C has no label.
 Volume Serial Number is 7408-8BB9

 Directory of C:\opt\springsource-dm-server-2\bin

24/07/2009  14:49    <dir>          .
24/07/2009  14:49    </dir><dir >          ..
24/07/2009  14:21            31,744 dmss.exe
14/07/2009  16:42               953 jconsole.bat
14/07/2009  16:42             1,071 jconsole.sh
14/07/2009  16:42             2,468 jmxPermissions.vbs
14/07/2009  16:42               291 setupClasspath.bat
14/07/2009  16:42               658 setupClasspath.sh
14/07/2009  16:42             1,017 shutdown.bat
14/07/2009  16:42             1,243 shutdown.sh
14/07/2009  16:42             3,561 startup.bat
14/07/2009  16:42             3,459 startup.sh
              15 File(s)         50,298 bytes
               2 Dir(s)   1,316,659,200 bytes free

Because the service wrapper (now renamed to dmss.exe) executes the same executable to start or stop the service, we must create an executable that can decide whether to start or stop the dm Server based on command line argument. Let’s call this executable dmscontrol.bat; if we pass the run command line argument, we want it to call the startup.bat. Similarly, if we pass the stop command line argument, we want it to call the shutdown.bat. We show the entire source code of dmscontrol.bat below:

@ECHO OFF

IF "%~1"=="run" CALL %SERVER_HOME%\bin\startup.bat
IF "%~1"=="stop" CALL %SERVER_HOME%\bin\shutdown.bat

The final piece of the puzzle is the service configuration file. The service wrapper will look for a configuration file whose file name matches the executable of the service wrapper, but with xml extension. In our case, dmss.exe will look for dmss.xml. Take a look at Listing 2, which shows the dmss.xml service configuration file.

Listing 2. The service wrapper configuration file

01 <service>
02  <id>dmserver2</id>
03  <name>dm Server 2.0</name>
04  <description>
05    Controls the SpringSource dm Server 2.0
06  </description>
07  <env name="JAVA_HOME"
08    value="c:\Program Files\Java\jdk1.6.0_14" />
09  <executable>%SERVER_HOME%\bin\dmscontrol.bat</executable>
10  <startargument>run</startargument>
11  <stopargument>stop</stopargument>
12 </service>

02 The service identifier, it must start with a letter and must not contain spaces
03 The service name, this is the name that the Services listing will show
05 The description of the service that the Services listing will show
08 We need to set the JAVA_HOME environment variable for the service
09 The path to the service executable
10 The command line argument that the service wrapper will pass to the service executable to start the service
11 The command line argument that the service wrapper will pass to the service executable to stop the service

Before we can install the service, we must check that the permissions on the dm Server’s directory allow access from the service’s account. By default, the service will run under the SYSTEM account, therefore, we must give the SYSTEM account full control of the %SERVER_HOME% directory. Once this is done, we must execute the following commands:

cd %SYSTEM_HOME%\bin
dmss install

This will install the dm Server service, the proof is in the pudding – the Services listing in Figure 1.

Figure 1. The dm Server service appearing in the Services listing

Notice in the Services listing that the name matches the contents of the <name> element in the dmss.xml file and description matches the contents of the <description> element in the configuration file. We can now start the service; when the service starts, its shell process will become child of the services.exe process (see Figure 2).

Figure 2. Process tree showing the dm Server’s dmss.exe wrapper

You can verify that the service starts dm Server successfully by going to http://localhost:8080, you should see the splash screen you saw when you started the dm Server by running %SERVER_HOME%\bin\startup.bat.

Note on security

Regardless of whether you are running dm Server on UNIX or Windows, you should create a separate user account to run it. Having a separate account to run the dm Server will help limit the damage a potential successful attacker may cause.
Now that we have explored the different ways to start and run dm Server, let’s find out how we can control it once it’s running. We will begin by looking at the simple web administrative console, followed by the more complex OSGi console.

And there you have it!

Whether you’re running UNIX or Windows, you can now configure dm Server to survive a logoff!