Controlling the FirstSpirit Server in Windows operating systems

General information

Java, the Java Service Wrapper, and the corresponding control files for starting and stopping the FirstSpirit Server (or the Java VM) are required to operate the FirstSpirit Server.

The desired actions, such as:

• starting the FirstSpirit Server
• stopping the FirstSpirit Server
• restarting the FirstSpirit Server
• generating thread dumps, etc.

are forwarded to the JVM by the control file fs-server.bat.

Providing the control files

Providing via the fs-update-[version].tar.gz update archive

The Java Service Wrapper and corresponding, latest version of the control files are provided by Crownpeak via the update archive (for existing installations):

The archive can be downloaded (for access data, please contact Technical Support).

The control files (fs-server and fs-server.bat) must not be changed.

Unpacking the archive in the installation directory

The archive must first be unpacked in the available FirstSpirit Server installation directory.

The archive itself is unpacked first using a zip tool such as 7-zip or IZArc, then the content of the .tar file obtained in this step must be unpacked as well.

Once the archive has been unpacked, the user and group permissions of the unpacked files must be viewed and adapted, if necessary.

Step 1) Activating maintenance mode

All clients should be logged off before the actions are started.

You can activate maintenance mode before starting and stopping the FirstSpirit Server.

Step 2) The fs-server.bat control file

At the moment, the installation and update archives each contain one control file for Linux and Windows.

(The fs-server control file is only needed for Linux operating systems – see Controlling in Linux.)

The range of functions of the fs-server.bat control file:

• console: Starts the FirstSpirit Server in the current console.
• start: Starts the FirstSpirit Server via a Windows system service.
  The FirstSpirit Server must first have been installed as a Windows system service in order to use the command (see install).
• stop: Stops the FirstSpirit Server via a Windows system service.
  The FirstSpirit Server must first have been installed as a Windows system service in order to use the command (see install).
• restart: Restarts the FirstSpirit Server via a Windows system service.
  The FirstSpirit Server must first have been installed as a Windows system service in order to use the command (see install).
• status: Outputs the current status of the FirstSpirit Server.
• install: Installs the FirstSpirit Server as a Windows system service.
• installstart: Installs the FirstSpirit Server as a Windows system service, then starts the FirstSpirit Server.
• remove: Uninstalls the FirstSpirit Server as a Windows system service.
• setup: Registers the Java Service Wrapper in the Windows event log.
  The log level is defined with the wrapper.syslog.loglevel= parameter and should not be set too high (see wrapper.syslog.*).
• teardown: Unregisters the Java Service Wrapper from the Windows event log again.

A Java Service Wrapper with version 3.5.42 or higher is required to use the fs-server.bat control file:

• If you use the FirstSpirit update directory, you will always receive a current version of the wrapper and the corresponding control files.
• You can find the version of the Java Service Wrapper currently being used on the server via FirstSpirit ServerMonitoring. The “wrapper version” is displayed under “Basic information (system)”, which can be found in ServerMonitoring – Overview – State.
• If the wrapper version used does not correspond to the version recommended by the FirstSpirit Server, this is indicated by the red font and the term outdated. This is also recorded in the fs-wrapper.log file.
  In this case, the Java Service Wrapper should be updated promptly (see Updating the FirstSpirit backend).

Step 3a) Controlling the server via a Windows system service (recommended)

Installing the service and starting the server

The FirstSpirit Server can be started via a Windows system service in Microsoft Windows operating systems.

To do this, open the command line in Windows, switch to the ~FS/bin folder, then install and start the Windows system service using this call:

~FS\bin\fs-server installstart

~FS here is the installation directory for the FirstSpirit Server.

Administrator permissions are required to call fs-server installstart in Windows.

Note: If the name of the Windows system service has changed, the service with the old name must be uninstalled first: ~FS\bin\fs-server remove Then the service with the new name is installed: ~FS\bin\fs-server install

All subcommands can then be executed via the Windows system service or the command line according to the following syntax:

~FS\bin\fs-server [reload|restart|start|status|stop|...]

e.g., starting the FirstSpirit Server:

~FS\bin\fs-server start

Configuration of the Windows system service

The Windows service configuration found in the fs-wrapper.isolated.conf file can be adapted using the wrapper.ntservice.* parameter (see wrapper.java.command).

Step 3b) Controlling the server without a Windows system service

Alternatively, the FirstSpirit Server can be started using this call in the current console (without using a system service):

~FS\bin\fs-server console

The server can be shut down via the console window using the shortcutCtrl+C.

All subcommands can then be executed via the command line according to the following syntax:

~FS\bin\fs-server [reload|restart|start|status|stop|...]

Step 3c) Restarting the server via FirstSpirit ServerMonitoring

The FirstSpirit Server can also be easily controlled via FirstSpirit ServerMonitoring. The FirstSpirit Server can be restarted under ServerMonitoring – FirstSpirit – Control.

However, this control does not currently allow for any other commands (like the control files), nor for log outputs or notifications.

Step 4) Error diagnosis and monitoring

Logging/Log files

If problems occur when starting the FirstSpirit Server or once it has been started, the fs-server.log and fs-wrapper.log log files in ~FS/log provide detailed information about the cause of the problem.

If the Java VM will not start, only the fs-wrapper.log is updated.

You can also contact Technical Support for a more detailed analysis and evaluation of the log files.

Creating and analyzing thread dumps

FirstSpirit ServerMonitoring provides another option for analysis. The thread dumps created with the threads functionality can be analyzed here and displayed in a prepared view.

Outputting the service status

Information about the service status can be output via the command:

~FS\bin\fs-server.service status 

Run level

When a FirstSpirit Server starts, information about the current run level is available.

The run levels are output in various locations:

• as a log output in the fs-server.log or fs-wrapper.log file
• as a value [number] in the ~FS/.fs.lock file

These run levels can indicate whether and/or when a server functionality is available:

• SHUTDOWN (run level 0)
  The server has been shut down.
  Note: The ~FS/.fs.lock file is not available in this run level.
• IN_PROGRESS (run level 20)
  The server is starting or being shut down; no functionalities are available with certainty.
• CORE_STARTED (run level 40)
  The basic functionalities are available; the server can be accessed via the SOCKET port.
• ROOT_WEBAPP_STARTED (run level 60)
  The server can now be accessed via the HTTP port as well.
• CORE_WEBAPPS_STARTED (run level 80)
  The global web applications are available.
• STARTED (run level 100)
  All FirstSpirit functionalities are available.

It is possible to respond via the API for example, in this run level (RunLevelAgent interface, de.espirit.firstspirit.agency package, FirstSpirit Access API).