systemd (systemd v0.6.2)

Functions for interacting with systemd features.

Link to this section Summary

Functions

booted()

Check if system was booted with systemd.

clear_fds(Names)

Removes given named filedescriptors from the store.

is_journal(Type)

listen_fds()

Returns list of file descriptors passed to the application by systemd.

notify(State)

Send notification to the systemd socket.

ready()

Returns child spec for task that will inform systemd that application is ready.

ready(Status)

reload()

Equivalent to reload([]).

reload(Opts)

Restart VM with informing the systemd about reload.

set_status(Statuses)

store_fds(List)

Send given file descriptors to supervisor for storage between VM restarts.

unset_env(Subsystem)

Unset environment variables for given subsystem.

watchdog(_)

Manage watchdog process.

Link to this section Types

fd/0

Specs

fd() :: integer() | {integer(), unicode:chardata()}.

sd_timeout/0

Specs

sd_timeout() :: pos_integer().

state/0

Specs

state() ::
    ready | stopping | reloading |
    {status, unicode:chardata()} |
    {errno, non_neg_integer()} |
    {buserror, unicode:chardata()} |
    {extend_timeout, {non_neg_integer(), erlang:time_unit()}} |
    {unicode:chardata() | atom(), unicode:chardata()}.

Link to this section Functions

booted()

(since 0.1.0)

Specs

booted() -> {ok, boolean()} | {error, file:posix()}.

Check if system was booted with systemd.

Note that all other functions in this module are safe to call even on non-systemd boots (even on non-systemd platforms). You should NOT protect them with a call to this function. Also note that this checks wheter the system, not the user session, is controlled by systemd. However other functions will work for both - user and system services.

clear_fds(Names)

(since 0.6.0)

Specs

clear_fds([unicode:chardata()]) -> ok.

Removes given named filedescriptors from the store.

is_journal(Type)

listen_fds()

(since 0.2.0)

Specs

listen_fds() -> [fd()].

Returns list of file descriptors passed to the application by systemd.

notify(State)

(since 0.1.0)

Specs

notify(State :: state() | [state()]) -> ok.

Send notification to the systemd socket.

Arguments

notify(ready): Notify that application is ready for work. If used with Type=notify in systemd.service(5) file then it will block systemctl start until this is called.
notify(stopping): Notify that application has already started shutting down, but is not yet ready to stop. For example when you want to do connection draining or you have to do some cleaning before fully stopping.
This will be automatically set for you in systemd's application prep_stop/1 step, so user do not need to call it manually.
notify(reloading): Notify that application is reloading. It is left up to user what is considered reloading and handle this call manually.
notify({errno, Errno :: integer()}): Notify that application encountered Errno in C's errno format.
Implemented only for feature parity.
notify({buserror, Error :: unicode:chardata()}): Notify about DBus error.
notify({extend_timeout, {integer(), erlang:time_unit()}}): Request extension of timeout for sending notify(ready). This is useful in case of setups that are taking more time than originally expected, for example because of retries in connecting to external service.
This message must be sent within original timeout.

Return value

Returns ok on success or if the message was ignored because there is no systemd notify socket. Only error that can be returned as 0.6.0 is when the file descriptors are passed and at least one of them is not correct file descriptor (for example it is closed), then this call will return {error, bad_descriptor}.

ready()

Returns child spec for task that will inform systemd that application is ready.

This is helper function that will return supervisor:child_spec/0 map that contains temporary job that will notify systemd about application readiness. This is meant to be inserted into your supervison tree when application is ready (usually at the end).

ready(Status)

reload()

Equivalent to reload([]).

reload(Opts)

Restart VM with informing the systemd about reload.

This is esentially the same as init:restart(Opts) with the difference that it will inform the systemd that the system is reloading instead of shutting down. If you use init:restart/{0,1} anywhere in your application you need to change it to this function otherwise your application may be forced to exit by systemd on reloads.

set_status(Statuses)

Specs

set_status(Statuses) -> supervisor:child_spec()
              when
                  Statuses :: MapStatuses | ListStatuses,
                  ListStatuses :: [{up | down, state()}],
                  MapStatuses :: #{up := state(), down := state()}.

store_fds(List)

(since 0.6.0)

Specs

store_fds([fd()]) -> ok | {error, term()}.

Send given file descriptors to supervisor for storage between VM restarts.

Warning

This currently assumes that the currently used ABI is using 32-bit ints. This is true for Linux at least for IA-32, x86-64, AArch64, AArch32, SPARC, OpenRISC, and RISC-V (required by POSIX). So while that shouldn't cause any problems, beware, that currently it may fail on some exotic platforms.

unset_env(Subsystem)

(since 0.4.0)

Specs

unset_env(Subsystem) -> ok when Subsystem :: notify | watchdog | listen_fds.

Unset environment variables for given subsystem.

Most environment variables will be cleaned on startup by default. To prevent such behaviour set unset_env application variable to false.

unset_env(notify): Unset variables used by notify/1. This call will be done automatically when the unset_env application option is set (default). It is highly encouraged to unset these variables to prevent them from being passed to subprocesses.
unset_env(watchdog): Unset variables used by watchdog/1. This call will be done automatically when the unset_env application option is set (default). It is highly encouraged to unset these variables to prevent them from being passed to subprocesses.
unset_env(listen_fds): Unset variables used by listen_fds/0. After that all subsequent calls to listen_fds will return empty list. It is highly encouraged to unset these variables to prevent them from being passed to the subprocesses.

watchdog(_)

(since 0.1.0)

Specs

watchdog(state) -> sd_timeout();
        (trigger) -> ok;
        (enable) -> ok;
        (disable) -> ok;
        (ping) -> ok.

Manage watchdog process.

By default systemd will handle Watchdog process automatically for you.

Arguments

watchdog(state) -> sd_timeout(): Returns state of the Watchdog process. Which either be integer representing timeout in microseconds or false if Watchdog process is disabled.
watchdog(enable) -> ok: Enable Watchdog process. Watchdog process is automatically enabled when needed after startup, so this will be only needed if user manually called watchdog(disable).
watchdog(disable) -> ok: Disable Watchdog process. This will cause no keep-alive messages to be sent.
watchdog(trigger) -> ok: Manually send keep-alive message to the Watchdog. It will not reset timer and will not disturb regular process pinging.

Options

watchdog_scale: Divider of the timeout to send messages more often than this is required to prevent any jitter.
Defaults to 2 which will send messages twice as often as needed.
watchdog_check: Function (specified as 0-ary function or mfa()) that will be ran before pinging watchdog process. Such function should return true if the application is in functioning state and false otherwise.
Defaults to function that always return true.