OpenMTC/doc/systemd.md

OpenMTC systemd integration

In addition to SysV init scripts, OpenMTC is providing ready-to-use service files for the systemd init system.

ℹ️ Hint: As OpenMTC does not require privileged ports in order to function, it can be safely run from within a user's home directory. To do so, replace sudo systemctl with systemctl --user. It should bear mentioning that this is a convenience option for developers that is strongly discouraged for production.

Installing Service Files

Please refrain from copying or editing the provided files. Instead, change into the root of the openmtc repository and proceed as follows:

$ sudo systemctl link $(pwd)/openmtc-gevent/etc/systemd/system/openmtc-*.service

This should provide you with two new services in the systemd search path: openmtc-gateway and openmtc-backend. Confirm this by executing sudo systemctl status openmtc-\*.

Adjusting ExecStart

By default, the service files will assume to find the start scripts to be located in /usr/local/bin. Chances are, this may not be the case. This is how to adjust the service files properly:

$ sudo systemctl edit openmtc-gateway

An editor is going to open. Fill the presented file with the following content:

[Service]
# Clear user and group
User=
Group=
# This is needed to reset ExecStart before reassigning
ExecStart=
# Change to location on your system
ExecStart=/opt/openmtc-gevent/bin/run-gateway

Save the file and exit the editor. Run sudo systemctl daemon-reload and verify the new value got picked up by executing sudo systemctl show --property=ExecStart --no-pager openmtc-gateway .

The procedure above is identical for the openmtc-backend component, safe for replacing gateway with backend.

Controlling the Services

Both, gateway and backend, can be started through sudo systemctl start openmtc-gateway and sudo systemctl start openmtc-backend, respectively. They can also be started in bulk via sudo systemctl start openmtc-gateway openmtc-backend. Execution order is not guaranteed, though.

If you always require the two services, it may be a good idea to add a dependency from the gateway to the backend as follows:

$ sudo systemctl add-requires openmtc-gateway.service openmtc-backend

⚠️ Caveat: Please take note that the target unit name is fully specified. This is needed as systemd would otherwise assume you wanted to add a requirement to a target

Verify the dependency has been set in place by running sudo systemctl list-dependencies openmtc-gateway and checking if openmtc-gateway.service is listed. Starting the openmtc-gateway service will now also invoke openmtc-backend. Another benefit is that openmtc-gateway will be reloaded if openmtc-backend is.

Services can be shut down through sudo systemctl stop in the same fashion as systemctl start.

Monitoring

While systemctl status may reveal some log lines, more telling output generated by the services can be monitored through journalctl. sudo journalctl -lf --unit openmtc-\* should present a life feed of all running openmtc services.

ℹ️ Hint: The road is a bit rough for those who run OpenMTC via systemd from their homedir, unfortunately. In theory, you should be good to go with journalctl -lf --user --unit openmtc-\*. But due to a lot of diversity in deployed systemd versions potentised by a wealth of different configurations, this may not do the trick. In that case, - under the assumption only a single instance of each, gateway and backend is running - the fastest way to success may be this:

$ sudo journalctl -lf _PID=$(ps ux | grep gateway_main.py | head -n1 | awk '{ print $2; }') + \
                      _PID=$(ps ux | grep backend_main.py | head -n1 | awk '{ print $2; }')