sd_notify_promise

Implementation of libsystemd's sd_notify using unix-dgram socket

Usage no npm install needed!

<script type="module">
  import sdNotifyPromise from 'https://cdn.skypack.dev/sd_notify_promise';
</script>

README

This is an implementation of systemd’s simple sd_notify protocol as described in sd_notify Notes and as implemented in libsystemd. In the service’s systemd configuration, you can configure systemd to restart the process when it is not working using e.g. Type=notify or WatchdogSec=60.

API

function sd_notify(state: string, {unsetEnvironment?: boolean}): Promise<boolean>

Sends the string in state to systemd (which is identified by the NOTIFY_SOCKET environment variable), and returns a Promise that completes once the message has been sent. The promise resolves to true if the message was sent, or false if NOTIFY_SOCKET was unset.

If unsetEnvironment is set, deletes the process.env.NOTIFY_SOCKET field so that subprocesses do not use the socket. If you are calling sd_notify more than once, unsetEnvironment should be false.

Typically you would use it like this. For a full list of messages that systemd understands, see the sd_notify documentation.

sd_notify("STATUS=loading").catch(console.error)
sd_notify("READY=1").catch(console.error)
sd_notify("STATUS=serving").catch(console.error)
if (parseInt(process.env.WATCHDOG_USEC)) setInterval(() => {
    // check server health…

    sd_notify("WATCHDOG=1").catch(console.error)
}, parseInt(process.env.WATCHDOG_USEC)/1000/2)

Not supported

I have not implemented sd_pid_notify, which sends the credentials of the PID in question to systemd using ancillary data of type cmsg_type=SCM_CREDENTIALS in the sendmsg call.

I have not implemented sd_pid_notify_with_fds, which sends open file descriptors to systemd using ancillary data of type cmsg_type=SCM_RIGHTS in the sendmsg call. This is used in sd_notify(…, "FDSTORE=1") to keep a socket open even when a process is restarted.

Other implementations

  • sdnotify-wrapper calls the libsystemd shared library. It requires libsystemd to be installed.
  • systemd-daemon exposes a fire-and-forget notify function.

Dependencies

The only dependency is unix-dgram, which is needed to create datagram sockets (socket(AF_UNIX, SOCK_DGRAM)). (Node/libuv’s builtin IPC support creates only streaming sockets socket(AF_UNIX, SOCK_STREAM)).