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 | watchdog | watchdog_trigger | {status, unicode:chardata()} | {errno, non_neg_integer()} | {buserror, unicode:chardata()} | {extend_timeout, {non_neg_integer(), erlang:time_unit()}} | unicode:chardata()

Function Index

booted/0 Check if system was booted with systemd.
listen_fds/0 Returns list of file descriptors passed to the application by systemd.
notify/1 Send notification to the systemd socket.
notify/2 Send notification to the systemd socket.
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

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

Equivalent of watchdog(ping).

See watchdog/1.
notify(watchdog_trigger)

Equivalent of watchdog(trigger).

See watchdog/1.
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, {Time :: integer(), Unit :: 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.

Introduced in: 0.1.0

notify/2

notify(Format::io:format(), Data::[term()]) -> ok

Send notification to the systemd socket.

This function takes Format and Data that will be formatted in the same way as io:fwrite/2.

Introduced in: 0.1.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(trigger) -> ok
Trigger Watchdog timeout right despite current state.
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