Introduction

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

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 /var/run/js7 = /home/js/controller/var/logs
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:

• The /var/run directory is ephemeral, i.e. it is 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 FileDirectory
  • PIDFile=/var/run/js7/controller.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.

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

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 /var/run = /home/js/agent/var_4445/logs
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.

FEATURE AVAILABILITY STARTING FROM RELEASE 2.5.0

• 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

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 (not as root)
./setup.sh joc_install.xml

Explanation:

• The installer will use sudo to acquire root permissions. Execution of the above command by the root account is denied.
• 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/var/log/sos-berlin.com/js7/joc directory will be created and will be assigned read/write permissions for the JOC Cockpit run-time account.
      • the $JETTY_BASE/logs symlink will be created that points to the /var/log/sos-berlin.com/js7/joc 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 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.
    • Consider that use of sub-directories to /var/run is discouraged as this is an ephemeral directory that is reverted 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/js7_joc_1.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:

• The /var/run directory is ephemeral, i.e. it is 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/js7_joc_1.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.