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 a 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. Control actions are executed by a shell script or a system service.

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 uncompressed (G(un)zip) and unpacked in the available FirstSpirit Server installation directory.

Example call for the update archive using Linux:

~/firstspirit5$ tar xvfz fs-update-[version].tar.gz

The tar archive zip (*.tar.gz) is unpacked with the xvfz tar option.

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

Step 1) Creating a user

We recommend creating a separate system user for the FirstSpirit Server and not starting the FirstSpirit Server as root.

The system user fs is created in this example.

useradd fs

The FirstSpirit Server must be able to adapt files in several locations within its installation directory. The easiest way is to allow it to write everywhere in its installation directory:

chown -R fs:fs ~FS

~FS here serves as a placeholder for the server installation directory.

Step 2) 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 3) The fs-server control file

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

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

The range of functions for the fs-server control file can be called up in the command line using the integrated help function (Usage, Command syntax, Commands), via the fs-server call, for example:

fs@fs_example:~$ fs-server 
Usage: /home/fs_example/firstspirit/bin/fs-server [ console | start | stop | restart | condrestart | status | install | installstart | remove | dump ] 
Commands: 
console Launch in the current console. 
start Start in the background as a daemon process. 
stop Stop if running as a daemon or in another console. 
restart Stop if running and then start. 
condrestart Restart only if already running. 
status Query the current status. 
install Install to start automatically when system boots. 
installstart Install and start running as a daemon process. 
remove Uninstall. 
dump Request a Java thread dump if running.

A Java Service Wrapper with version 3.5.42 or higher is required to use the fs-server 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).

fs-server-custom.shconf optional configuration file

The fs-server-custom.shconf file can be used

to define the user with which the FirstSpirit Server is to be started
to define the path to the Java version.

The file is not updated automatically when the FirstSpirit backend is updated and is therefore not included in the fs-update-[version].tar.gz file. For servers that have already been installed, the file can be extracted from the fs-install-[version]*.tar.gz file.

In the file, the corresponding lines must then be uncommented (# at the start of the line removed) and the required values entered.

RUN_AS_USER=<Username>
export FS_JAVA_HOME=<path to java>

Step 4) Controlling the server

The control files support control of the FirstSpirit Server in various init systems.

These are currently supported:

systemd
Upstart
SystemVinit

There follows a description of how to install the system service and control the FirstSpirit Server using the systemd init system as an example.

The system service can be installed and the FirstSpirit Server controlled in the same way for other init systems as for systemd. The individual commands, the installation location, and the configuration may vary however, depending on which init system is used.

It is not possible to provide a full manual at this point. Please consult the manuals for systemd, Upstart, and SystemVinit, in particular the information about hardening and security.

Example: systemd

All large Linux distributions use systemd to control system services. Compared to the alternative, SysVinit, systemd is faster, more flexible, and allows system services to start simultaneously, for example.

systemd: Requirements

For use with the fs-server control file:

The pidof program should have been installed:
The fs-server control files use pidof as an internal program. The program should have been installed in the system to enable the control files to work properly.
The systemd PAM (pluggable authentication modules) module should have been installed and registered for the FirstSpirit user session (e.g., libpam-systemd in Debian). (The module is required for identifying the systemd process.)

Crownpeak recommends using only the regular systemctl services to control the FirstSpirit Server. The system does not support systemd and sysctl substitutions (such as “Fake Systemd” or “docker systemctl replacement”), so using them could cause problems.

systemd: Installing the service and starting the server (under a separate system user account)

The service is installed via the command line, for the fs-server control file using the command:

~FS/bin/fs-server install

or, alternatively, the command:

~FS/bin/fs-server installrun

Only relevant for an installation using systemd:
When using installrun, the systemd overwrites must be available in /etc/systemd/system/fs-server.service.d/override.conf prior to execution
(see also systemd: Configuration via unit files).

Under a separate system user account: For security reasons, processes should not be executed with root permissions in Linux. The control script does require root permissions in order to run, but the process itself is executed in a user context.

The fs-server-custom.shconf optional configuration file can be used to specify the user for the process (see section Creating a user).

Once the systemd service has been installed, only systemd is used for control, i.e., systemctl is used even when fs-server is called in the user account (the command may differ if a different init system is used).

The user must have sufficient permissions in systemd to start and stop the systemd service, otherwise the user will be asked for the root password. It is not possible to provide a full manual on configuring user permissions (e.g., using polkitd) at this point. Please consult the manual for systemd.

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

systemctl [reload|restart|start|status|stop|...] fs-server

or, alternatively, via:

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

e.g., starting the FirstSpirit Server:

systemctl start fs-server

or:

~FS/bin/fs-server start

For information about installation and configuration, see also Preparing the operating system (Linux) (→Installation Instructions).

systemd: Configuration via unit files

systemd manages its services via units. The files that initialize and start a unit (in this case, the FirstSpirit Server) during booting are called unit files. Unit files are not executable files, but configuration files similar to Windows ini files.

The ~FS/bin/fs-server install command is used to automatically generate the systemd service file and save it, usually in /etc/systemd/system.

Existing unit files can be expanded with the edit command; to do this, the corresponding systemd service file must be specified, e.g.:

systemctl edit fs-server.service

An example of a simple configuration (fs-server) looks like this:

[Service]
Group=fs
UMask=0027
LimitNOFILE=10000
Environment="FS_JAVA_HOME=/opt/openjdk/lts"

Environment variables are defined in the section [Service]:

UMask: The value configured here should be based on the default setting of the fs-wrapper.conf configuration file (see wrapper.umask). The default value for this parameter is 0027. This means that the “Group” user class has read permissions and the “Others” user class has no permissions.
LimitNOFILE: This variable can be used to define the resource limits, i.e., the maximum number of file handles that may be open simultaneously under the FirstSpirit Server user account (see Preparing the operating system (Linux) (→Installation Instructions)).
Environment: The directive Environment= can be inserted in the service block to declare the FS_JAVA_HOME variable, for example, in the systemd service file.

Step 5) 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 a stack dump

The command:

fs-server dump

is used to create an up-to-date thread dump and write it according to ~FS/log/fs-dump-DATUM-UHRZEIT.log.

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-server 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).

Print version | Page start