Module systemd

Functions for interacting with systemd features.

Introduced in: 0.1.0

Description

Functions for interacting with systemd features.

Data Types

fd()

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

sd_timeout()

sd_timeout() = pos_integer()

state()

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()}

Function Index

booted/0 Check if system was booted with systemd.
clear_fds/1 Removes given named filedescriptors from the store.
listen_fds/0 Returns list of file descriptors passed to the application by systemd.
notify/1 Send notification to the systemd socket.
ready/0 Returns child spec for task that will inform systemd that application is ready.
store_fds/1 Send given file descriptors to supervisor for storage between VM restarts.
unset_env/1 Unset environment variables for given subsystem.
watchdog/1 Manage watchdog process.

Function Details

booted/0

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

returns: {ok, true} if system was booted with systemd, {ok,false} if not, and {error, Reason} on error.

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.

Introduced in: 0.1.0

clear_fds/1

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

Removes given named filedescriptors from the store.

Introduced in: 0.6.0

listen_fds/0

listen_fds() -> [fd()]

returns: List of passed file descriptors. If descriptor have name defined then it will be returned as 2nd value in tuple. Order of returned descriptors is the same as passed in environment.

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

Introduced in: 0.2.0

notify/1

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}.

Introduced in: 0.1.0

ready/0

ready() -> any()

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).

store_fds/1

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

returns: ok on success, {error, bad_descriptor} if any file descriptor in the passed list is invalid (isn't file desciptor or is closed).

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 at least for x86-64, AArch64, AArch32, SPARC, OpenRISC, and RISC-V.

Introduced in: 0.6.0

unset_env/1

unset_env(Subsystem) -> ok

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.

Introduced in: 0.4.0

watchdog/1

watchdog(X1::state) -> sd_timeout()

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.

Introduced in: 0.1.0


Generated by EDoc