193 lines
7.8 KiB
OCaml
193 lines
7.8 KiB
OCaml
(** [Systemd] is a module for interacting with the {{:https://systemd.io/}systemd} service manager.
|
|
It provides functions for most common systemd functionality, such as the protocols for
|
|
detecting systemd/journald presence, startup/status notifications, the file descriptor store,
|
|
and the watchdog. See also {!Systemd_xlog} for integration with {!Xlog} to log via journald *)
|
|
|
|
(** [is_systemd_booted env] checks if the current system is running on systemd. [env] is the Eio
|
|
environment from [Eio_main.run] *)
|
|
val is_systemd_booted : Eio_unix.Stdenv.base -> bool
|
|
|
|
(** [is_in_systemd ()] checks if the program was started as a systemd service *)
|
|
val is_in_systemd : unit -> bool
|
|
|
|
(** [invocation_id ()] returns the systemd invocation ID if the program was started using systemd,
|
|
or if it is the child of a systemd service that has not unset the environment variable *)
|
|
val invocation_id : unit -> string
|
|
|
|
(** [is_journald_attached ()] checks if the program is currently connected to a journald stream.
|
|
This can indicate the ability to upgrade to rich log messages, eg with {!Systemd_xlog}. *)
|
|
val is_journald_attached : unit -> bool
|
|
|
|
(** [Systemd.Dirs] provides convenience functions for various directories passed in by systemd *)
|
|
module Dirs : sig
|
|
|
|
(** When started with a [RuntimeDirectory=] option, provides the runtime directory given by
|
|
systemd *)
|
|
val runtime_dir : unit -> string
|
|
|
|
(** When started with a [StateDirectory=] option, provides the state directory given by systemd *)
|
|
val state_dir : unit -> string
|
|
|
|
(** When started with a [CacheDirectory=] option, provides the cache directory given by systemd *)
|
|
val cache_dir : unit -> string
|
|
|
|
(** When started with a [LogsDirectory=] option, provides the logs directory given by systemd *)
|
|
val logs_dir : unit -> string
|
|
|
|
(** When started with a [ConfigurationDirectory=] option, provides the configuration directory
|
|
given by systemd *)
|
|
val configuration_dir : unit -> string
|
|
|
|
(** When started with a [LoadCredential=] or [LoadCredentialEncrypted=] option, provides the
|
|
directory with the credentials given by systemd *)
|
|
val credentials_dir : unit -> string
|
|
end
|
|
|
|
(** [Systemd.Notify] implements the notification protocol to inform systemd of service readiness
|
|
and other state changes *)
|
|
module Notify : sig
|
|
|
|
(** Holds context for using this module *)
|
|
type t
|
|
|
|
(** [Notify.make ~sw ~env] creates a new notify context, which must be passed to the other
|
|
functions in this module. [sw] is a [Eio.Switch] which will register the resources associated
|
|
with the context, and [env] is the Eio environment from [Eio_main.run] *)
|
|
val make :
|
|
sw:Eio.Switch.t ->
|
|
env:Eio_unix.Stdenv.base -> t
|
|
|
|
(** [Notify.notify t ~fds msg] sends [msg] and optionally file descriptors in [fds] to systemd.
|
|
This is a low-level function and should only be used if the convenience functions in this
|
|
module do not provide the functionality you need. In particular, [fds] should only be set
|
|
if [msg] corresponds to a command that accepts file descriptors. *)
|
|
val notify :
|
|
t ->
|
|
?fds:Eio_unix.Fd.t list ->
|
|
string -> unit
|
|
|
|
(** [Notify.ready t] tells systemd that this program has finished initialization and can be
|
|
considered fully operational. An optional [status] can be sent containing a status message.
|
|
Status messages should not contain any newlines.
|
|
[mainpid] corresponds to the [MAINPID=] field of the underlying notification command and is
|
|
typically not needed. *)
|
|
val ready :
|
|
?status:string option ->
|
|
?mainpid:int ->
|
|
t -> unit
|
|
|
|
(** [Notify.send_status t status] updates the status message of this program as reported by
|
|
systemd to the given text. Note that status messages should not contain any newlines. *)
|
|
val send_status :
|
|
t ->
|
|
string -> unit
|
|
|
|
(** [Notify.send_status_errno t status errno] is like [Notify.send_status t status] but contains
|
|
an additional [Unix.error] corresponding to some error condition encountered by the program. *)
|
|
val send_status_errno :
|
|
t ->
|
|
string ->
|
|
Unix.error -> unit
|
|
|
|
(** [Notify.reloading t] reports that the program is currently reloading its configuration.
|
|
If used, [Notify.ready t] must be called at some point to report completion. *)
|
|
val reloading : t -> unit
|
|
|
|
(** [Notify.stopping t] reports that the program is stopping. The program should exit soon after
|
|
calling this function. *)
|
|
val stopping : t -> unit
|
|
|
|
(** Represents the different values of the systemd [NotifyAccess=] setting. *)
|
|
module NotifyAccess : sig
|
|
|
|
(** Possible values for systemd [NotifyAccess=] *)
|
|
type t =
|
|
| None (** ["none"] *)
|
|
| Main (** ["main"] *)
|
|
| Exec (** ["exec"] *)
|
|
| All (** ["all"] *)
|
|
|
|
(** [to_string t] returns the systemd-compatible string representation of [t] *)
|
|
val to_string : t -> string
|
|
end
|
|
|
|
(** [Notify.update_access t acc] changes the access setting for the notification socket,
|
|
overriding the systemd [NotifyAccess=] setting *)
|
|
val update_access :
|
|
t ->
|
|
NotifyAccess.t -> unit
|
|
|
|
(** [Notify.extend_timeout t span] attempts to add a duration [span] to the
|
|
current startup, runtime or shutdown service timeout. A further notification message must be
|
|
sent within the duration specified by [span]. *)
|
|
val extend_timeout :
|
|
t ->
|
|
Mtime.Span.t -> unit
|
|
|
|
(** [Notify.barrier t] performs a barrier protocol to synchronize systemd with the program. Once
|
|
this function returns, systemd is guaranteed to have processed all notification messages sent
|
|
before this function was called. *)
|
|
val barrier : t -> unit
|
|
end
|
|
|
|
(** [Systemd.Watchdog] implements the systemd watchdog protocol, when the program is used with eg
|
|
[WatchdogSec=] *)
|
|
module Watchdog : sig
|
|
|
|
(** [Watchdog.get_interval_opt ()] returns either the interval on which the program must send
|
|
watchdog notifications, or [None] if the watchdog is not enabled *)
|
|
val get_interval_opt : unit -> Mtime.Span.t option
|
|
|
|
(** [Watchdog.pet t] sends a keep-alive notification to systemd *)
|
|
val pet : Notify.t -> unit
|
|
|
|
(** [Watchdog.trigger t] tells systemd to trigger the watchdog action, as if a failure has
|
|
occurred *)
|
|
val trigger : Notify.t -> unit
|
|
|
|
(** [Watchdog.set_watchdog_time t span] updates the watchdog interval to [span] *)
|
|
val set_watchdog_time :
|
|
Notify.t ->
|
|
Mtime.Span.t -> unit
|
|
end
|
|
|
|
(** [Systemd.Fdstore] implements the systemd
|
|
{{:https://systemd.io/FILE_DESCRIPTOR_STORE/}file descriptor store} and socket-passing protocol,
|
|
when relevent options are enabled *)
|
|
module Fdstore : sig
|
|
|
|
(** [Fdstore.is_valid_fdname s] checks if [s] is a valid fdstore name according to systemd *)
|
|
val is_valid_fdname : string -> bool
|
|
|
|
(** [Fdstore.get_fd_limit ()] retrieves the maximum number of file descriptors that can be stored
|
|
with systemd. Returns 0 if fdstore is not enabled *)
|
|
val get_fd_limit : unit -> int
|
|
|
|
(** [Fdstore.store t name fd] registers [fd] with [name] in the systemd fdstore. If
|
|
[poll=false] then systemd will not automatically remove the fd when it's closed, so it must
|
|
be manually unregistered. *)
|
|
val store :
|
|
Notify.t ->
|
|
string ->
|
|
?poll:bool ->
|
|
Eio_unix.Fd.t -> unit
|
|
|
|
(** [Fdstore.remove t name] removes any file descriptor previously registered with [name] from
|
|
systemd *)
|
|
val remove :
|
|
Notify.t ->
|
|
string -> unit
|
|
|
|
(** [Fdstore.listen_fds ~sw] returns a list of file descriptors passed into this process by
|
|
systemd. This can be fds previously registered with [Fdstore.store], or fds associatd with
|
|
systemd socket activation (or both). The fds get registered with Eio Switch [sw]. Environment
|
|
variables corresponding to this fd-passing protocol get unset when this function completes. *)
|
|
val listen_fds :
|
|
sw:Eio.Switch.t ->
|
|
(string option * Eio_unix.Fd.t) list
|
|
end
|
|
|
|
module MemPressure : sig
|
|
val memory_trim : unit -> unit
|
|
end
|