systemd socket activation

myapp.service

# https://www.freedesktop.org/software/systemd/man/systemd.unit.html
[Unit]
Description=My App
After=network.target

# https://www.freedesktop.org/software/systemd/man/systemd.exec.html
[Service]
Type=simple
# https://www.freedesktop.org/software/systemd/man/systemd.exec.html#WorkingDirectory=
WorkingDirectory=-/srv/app/
ExecStart=/usr/bin/node server.js
DynamicUser=yes
ProtectHome=yes
Restart=always
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=myapp

[Install]
WantedBy=multi-user.target

myapp.socket

# https://www.freedesktop.org/software/systemd/man/systemd.socket.html

[Socket]
# https://www.freedesktop.org/software/systemd/man/systemd.socket.html#ListenStream=
ListenStream=3000
BindIPv6Only = both

# SO_REUSEPORT not supported by node: https://github.com/nodejs/node/issues/12228
# ReusePort=true

[Install]
WantedBy=sockets.target

server.ts

import http from 'http'
import { getSystemdSocketHandle } from './socket-handle'

const server = http.createServer(async (req, res) => {
	console.log(req.url, req.headers)

	res.statusCode = 200
	res.setHeader('Content-Type', 'application/json')
	res.end(JSON.stringify({ data: true }))
})

// Still compatible if not socket activated.
const handle = getSystemdSocketHandle() || process.env.PORT || 3000

server.listen(handle, () => {
	console.log('Server started', server.address())
})

socket-handle.ts

/**
 * Returns file descriptor of systemd socket.
 * Returns `undefined` if the process has not been activated by systemd socket.
 */
export function getSystemdSocketHandle() {
	// https://www.freedesktop.org/software/systemd/man/sd_listen_fds.html
	const SD_LISTEN_FDS_START = 3

	const LISTEN_PID = !!process.env.LISTEN_PID && Number.parseInt(process.env.LISTEN_PID)
	const LISTEN_FDS = !!process.env.LISTEN_FDS && Number.parseInt(process.env.LISTEN_FDS)
	const LISTEN_FDNAMES = !!process.env.LISTEN_FDNAMES && process.env.LISTEN_FDNAMES.split(':')

	// console.log('PID:', process.pid, 'PPID:', process.ppid)
	// console.log('LISTEN_PID:', LISTEN_PID, 'LISTEN_FDS:', LISTEN_FDS, 'LISTEN_FDNAMES:', LISTEN_FDNAMES)

	const isSocketActivated = !!LISTEN_PID && !!LISTEN_FDS

	if (!isSocketActivated) {
		return undefined
	}

	if (LISTEN_PID !== process.pid) {
		throw Error(`Cannot use file descriptors meant for pid ${LISTEN_PID} in pid ${process.pid}`)
	}

	if (LISTEN_FDS > 1) {
		throw Error(`One file descriptor expected. ${LISTEN_FDS} received (${LISTEN_FDNAMES})`)
	}

	return { fd: SD_LISTEN_FDS_START }
}

§links.md

Systemd

https://www.usenix.org/system/files/login/articles/login_june_06_jedrzejewski-szmek.pdf

https://www.digitalocean.com/community/tutorials/understanding-systemd-units-and-unit-files https://www.digitalocean.com/community/tutorials/how-to-use-systemctl-to-manage-systemd-services-and-units

https://mgdm.net/weblog/systemd/ https://vincent.bernat.ch/en/blog/2017-systemd-golang

Socket Activations

https://mgdm.net/weblog/systemd-socket-activation/ https://vincent.bernat.ch/en/blog/2018-systemd-golang-socket-activation https://idea.popcount.org/2019-11-06-creating-sockets/#socket-activation

File descriptor issues

nodejs/help#2115 (comment) haproxy/haproxy#766 https://serverfault.com/questions/1036195/passing-8192-sockets-via-systemd-socket-activation-fails-with-e2big

Security & Sandboxing

https://nickb.dev/blog/writing-a-secure-systemd-service-with-sandboxing-and-dynamic-users https://unix.stackexchange.com/questions/635027/systemd-dynamicuser-vs-user

Reload

https://serverfault.com/questions/767360/how-to-configure-systemd-to-kill-and-restart-a-daemon-on-reload/767898

Notify

https://github.com/nmorsman/node-systemd-notify/blob/master/notify.js