Overview
The most convenient way to start your pulse™ server (or agent) is by installing it as a service, so that it will automatically start when the host machine boots. Pulse supports running as a service on most common architectures, either as a Windows NT service or via an init script (on Unix-like systems). Because a native binary is used to integrate with the underlying system, not all architectures are supported.
Configuration
Pulse uses the Java Service Wrapper
to integrate as a native service. All configuration of the service is thus controlled by the wrapper config file $PULSE_HOME/bin/wrapper.conf. Most configuration is common to both Windows and Unix-like services. System-specific configuration is described in the section for that system.
Java Command
By default, the wrapper is configured to locate a Java VM at $JAVA_HOME/bin/java. To control the Java runtime used to launch pulse™, change the value of the parameter wrapper.java.command at the start of the config file. For example:
wrapper.java.command=/usr/local/jre/bin/java
Additional JVM Parameters
To pass arbitrary additional parameters to the pulse™ JVM, add parameters names wrapper.java.additional.<n> where <n> is the number of the parameter. By default, the parameters look something like:
wrapper.java.additional.1=-Dpulse.home=..
wrapper.java.additional.2=-Djava.awt.headless=true
wrapper.java.additional.3=-Djava.util.logging.config.class=com.zutubi.pulse.logging.ConsoleConfig
To enable system assertions, for example, add a fourth parameter:
wrapper.java.additional.4=-esa
Maximum Heap Size
By default, pulse™ is configured with a maximum heap size of 512MB. To adjust the maximum heap size, set the property wrapper.java.maxmemory. For example, to set it to 1GB:
wrapper.java.maxmemory=1024
Running as a Windows Service
Installation
When you install pulse™ using the Windows installer package, it is automatically installed as a service for you. Start menu items are added to start and stop the service, and it may also be controlled using the normal Windows service tools.
If you install via another means, you can still install the Windows service using the batch file $PULSE_HOME/bin/install-service.bat. Once the service is installed in this manor, it may be started and stopped using the normal Windows service tools. To uninstall the service (without uninstalling pulse™ itself), run $PULSE_HOME/bin/uninstall-service.bat.
Configuration
 | Note
Before making any changes to Windows service parameters, first uninstall the service using uninstall-service.bat. After your changes are made, install the service once more with install-service.bat. Failure to do so may mean some changes are not correctly applied. |
User
By default, the pulse™ Windows serice will run as the LocalSystem user. You can configure the user via the wrapper.ntservice.account property. Note that you must include both the domain and account name in the form <domain>\<account>. For the default domain, use .\<account>. For example, to use the account "pulse" in the default domain:
wrapper.ntservice.account=.\pulse
See http://wrapper.tanukisoftware.org/doc/english/prop-ntservice-account.html for details and troubleshooting information.
Running as a Unix Service
Installation
The pulse™ Unix service is implemented using a standard init script located at $PULSE_HOME/bin/init/sh. To install the script, create a symbolic link in /etc/init.d that points to it, for example:
# ln -s $PULSE_HOME/bin/init.sh /etc/init.d/pulse
Note that you should not take a copy of this script, as it uses its own location to determine the location of pulse™. The next step is to link the pulse script into the appropriate runlevel directories (e.g. /etc/rc*.d) so that pulse™ will be started and stopped automatically. The method for doing this is system-dependent. If your system supports the chkconfig command, it may be used to add the service:
To uninstall the service, simply remove the symbolic links created when installing it.
Control
The init script can also be used to control pulse™ from the command line. All common init script commands are supported, in particular start, stop and restart. For example, to manually stop the pulse™ daemon:
Configuration
User
By default, the Unix service will run as the user that invokes the init script, which is likely to be root. This is undesirable for security reasons, thus a mechanism is available to run as a specified account. The account is configured by setting the RUN_AS_USER variable in the init script (a commented line with this variable can be found in the original script). For example, to run as the user "pulse", edit the commented line to read:
Note that the account must have read and write access to the $PULSE_HOME and data directories.
Troubleshooting
The wrapper will log both its own status information and the output of the pulse™ process to a file named $PULSE_HOME/logs/wrapper.log. This file is the first place to check if you are having trouble launching pulse™ as a service. You may also find useful information in the pulse<n>.<m>.log files in the same directory.
