Introduction

This article focuses on the locations for the pid file and logs.

The logs should be stored under /var/log and the pid file under /var/run.

Controller

Nach dem Entpacken des Archivs js7_controller_unix.<release>.tar.gz sollte das Instance-Script ./bin/controller_instance.sh-example nach ./bin/controller_instance.sh umbenannt werden.
Im weiteren wird das Instance-Script zum Starten, Stoppen etc. verwendet. In ihr können Umgebungsvariablen auch die Speicherorte des PID File und der der Protokolle gesetzt werden.

Logs

• Voreinstellung ohne manuellen Eingriff
  • Die Protokolle werden in $JS7_CONTROLLER_DATA/logs geschrieben, wobei in der Voreinstellung für $JS7_CONTROLLER_DATA das ./var Verzeichnis ist.
• Manuelle Konfiguration
  • Im Instance-Script wird mit der Umgebungsvariablen JS7_CONTROLLER_LOGS der Speicherort der Protokolle bestimmt.
    Dieses Verzeichnis muss ggf. manuell angelegt werden und Lese- und Schreibrechte für den Controller User Account haben.

PID File

• Voreinstellung ohne manuellen Eingriff
  
  • Das PID File in $JS7_CONTROLLER_LOGS geschrieben (siehe oben). 
• Manuelle Konfiguration
  • Im Instance-Script wird mit der Umgebungsvariablen JS7_CONTROLLER_PID_FILE_DIR der Speicherort des PID Files bestimmt.
    Dieses Verzeichnis muss ggf. manuell angelegt werden und Lese- und Schreibrechte für den Controller User Account haben.

Agent

Nach dem Entpacken des Archivs js7_agent_unix.<release>.tar.gz sollte das Instance-Script ./bin/agent_instance.sh-example nach ./bin/agent_instance.sh umbenannt werden.
Im weiteren wird das Instance-Script zum Starten, Stoppen etc. verwendet. In ihr können Umgebungsvariablen auch die Speicherorte des PID File und der der Protokolle gesetzt werden.

Logs

• Voreinstellung ohne manuellen Eingriff
  • Die Protokolle werden in $JS7_AGENT_DATA/logs geschrieben, wobei in der Voreinstellung für $JS7_AGENT_DATA das ./var Verzeichnis ist.
• Manuelle Konfiguration
  • Im Instance-Script wird mit der Umgebungsvariablen JS7_AGENT_LOGS der Speicherort der Protokolle bestimmt.
    Dieses Verzeichnis muss ggf. manuell angelegt werden und Lese- und Schreibrechte für den Agent User Account haben.

PID File

• Voreinstellung ohne manuellen Eingriff
  
  • Das PID File in $JS7_AGENT_LOGS geschrieben (siehe oben). 
• Manuelle Konfiguration
  • Im Instance-Script wird mit der Umgebungsvariablen JS7_AGENT_PID_FILE_DIR der Speicherort des PID Files bestimmt.
    Dieses Verzeichnis muss ggf. manuell angelegt werden und Lese- und Schreibrechte für den Agent User Account haben.

JOC Cockpit

Logs

SELinux is an extension to the Linux kernel that provides elaborated access control and support for security policies.

• For compliance with SELinux users should consider use of specific directories for operation of Controller, Agent and JOC Cockpit.
• SELinux suggests the following locations for storing PID files and log files:
  • Log files: /var/log
  • PID files: /var/run
• There is no need using specific SELinux security policies as the JS7 products can be operated in compliance with standard SELinux security policies.

Controller

The location of directories used for the Controller is specified with the Controller Start Script controller_instance.sh.

• For details about the Controller Start Script see JS7 - Controller - Command Line Operation
• For general installation instructions see JS7 - Controller - Headless Installation on Linux and Windows
• SELinux compliant installation is supported by installation scripts, see JS7 - Automated Installation and Update.

Controller Instance Start Script

For SELinux compliance the following settings in the controller_instance.sh script have to be adjusted, see chapter Controller Environment Variables::

Controller systemd Service File

SELinux requries a few changes to the Controller's systemd service file to reflect the PID file directory:

[Unit]
Description=SOS JS7 Controller -id=controller
After=syslog.target
After=network.target

[Service]
# Set JAVA_HOME environment variable if required
# Environment="JAVA_HOME=/opt/java/jdk-17.0.2"
# Environment="JAVA_OPTIONS="
Type=forking
KillMode=process
# default PIDFile = /home/js/controller/var/logs/controller.pid
PIDFile=/var/run/js7/controller.pid
ExecStartPre=+/bin/mkdir -p /var/run/js7
ExecStartPre=+/bin/chown js:js /var/run/js7
ExecStartPost=/bin/sleep 1
ExecStart=/bin/sh -c "/home/js/controller/bin/controller_instance.sh start"
ExecStop=/bin/sh -c "/home/js/controller/bin/controller_instance.sh stop"
ExecReload=/bin/sh -c "/home/js/controller/bin/controller_instance.sh restart"
User=js
StandardOutput=journal+console
StandardError=journal+console
TimeoutStopSec=60
TasksMax=infinity

