search

bstarynk / helpcovid

a C++ free software web application (GPLv3+, Linux) to organize people helping other neighbours in Covid pandemics
GNU General Public License v3.0
2 stars 2 forks source link

Show how to set up as per-user services in systemd and nosh service management #33

Open jdebp opened 4 years ago

jdebp commented 4 years ago

Per https://unix.stackexchange.com/a/578832/5132 , after #32 is in place the program can be run as a per-user or indeed system-wide service under systemd, the nosh toolset's service management, or anything else that provides the other side of the LISTEN_FDS mechanism. There are some quick and dirty socket and service units in that StackExchange answer that need tidying up, commenting, and inclusion in the tree here, somewhere.

This can then be documented in the readme:

Running as a systemd service

The helpcovid.socket and helpcovid.service files, provided here, can be used to run helpcovidas a so-called socket-activated service under systemd, either at the user level or at the system level. To run it at user level, place these files in your $HOME/.config/systemd/user/ directory and issue systemctl --user daemon-reload to tell systemd to rescan that directory and find them.

To start/stop/enable/disable the program, address the socket unit; so (for example) issue systemctl --user enable helpcovid.socket. The listening socket port and IP address are configured by adjusting the ListenStream= setting in the helpcovid.socket file in the normal systemd manner. Note that systemd allows multiple port and IP address combinations in a single socket unit, with multiple ListenStream= settings.

All environment variables are set by modifying the service unit, either directly or with separate .conf file drop-ins (documented in the systemd.unit(1) manual page) that have individual Environment=WIBBLE=wobble lines). That is where the LC_ALL environment variable, for specifying the locale, is set, as shown in the service unit provided. Command-line flags can be altered by setting a flags variable, as referenced by the ExecStart= setting, notice. The EnvironmentDirectory setting is not there for systemd; it is there for nosh service management, discussed in the next section.

systemd pushes the standard output and error of the service to your user part of the central systemd journal, which you can read with journalctl --user .

Running as a system-level service is much the same (without the --user and putting the unit files in the /etc/systemd/system/ directory instead). Note that running as a system-level service involves privileged access and entails paying more attention to security, issues that this readme does not go into for brevity. Unless you really need to bind to a super-user-only TCP port number, prefer running this as a user-level service under systemd.

Note that systemd starts your (enabled) user-level services when you first log in, and stops them when you log out of your final login session.

Running under nosh service management

Take the helpcovid.socket and helpcovid.service units for systemd, and pass them through system-control convert-systemd-units ./helpcovid.socket . Place the generated service bundle directory (see the system-control(1) manual for what this is) in your$HOME/.config/service-bundles/services/directory as a helpcovid subdirectory. Run system-control --user start helpcovid, and so forth.

Environment variables are read from an "envdir" (as documented in the envdir(1) manual page). You can set them with (for example) system-control --user set-service-env helpcovid flags '--wibble' and print them with system-control --user print-service-env helpcovid. This does not involve editing the helpcovid/service/run and helpcovid/service/service files, except perhaps to delete the setenv LC_ALL fr_FR.UTF-8 line so that you can override it from the envdir (which is read first).

Change the TCP port number and IP address by editing the tcp-socket-accept line in helpcovid/service/run. Multiple port and address combinations can be set up by adding further tcp-socket-accept lines, all with (importantly) the --systemd-compatibility flag.

To log, create a second service bundle, named (for example) cyclog@helpcovid that runs cyclog ./main, and connect the first service to the second by symbolically linking helpcovid/log to ../cyclog@helpcovid. There are lots of logging services that come with the nosh toolset that show how this is done. You can read the log in cyclog@helpcovid/main/current and related files.