TomEE: Running with Systemd

What is systemd?

Systemd is the first background process to run and the last background process to end in the Linux operating system. It has the process id (PID) of 1, meaning that all other background processes (aka daemons) are created by systemd; it is the root background process in a Linux operating system.

Systemd is designed to provide a unified configuration process for bootstrapping Linux processes, enable and disable process, and manage the interface between those processes and user applications.  Developers can configure systemd using standard files called units. Units can be used for defining the initialization process for services, mount points, devices and network sockets.

By defining a systemd unit file for TomEE, the process of starting, stopping, and running TomEE can be greatly simplified.

TomEE systemd unit

The following set of instructions apply only for tomee zip/tar distribution. Docker and OS package manager distributions are outside the scope of this document.

To start the creation of our systemd unit, we have some prerequisites, which are:

• Create the user to run the service
• Make sure which we can read and write in TomEE path

By default, when installing a new service, Linux will create a new user for that service.

For example, on Archlinux – a lightweight Linux distribution – if you install the MySQL, it will create a new user and group called mysql. Linux groups make it easily give permission for additional users to have access to write or read operations on the MySQL path. For our TomEE service we’ll do exactly that, so, before we create our systemd unit we need to create the user and group called tomee.

Create the user and group tomee

Open the terminal and execute the follows command:

$ sudo adduser tomee

When you execute the adduser command you will be asked to enter user password before the user account is created, so input the password which you want for the tomee user. Once the tomee user is created you can see that the user, tomee, was assigned the primary group, tomee, by default.

Fixing TomEE path permission

In order for users to work with TomEE we need to modify the permissions for the tomee group.  Any user added to that group will have the same permissions. To enable proper permissions we need to fix the paths associated with the tomee group.  This will ensure that any user associated with the tomee group can access TomEE files.

For this article, we assume that you installed TomEE inside /opt/tomee path. To grant access permissions to the tomee user and group we will use the chmod command. The chmod command will give the permissions to the:

• tomee user to execute programs and write and read files,
• tomee group to read files and execute programs,
• all other users to read files.

In order to deploy and update wars or the ear, update config files, and edit something in your tomee path you need to provide proper permissions. Execute the following commands:

$ sudo chmod -R 754 /opt/tomee

and then execute the following

$ sudo chown tomee:tomee -R /opt/tomee

After executing the above, any user can read the files, it means everyone will be able to read the config files, logs and etc.

Setting the systemd unit

To run TomEE as a service in any Linux distribution with systemd, we need to set up a new systemd unit file. Start by creating the file with the vi editor using the following command:

sudo vi /etc/systemd/system/tomee.service

Or use any text editor of your choice.  Once the text editor is opened, you need to copy and paste the following script:

[Unit]

Description=Apache TomEE

After=network.target

[Service]

User=tomee

Group=tomee

Type=forking

Environment=JAVA_HOME=/usr/lib/jvm/jre

Environment=CATALINA_PID=/opt/tomee/temp/tomee.pid

Environment=CATALINA_HOME=/opt/tomee

Environment=CATALINA_BASE=/opt/tomee

Environment=CATALINA_OPTS='-server'

Environment=JAVA_OPTS='-Djava.awt.headless=true'

ExecStart=/opt/tomee/bin/startup.sh

ExecStop=/opt/tomee/bin/shutdown.sh

KillSignal=SIGCONT

[Install]

WantedBy=multi-user.target

If your file paths are different you will need to adjust the environment variables to the appropriate values:

• JAVA_HOME to where Java is installed
• CATALINA_HOME to where TomEE is installed
• CATALINA_BASE to where TomEE is installed
• CATALINA_OPTS to options you may want to pass to TomEE
• JAVA_OPTS to options you may want to pass to the Java VM

Save the file and exit.

To be able to use the new systemd configuration, we need to reload it using the following command:

$ sudo systemctl daemon-reload

Now you should be able to use the following commands to perform these operations with the TomEE service:

$ sudo systemctl start tomee
$ sudo systemctl stop tomee
$ sudo systemctl status tomee

The above will start, stop and check the status of the TomEE service.

Tips

The systemd unit files, like the one we created above, define a lot of useful properties which are described in detail in the man pages for systemd:

https://www.freedesktop.org/software/systemd/man/systemd.unit.html

But, here I’ll describe some of the properties and provide tips that can help you to avoid common issues.

The PrivateTmp property

This property is really useful for security perspective. All users are able to write to /tmp, so if an application creates content in /tmp that is guessable (i.e., has a well-known name), someone could create a link file with that name in /tmp and fool the privileged app to unlink or overwrite the destination of the link. Not only do you have to worry about users doing this, but you also have to worry about the applications that the user runs and the services that you have running on your system. There have been several vulnerabilities (CVEs)  reported to the National Vulnerabilities Database (CVEs) on this topic.

If you enable the PrivateTmp property by setting it to true, the systemd will create a new file system namespace for the executed processes and mounts a private /tmp directory inside it, that is not shared by processes outside of the namespace.

So, if you enable PrivateTmp as shown above, which is good, only the ROOT user will be able to generate some information (jstack output) for you.

The drawback to setting PrivateTmp to true is that you cannot generate a thread dump with the tomee user (in our case, the systemd unit was configured for this user), so do not use this property if you need that capability from the tomee user.

By default, for this tutorial, we didn’t configure our tomee.service to enable this security layer, but if you want to do that, just add the property PrivateTmp=true in the [Service] section.

Service dependencies

It is likely that you will want to access a database from your TomEE application. The issue is: We need to have the database running before start our TomEE service.

In the most popular Linux distributions, the package manager will automatically create a service for the database which you installed. For example, if you install the MySQL, it will create a service called MySQL (mysql.service).  To use TomEE with MySQL, just start MySQL first and then TomEE.

To make it possible, inside the section [Unit] in our tomee.service, update the After property as shown below.

After=network.target mysql.service

With this update, we make sure that TomEE will start only after the network and MySQL are up and running.