[Install]
WantedBy=multi-user.target

Explanation:

• Sub-directories in /var/run are ephemeral, i.e. they will be dropped on reboot of the server. If a sub-directory such as js7 is used then it has to be created by the service file. 
• PID File
  • PIDFile=/var/run/js7/controller.pid
  • ExecStartPre=+/bin/mkdir -p /var/run/js7
  • ExecStartPre=+/bin/chown js:js /var/run/js7
• The + preceeding the commands indicates that they will be executed by the root account.
• The commands create the js7 sub-directory and hand-over ownership to the js account and group.

Agent

The location of directories used for the Agent is specified with the Agent Start Script agent_<port>.sh with <port> being the HTTP port that the Agent is operated for.

• For details about the Agent Start Script see JS7 - Agent Command Line Operation
• For general installation instructions see JS7 - Agent - Headless Installation on Unix and Windows
• SELinux compliant installation is supported by installation scripts, see JS7 - Automated Installation and Update.

Agent Instance Start Script

For SELinux compliance the following settings in the agent_<port>.sh script have to be adjusted, see chapter Agent Environment Variables:

Agent systemd Service File

SELinux requries a few changes to the Agent's systemd service file to reflect the PID file directory:

[Unit]
Description=SOS JS7 Agent -port=4445
After=syslog.target
After=network.target

[Service]
# Set JAVA_HOME environment variable if required
# Environment="JAVA_HOME=/opt/java/jdk-17.0.2"
# Environment="JAVA_OPTIONS="
Type=forking
KillMode=process
# default PIDFile = /home/js/agent/var_4445/logs/agent.pid
PIDFile=/var/run/js7/js7_agent_4445.pid
ExecStartPre=+/bin/mkdir -p /var/run/js7
ExecStartPre=+/bin/chown js:js /var/run/js7
ExecStartPost=/bin/sleep 1
ExecStart=/bin/sh -c "/home/js/agent/bin/agent_4445.sh start"
ExecStop=/bin/sh -c "/home/js/agent/bin/agent_4445.sh stop"
ExecReload=/bin/sh -c "/home/js/agent/bin/agent_4445.sh restart"
User=js
StandardOutput=journal+console
StandardError=journal+console
TimeoutStopSec=60
TasksMax=infinity

[Install]
WantedBy=multi-user.target

Explanations are the same as for the Controller's systemd service file.

JOC Cockpit

The location of SELinux related directories is determined by the JOC Cockpit installer.

• For details about the Agent Start Script see JS7 - JOC Cockpit - Command Line Operation
• For general installation instructions see 
  • JS7 - JOC Cockpit - Headless Installation on Linux and Windows
  • JS7 - JOC Cockpit - Installation Using the Graphical Installer for Linux and Windows
  • SELinux compliant installation is supported by installation scripts, see JS7 - Automated Installation and Update.

JOC Cockpit Installation

Users have to perform installation of JOC Cockpit on Unix systems from a user account that can acquire root permissions:

# login as the user account or root
./setup.sh joc_install.xml

Explanation:

• The installer will use sudo to acquire root permissions if a non-root account is used.
• Files in the installation directory will be owned by the root account, Files in the data directory will be owned by the JOC Cockpit run-time account.
• Location of log files
  • The installer will try to look up the /var/log directory:
    • If the directory is available then
      • the
  Konfiguration seitens des Setups mit root-Rechten, d.h. ohne der -u Option
  
  • Der Installer sucht nacheinander nach den Verzeichnissen /var/log.
    • Wird das Verzeichnis gefunden, dann
      • wird das Verzeichnis /var/log/sos-berlin.com/js7/joc angelegt und mit Lese- und Schreibrechte des Jetty User Accounts versehen. directory will be created and will be assigned read/write permissions for the JOC Cockpit run-time account.
      • the wird ein Symlink $JETTY_BASE/logs angelegt, der auf symlink will be created that points to the /var/log/sos-berlin.com/js7/joc zeigt.
      Wird das Verzeichnis nicht gefunden, dann werden die Protokolle in 
      • directory.
    • If the directory is not available then log files will be written to the $JETTY_BASE/logs directory.
  • Alternative configuration
    • Users can manually create the $JETTY_BASE/logs geschrieben. 
• Konfiguration seitens des Setups ohne root-Rechten, d.h. mit der -u Option
  • Die Protokolle werden in das Verzeichnis $JETTY_BASE/logs geschrieben. 
• Manuelle Konfiguration
  • Legen Sie ein Symlink $JETTY_BASE/logs an, der auf das gewünschte Verzeichnis zeigt. 
    Dieses Verzeichnis muss ggf. manuell angelegt werden und Lese- und Schreibrechte für den Jetty User Account haben.

