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.

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::


Environment Variable Default ValueSELinux compliant ValueNotes
Log FilesJS7_CONTROLLER_LOGS$JS7_CONTROLLER_DATA/logs/var/log/controllerThe sub-directory controller has to be created and assigned permissions for write access by the Controller's run-time account.
PID File

JS7_CONTROLLER_PID_FILE_DIR

$JS7_CONTROLLER_LOGS/var/run[/js7]If the /var/run directory is write-protected then this suggests to create a js7 sub-directory that is owned to the Controller's run-time account.

JS7_CONTROLLER_PID_FILE_NAMEcontroller.pid
If a common directory such as /var/run is used then users might choose a more speaking name for the Controller's PID file.

Controller systemd Service File

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

Example for systemd service file
[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.

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:


Environment Variable Default ValueSELinux compliant ValueNotes
Log FilesJS7_AGENT_LOGS$JS7_AGENT_DATA/logs/var/log/agentThe sub-directory agent has to be created and assigned permissions for write access by the Agent's run-time account.
PID File

JS7_AGENT_PID_FILE_DIR

$JS7_AGENT_LOGS/var/run[/js7]If the /var/run directory is write-protected then this suggests to create a js7 sub-directory that is owned to the Agent's run-time account.

JS7_AGENT_PID_FILE_NAMEagent.pid
If a common directory such as /var/run is used then users might choose a more speaking name for the Agent's PID file.

Agent systemd Service File

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

Example for systemd service file
[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.

FEATURE AVAILABILITY STARTING FROM RELEASE 2.5.0

JOC Cockpit Installation

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

Starting headless installation of the JOC Cockpit on Unix systems with 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/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.
      • 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:

Example for systemd service file
[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.