Introduction
Introduction

Introduction / FirstSpirit Server control / Unix

Controlling the FirstSpirit Server in Linux operating systems

General information

Table of contents

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 (“fs5” or “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 e-Spirit via the update archive (for existing installations):

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

Important 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) Selecting the control file

At the moment, the installation and update archives each contain two control files for Linux and Windows.

The new fs-server control file has a more extensive range of functions than the fs5 control file, but is in the EAP phase, so cannot yet be recommended for use in live environments.

Please continue to use the fs5 control file for live environments.

(The fs-server.bat and fs5.cmd control files are only needed for Windows operating systems – see Controlling in Windows.)

The fs-server control file (EAP)

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

Important Since the fs-server control file is still in the EAP phase, it is not yet recommended for use in live environments. Please use the fs5 control file in live environments.

The fs5 control file

Recommended for use in live environments

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

fs@fs_example:~$ fs5
Usage: /home/fs_example/firstspirit/bin/fs5 [ console | start | stop | restart | status | 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.
status Query the current status.
dump Request a Java thread dump if running.

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

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

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

~FS/bin/fs-server install

or, alternatively, the command:

~FS/bin/fs-server installrun
Important 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 RUN_AS_USER environment variable is used when installing the systemd service to specify the user (see section Creating a user) that is to be used for the process:

RUN_AS_USER=fs ~FS/bin/fs-server install

fs is the system user created for operation of the FirstSpirit Server (see above) and ~FS is a placeholder for the installation directory.

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

The administrator is responsible for installing the corresponding service for the fs5 control file. A template for SysVinit is available in ~FS/bin/fs5.init.

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.

Example: Controlling the server via SystemVinit (fs5 only)

SystemVinit: Configuring a service

As an alternative to the systemd method described above, a template for an init script is available in ~FS/bin/fs5.init for systems using the (older) SystemVinit system. To ensure that FirstSpirit will also start automatically via this script when the Unix server starts, it must be copied to the corresponding location and adapted:

cp ~FS/bin/fs5.init /etc/init.d/fs5

Two lines must be adapted in the file:

FSDIR=@@FSDIR@@
FSUSER=@@FSUSER@@

Enter the installation directory (identified here as ~FS) in the FSDIR line and enter the fs system user created earlier for operation of the FirstSpirit Server in FSUSER.

The FS_JAVA_HOME environment variable can be set using an export instruction in the init script (before the case block):

export FS_JAVA_HOME=%JAVA_HOME%

For

SystemVinit: Controlling the server (under a separate system user account) (fs5 only)

The server is controlled with the same commands as for systemd, just as an init script call. So the start looks like this:

/etc/init.d/fs5 start

The FirstSpirit Server can also be controlled from a standard user account, provided that the user has the appropriate write permissions – see the section Creating a user.

If you are logged on as the corresponding user, simply call the ~FS/bin/fs5 script instead of the system init script, using the same parameters (start, stop, restart, and status).

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

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

or:

fs5 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

or:

fs5 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 Developer API).

© 2005 - 2020 e-Spirit AG | All rights reserved. | FirstSpirit 2020-07 | Data privacy | Imprint | Contact us