PID File

• • • symlink that points to the directory where log files should be stored. The directory should offer read/write permissions to the JOC Cockpit run-time account.
• Location of the PID file
  • The installer will check the JOC Cockpit's run-time account using the following precedence:
    • The run-time account can be specified with the <entry key="runningUser" value=""/> setting in the joc_install.xml response file during installation.
    • The run-time account is identified from the account running the installer.
  • If JOC Cockpit's run-time account is identified to be
    • the root account then the installer will check if the /var/run directory is writeable to the JOC Cockpit's run-time account and otherwise it will look up the /usr/var/run directory and finally the JETTY_BASE directory.
    • a non-root account then the PID file will be written to the JETTY_BASE directory.
    • JOC Cockpit will write the joc.pid file to the respective directory.
  • Alternative configuration
    • The installer will create the ~/.jocrc file in the home directory of JOC Cockpit's run-time account.
    • This file can be added
      • the JETTY_RUN environment variable that is assigned the directory to which the joc.pid PID file will be written. The directory should offer read/write permissions to the JOC Cockpit's run-time account.
      • the JETTY_PID environment variable that holds an individual path to the PID file, for example /var/run/js7_joc.pid.
    • If a sub-directory to /var/run is used then users should consider that this is an ephemeral sub-directory that will be dropped on server start-up.
    • Consider to check the JETTY_HOME/jetty/bin/joc.service systemd Service File template that is created by the installer and that has to reflect modifications of the PID file location applied after installation. For details see JS7 - systemd Service Files for automated Startup and Shutdown with Unix Systems.

JOC Cockpit systemd Service File

SELinux requries a few changes to the JOC Cockpit's systemd service file to reflect the PID file directory:

[Unit]
Description=Jetty for SOS JS7 JOC Cockpit
After=syslog.target
After=network.target

[Service]
# Set JAVA_HOME environment variable if necessary
# Environment="JAVA_HOME=/opt/java/jdk-17.0.2"
# Environment="JAVA=/opt/java/jdk-17.0.2/bin/java"
# Environment="JAVA_OPTIONS="
Environment="JETTY_RUN=/var/run/js7"
Environment="JETTY_PID=/var/run/js7/joc.pid"
Type=forking
PIDFile=/var/run/js7/joc.pid
ExecStartPre=+/bin/mkdir -p /var/run/js7
ExecStartPre=+/bin/chown ap:ap /var/run/js7
ExecStartPost=/bin/sleep 1
ExecStart=/bin/sh -c "/home/js/joc/jetty/bin/jetty.sh start"
ExecStop=/bin/sh -c "/home/js/joc/jetty/bin/jetty.sh stop"
ExecReload=/bin/sh -c "/home/js/joc/jetty/bin/jetty.sh restart"
User=js
StandardOutput=journal+console
StandardError=journal+console
SuccessExitStatus=143
TimeoutStopSec=60

[Install]
WantedBy=multi-user.target

Explanation:

• Sub-directories in the /var/run directory are ephemeral, i.e. they will be dropped on reboot of the server. If a sub-directory such as js7 is used then it has to be created by the service file. 
• Jetty Environment Variables
  • Configuration
    • Environment="JETTY_RUN=/var/run/js7"
    • Environment="JETTY_PID=/var/run/js7/joc.pid"
  • The variables specify the directory and the path of the PID file used by Jetty.
• PID FileDirectory
  • Configuration 
    • PIDFile=/var/run/js7/joc.pid
    • ExecStartPre=+/bin/mkdir -p /var/run/js7
    • ExecStartPre=+/bin/chown js:js /var/run/js7
  • The + preceeding the commends indicates that they will be executed by the root account.
  • The commands create the js7 sub-directory and hand-over ownership to the js account and group
• Konfiguration seitens des Setups mit root-Rechten, d.h. ohne der -u Option
  • Der Installer sucht nacheinander nach den Verzeichnissen /var/run und /usr/var/run.
    • Wird eines dieser Verzeichnis gefunden, dann wird das Verzeichnis /var/run/joc bzw. /usr/var/run/joc angelegt und mit Lese- und Schreibrechte des Jetty Users versehen.
    • Wird keines dieser Verzeichnisse gefunden, dann wird das PID File in  $JETTY_BASE geschrieben. 
• Konfiguration seitens des Setups ohne root-Rechten, d.h. mit der -u Option
  • Das PID File in  $JETTY_BASE geschrieben.
• Manuelle Konfiguration
  • Im Home-Verzeichnis des Jetty Users wird eine Datei ~/.jocrc vom Installer angelegt.
    In ihr kann mit der Umgebungsvariablen JETTY_RUN ein Verzeichnis für das PID File bestimmt werden.
    Dieses Verzeichnis muss ggf. manuell angelegt werden und Lese- und Schreibrechte für den Jetty User haben.