@push.rocks/smartdaemon 2.20.1 → 2.22.0

package/dist_ts_systemdruntime/systemdruntime.listen.js

@@ -0,0 +1,136 @@
+import { SystemdRuntimeError } from './classes.systemdruntimeerror.js';
+import { libcConstants, systemdLibc } from './systemdruntime.libc.js';
+import { assertSystemdDescriptor, isSystemdDescriptorName } from './systemdruntime.validation.js';
+/** sd_listen_fds(3): `SD_LISTEN_FDS_START`, the first passed descriptor. */
+export const systemdListenDescriptorsStart = 3;
+/**
+ * Marks one open descriptor close-on-exec (`fcntl(F_SETFD, FD_CLOEXEC)`) and verifies the flag,
+ * so no child process inherits it. Throws `close_on_exec_failed` with `errno` when the descriptor
+ * is not open or the flag does not hold.
+ */
+export const setCloseOnExec = (descriptorArg) => {
+    assertSystemdDescriptor(descriptorArg);
+    const libc = systemdLibc();
+    const { fcntl } = libc.functions;
+    const flags = fcntl(descriptorArg, libcConstants.F_GETFD, 0);
+    if (flags < 0) {
+        throw new SystemdRuntimeError('close_on_exec_failed', `Descriptor ${descriptorArg} cannot be read.`, {
+            errno: libc.errno(),
+        });
+    }
+    if (fcntl(descriptorArg, libcConstants.F_SETFD, flags | libcConstants.FD_CLOEXEC) < 0) {
+        throw new SystemdRuntimeError('close_on_exec_failed', `Descriptor ${descriptorArg} cannot be marked close-on-exec.`, {
+            errno: libc.errno(),
+        });
+    }
+    if ((fcntl(descriptorArg, libcConstants.F_GETFD, 0) & libcConstants.FD_CLOEXEC) === 0) {
+        throw new SystemdRuntimeError('close_on_exec_failed', `Descriptor ${descriptorArg} did not keep close-on-exec.`);
+    }
+};
+const positiveIntegerPattern = /^[1-9][0-9]*$/;
+/** sd_listen_fds(3) refuses a count above `INT_MAX - SD_LISTEN_FDS_START`. */
+const listenDescriptorsMaximum = 2_147_483_647 - systemdListenDescriptorsStart;
+const invalidListen = (messageArg, errnoArg) => new SystemdRuntimeError('listen_environment_invalid', messageArg, errnoArg === undefined ? {} : { errno: errnoArg });
+/**
+ * The process's hard `RLIMIT_NOFILE` (`getrlimit(2)`), or null for `RLIM_INFINITY`. No descriptor
+ * the manager passed can lie at or above it: systemd moves passed descriptors into place with
+ * `fcntl(F_DUPFD)` after applying the unit's limits (`shift_fds()` after `setrlimit_closest_all()` in
+ * v255 `src/core/exec-invoke.c`), `F_DUPFD` refuses a number at or above the soft limit, the soft
+ * limit never exceeds the hard one, and an unprivileged process cannot raise the hard one.
+ */
+const descriptorHardLimit = () => {
+    const libc = systemdLibc();
+    const rlimit = Buffer.alloc(16);
+    if (libc.functions.getrlimit(libcConstants.RLIMIT_NOFILE, rlimit) !== 0) {
+        throw invalidListen('getrlimit(RLIMIT_NOFILE) failed, so LISTEN_FDS cannot be bounded.', libc.errno());
+    }
+    const hard = rlimit.readBigUInt64LE(8);
+    return hard === 0xffffffffffffffffn ? null : hard;
+};
+/**
+ * Takes the descriptors the service manager passed this process (sd_listen_fds_with_names(3)):
+ * socket-activation sockets and descriptor-store entries, numbered from 3.
+ *
+ * `LISTEN_PID`, `LISTEN_FDS` and `LISTEN_FDNAMES` always leave the environment, so no child sees
+ * them. Without them, or with `LISTEN_PID` naming another process (variables inherited from a
+ * parent), it returns an empty list and touches no descriptor. For this process every passed
+ * descriptor is marked close-on-exec before the list returns. Without `LISTEN_FDNAMES` each name is
+ * `unknown`, as in systemd.
+ *
+ * Throws `listen_environment_invalid` before touching any descriptor for a partial or malformed set
+ * (a count that is not a positive integer, a count whose last descriptor, `2 + count`, is at or
+ * above the process's hard `RLIMIT_NOFILE`, a names list whose length differs from the count, an
+ * invalid name), and with `errno` when `getrlimit(2)` fails. Descriptors are then marked one by one
+ * from 3, and memory grows only with descriptors proven open: the first passed descriptor that is
+ * not open throws `close_on_exec_failed`, as `sd_listen_fds(3)` fails on it; descriptors before it
+ * keep the flag.
+ */
+export const takeSystemdListenDescriptors = (optionsArg = {}) => {
+    const env = optionsArg.env ?? process.env;
+    const pid = optionsArg.pid ?? process.pid;
+    const listenPid = env.LISTEN_PID;
+    const listenFds = env.LISTEN_FDS;
+    const listenFdNames = env.LISTEN_FDNAMES;
+    delete env.LISTEN_PID;
+    delete env.LISTEN_FDS;
+    delete env.LISTEN_FDNAMES;
+    if (listenPid === undefined && listenFds === undefined && listenFdNames === undefined)
+        return Object.freeze([]);
+    if (listenPid === undefined || !positiveIntegerPattern.test(listenPid)) {
+        throw invalidListen('LISTEN_PID must name a process.');
+    }
+    if (listenPid !== String(pid))
+        return Object.freeze([]);
+    if (listenFds === undefined || !positiveIntegerPattern.test(listenFds) || Number(listenFds) > listenDescriptorsMaximum) {
+        throw invalidListen('LISTEN_FDS must be a positive descriptor count.');
+    }
+    const count = Number(listenFds);
+    // The cheap early bound: the last passed descriptor is 2 + count.
+    const hardLimit = descriptorHardLimit();
+    if (hardLimit !== null && BigInt(systemdListenDescriptorsStart + count) > hardLimit) {
+        throw invalidListen(`LISTEN_FDS passes ${count} descriptors; descriptor ${systemdListenDescriptorsStart + count - 1} is at or above this process's hard RLIMIT_NOFILE (${hardLimit}).`);
+    }
+    // Names, when given, are checked before any descriptor; the list is bounded by the variable's length.
+    const names = listenFdNames === undefined ? null : listenFdNames.split(':');
+    if (names !== null) {
+        if (names.length !== count)
+            throw invalidListen(`LISTEN_FDNAMES names ${names.length} descriptors; LISTEN_FDS passes ${count}.`);
+        if (!names.every((name) => isSystemdDescriptorName(name, false)))
+            throw invalidListen('LISTEN_FDNAMES holds an invalid name.');
+    }
+    // Nothing scales with the count before a descriptor is proven open: as in sd_listen_fds(3), the
+    // first descriptor that is not open ends the walk with close_on_exec_failed.
+    const descriptors = [];
+    for (let index = 0; index < count; index++) {
+        const descriptor = systemdListenDescriptorsStart + index;
+        setCloseOnExec(descriptor);
+        descriptors.push(Object.freeze({ descriptor, name: names === null ? 'unknown' : names[index] }));
+    }
+    return Object.freeze(descriptors);
+};
+/**
+ * The watchdog interval the manager expects `WATCHDOG=1` within (`WATCHDOG_USEC`, sd_watchdog_enabled(3)),
+ * in microseconds; null when the unit has no watchdog or `WATCHDOG_PID` names another process.
+ * Reads the environment without changing it. Throws `watchdog_environment_invalid` for a malformed
+ * value.
+ */
+export const watchdogIntervalUsec = (optionsArg = {}) => {
+    const env = optionsArg.env ?? process.env;
+    const pid = optionsArg.pid ?? process.pid;
+    const usec = env.WATCHDOG_USEC;
+    const watchdogPid = env.WATCHDOG_PID;
+    if (usec === undefined)
+        return null;
+    if (!positiveIntegerPattern.test(usec) || !Number.isSafeInteger(Number(usec))) {
+        throw new SystemdRuntimeError('watchdog_environment_invalid', 'WATCHDOG_USEC must be a positive integer.');
+    }
+    if (watchdogPid !== undefined) {
+        if (!positiveIntegerPattern.test(watchdogPid)) {
+            throw new SystemdRuntimeError('watchdog_environment_invalid', 'WATCHDOG_PID must name a process.');
+        }
+        if (watchdogPid !== String(pid))
+            return null;
+    }
+    return Number(usec);
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3lzdGVtZHJ1bnRpbWUubGlzdGVuLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfc3lzdGVtZHJ1bnRpbWUvc3lzdGVtZHJ1bnRpbWUubGlzdGVuLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxtQkFBbUIsRUFBRSxNQUFNLGtDQUFrQyxDQUFDO0FBQ3ZFLE9BQU8sRUFBRSxhQUFhLEVBQUUsV0FBVyxFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFDdEUsT0FBTyxFQUFFLHVCQUF1QixFQUFFLHVCQUF1QixFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFFbEcsNEVBQTRFO0FBQzVFLE1BQU0sQ0FBQyxNQUFNLDZCQUE2QixHQUFHLENBQUMsQ0FBQztBQWdCL0M7Ozs7R0FJRztBQUNILE1BQU0sQ0FBQyxNQUFNLGNBQWMsR0FBRyxDQUFDLGFBQXFCLEVBQVEsRUFBRTtJQUM1RCx1QkFBdUIsQ0FBQyxhQUFhLENBQUMsQ0FBQztJQUN2QyxNQUFNLElBQUksR0FBRyxXQUFXLEVBQUUsQ0FBQztJQUMzQixNQUFNLEVBQUUsS0FBSyxFQUFFLEdBQUcsSUFBSSxDQUFDLFNBQVMsQ0FBQztJQUNqQyxNQUFNLEtBQUssR0FBRyxLQUFLLENBQUMsYUFBYSxFQUFFLGFBQWEsQ0FBQyxPQUFPLEVBQUUsQ0FBQyxDQUFDLENBQUM7SUFDN0QsSUFBSSxLQUFLLEdBQUcsQ0FBQyxFQUFFLENBQUM7UUFDZCxNQUFNLElBQUksbUJBQW1CLENBQUMsc0JBQXNCLEVBQUUsY0FBYyxhQUFhLGtCQUFrQixFQUFFO1lBQ25HLEtBQUssRUFBRSxJQUFJLENBQUMsS0FBSyxFQUFFO1NBQ3BCLENBQUMsQ0FBQztJQUNMLENBQUM7SUFDRCxJQUFJLEtBQUssQ0FBQyxhQUFhLEVBQUUsYUFBYSxDQUFDLE9BQU8sRUFBRSxLQUFLLEdBQUcsYUFBYSxDQUFDLFVBQVUsQ0FBQyxHQUFHLENBQUMsRUFBRSxDQUFDO1FBQ3RGLE1BQU0sSUFBSSxtQkFBbUIsQ0FBQyxzQkFBc0IsRUFBRSxjQUFjLGFBQWEsa0NBQWtDLEVBQUU7WUFDbkgsS0FBSyxFQUFFLElBQUksQ0FBQyxLQUFLLEVBQUU7U0FDcEIsQ0FBQyxDQUFDO0lBQ0wsQ0FBQztJQUNELElBQUksQ0FBQyxLQUFLLENBQUMsYUFBYSxFQUFFLGFBQWEsQ0FBQyxPQUFPLEVBQUUsQ0FBQyxDQUFDLEdBQUcsYUFBYSxDQUFDLFVBQVUsQ0FBQyxLQUFLLENBQUMsRUFBRSxDQUFDO1FBQ3RGLE1BQU0sSUFBSSxtQkFBbUIsQ0FBQyxzQkFBc0IsRUFBRSxjQUFjLGFBQWEsOEJBQThCLENBQUMsQ0FBQztJQUNuSCxDQUFDO0FBQ0gsQ0FBQyxDQUFDO0FBRUYsTUFBTSxzQkFBc0IsR0FBRyxlQUFlLENBQUM7QUFDL0MsOEVBQThFO0FBQzlFLE1BQU0sd0JBQXdCLEdBQUcsYUFBYSxHQUFHLDZCQUE2QixDQUFDO0FBRS9FLE1BQU0sYUFBYSxHQUFHLENBQUMsVUFBa0IsRUFBRSxRQUFpQixFQUFFLEVBQUUsQ0FDOUQsSUFBSSxtQkFBbUIsQ0FBQyw0QkFBNEIsRUFBRSxVQUFVLEVBQUUsUUFBUSxLQUFLLFNBQVMsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLEtBQUssRUFBRSxRQUFRLEVBQUUsQ0FBQyxDQUFDO0FBRXZIOzs7Ozs7R0FNRztBQUNILE1BQU0sbUJBQW1CLEdBQUcsR0FBa0IsRUFBRTtJQUM5QyxNQUFNLElBQUksR0FBRyxXQUFXLEVBQUUsQ0FBQztJQUMzQixNQUFNLE1BQU0sR0FBRyxNQUFNLENBQUMsS0FBSyxDQUFDLEVBQUUsQ0FBQyxDQUFDO0lBQ2hDLElBQUksSUFBSSxDQUFDLFNBQVMsQ0FBQyxTQUFTLENBQUMsYUFBYSxDQUFDLGFBQWEsRUFBRSxNQUFNLENBQUMsS0FBSyxDQUFDLEVBQUUsQ0FBQztRQUN4RSxNQUFNLGFBQWEsQ0FBQyxtRUFBbUUsRUFBRSxJQUFJLENBQUMsS0FBSyxFQUFFLENBQUMsQ0FBQztJQUN6RyxDQUFDO0lBQ0QsTUFBTSxJQUFJLEdBQUcsTUFBTSxDQUFDLGVBQWUsQ0FBQyxDQUFDLENBQUMsQ0FBQztJQUN2QyxPQUFPLElBQUksS0FBSyxtQkFBc0IsQ0FBQyxDQUFDLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQyxJQUFJLENBQUM7QUFDdkQsQ0FBQyxDQUFDO0FBRUY7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBaUJHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sNEJBQTRCLEdBQUcsQ0FDMUMsVUFBVSxHQUFzQyxFQUFFLEVBQ2IsRUFBRTtJQUN2QyxNQUFNLEdBQUcsR0FBRyxVQUFVLENBQUMsR0FBRyxJQUFJLE9BQU8sQ0FBQyxHQUFHLENBQUM7SUFDMUMsTUFBTSxHQUFHLEdBQUcsVUFBVSxDQUFDLEdBQUcsSUFBSSxPQUFPLENBQUMsR0FBRyxDQUFDO0lBQzFDLE1BQU0sU0FBUyxHQUFHLEdBQUcsQ0FBQyxVQUFVLENBQUM7SUFDakMsTUFBTSxTQUFTLEdBQUcsR0FBRyxDQUFDLFVBQVUsQ0FBQztJQUNqQyxNQUFNLGFBQWEsR0FBRyxHQUFHLENBQUMsY0FBYyxDQUFDO0lBQ3pDLE9BQU8sR0FBRyxDQUFDLFVBQVUsQ0FBQztJQUN0QixPQUFPLEdBQUcsQ0FBQyxVQUFVLENBQUM7SUFDdEIsT0FBTyxHQUFHLENBQUMsY0FBYyxDQUFDO0lBQzFCLElBQUksU0FBUyxLQUFLLFNBQVMsSUFBSSxTQUFTLEtBQUssU0FBUyxJQUFJLGFBQWEsS0FBSyxTQUFTO1FBQUUsT0FBTyxNQUFNLENBQUMsTUFBTSxDQUFDLEVBQUUsQ0FBQyxDQUFDO0lBQ2hILElBQUksU0FBUyxLQUFLLFNBQVMsSUFBSSxDQUFDLHNCQUFzQixDQUFDLElBQUksQ0FBQyxTQUFTLENBQUMsRUFBRSxDQUFDO1FBQ3ZFLE1BQU0sYUFBYSxDQUFDLGlDQUFpQyxDQUFDLENBQUM7SUFDekQsQ0FBQztJQUNELElBQUksU0FBUyxLQUFLLE1BQU0sQ0FBQyxHQUFHLENBQUM7UUFBRSxPQUFPLE1BQU0sQ0FBQyxNQUFNLENBQUMsRUFBRSxDQUFDLENBQUM7SUFDeEQsSUFBSSxTQUFTLEtBQUssU0FBUyxJQUFJLENBQUMsc0JBQXNCLENBQUMsSUFBSSxDQUFDLFNBQVMsQ0FBQyxJQUFJLE1BQU0sQ0FBQyxTQUFTLENBQUMsR0FBRyx3QkFBd0IsRUFBRSxDQUFDO1FBQ3ZILE1BQU0sYUFBYSxDQUFDLGlEQUFpRCxDQUFDLENBQUM7SUFDekUsQ0FBQztJQUNELE1BQU0sS0FBSyxHQUFHLE1BQU0sQ0FBQyxTQUFTLENBQUMsQ0FBQztJQUNoQyxrRUFBa0U7SUFDbEUsTUFBTSxTQUFTLEdBQUcsbUJBQW1CLEVBQUUsQ0FBQztJQUN4QyxJQUFJLFNBQVMsS0FBSyxJQUFJLElBQUksTUFBTSxDQUFDLDZCQUE2QixHQUFHLEtBQUssQ0FBQyxHQUFHLFNBQVMsRUFBRSxDQUFDO1FBQ3BGLE1BQU0sYUFBYSxDQUFDLHFCQUFxQixLQUFLLDRCQUE0Qiw2QkFBNkIsR0FBRyxLQUFLLEdBQUcsQ0FBQyxzREFBc0QsU0FBUyxJQUFJLENBQUMsQ0FBQztJQUMxTCxDQUFDO0lBQ0Qsc0dBQXNHO0lBQ3RHLE1BQU0sS0FBSyxHQUFHLGFBQWEsS0FBSyxTQUFTLENBQUMsQ0FBQyxDQUFDLElBQUksQ0FBQyxDQUFDLENBQUMsYUFBYSxDQUFDLEtBQUssQ0FBQyxHQUFHLENBQUMsQ0FBQztJQUM1RSxJQUFJLEtBQUssS0FBSyxJQUFJLEVBQUUsQ0FBQztRQUNuQixJQUFJLEtBQUssQ0FBQyxNQUFNLEtBQUssS0FBSztZQUFFLE1BQU0sYUFBYSxDQUFDLHdCQUF3QixLQUFLLENBQUMsTUFBTSxtQ0FBbUMsS0FBSyxHQUFHLENBQUMsQ0FBQztRQUNqSSxJQUFJLENBQUMsS0FBSyxDQUFDLEtBQUssQ0FBQyxDQUFDLElBQUksRUFBRSxFQUFFLENBQUMsdUJBQXVCLENBQUMsSUFBSSxFQUFFLEtBQUssQ0FBQyxDQUFDO1lBQUUsTUFBTSxhQUFhLENBQUMsdUNBQXVDLENBQUMsQ0FBQztJQUNqSSxDQUFDO0lBQ0QsZ0dBQWdHO0lBQ2hHLDZFQUE2RTtJQUM3RSxNQUFNLFdBQVcsR0FBK0IsRUFBRSxDQUFDO0lBQ25ELEtBQUssSUFBSSxLQUFLLEdBQUcsQ0FBQyxFQUFFLEtBQUssR0FBRyxLQUFLLEVBQUUsS0FBSyxFQUFFLEVBQUUsQ0FBQztRQUMzQyxNQUFNLFVBQVUsR0FBRyw2QkFBNkIsR0FBRyxLQUFLLENBQUM7UUFDekQsY0FBYyxDQUFDLFVBQVUsQ0FBQyxDQUFDO1FBQzNCLFdBQVcsQ0FBQyxJQUFJLENBQUMsTUFBTSxDQUFDLE1BQU0sQ0FBQyxFQUFFLFVBQVUsRUFBRSxJQUFJLEVBQUUsS0FBSyxLQUFLLElBQUksQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQyxLQUFLLENBQUMsS0FBSyxDQUFDLEVBQUUsQ0FBQyxDQUFDLENBQUM7SUFDbkcsQ0FBQztJQUNELE9BQU8sTUFBTSxDQUFDLE1BQU0sQ0FBQyxXQUFXLENBQUMsQ0FBQztBQUNwQyxDQUFDLENBQUM7QUFFRjs7Ozs7R0FLRztBQUNILE1BQU0sQ0FBQyxNQUFNLG9CQUFvQixHQUFHLENBQUMsVUFBVSxHQUFzQyxFQUFFLEVBQWlCLEVBQUU7SUFDeEcsTUFBTSxHQUFHLEdBQUcsVUFBVSxDQUFDLEdBQUcsSUFBSSxPQUFPLENBQUMsR0FBRyxDQUFDO0lBQzFDLE1BQU0sR0FBRyxHQUFHLFVBQVUsQ0FBQyxHQUFHLElBQUksT0FBTyxDQUFDLEdBQUcsQ0FBQztJQUMxQyxNQUFNLElBQUksR0FBRyxHQUFHLENBQUMsYUFBYSxDQUFDO0lBQy9CLE1BQU0sV0FBVyxHQUFHLEdBQUcsQ0FBQyxZQUFZLENBQUM7SUFDckMsSUFBSSxJQUFJLEtBQUssU0FBUztRQUFFLE9BQU8sSUFBSSxDQUFDO0lBQ3BDLElBQUksQ0FBQyxzQkFBc0IsQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxNQUFNLENBQUMsYUFBYSxDQUFDLE1BQU0sQ0FBQyxJQUFJLENBQUMsQ0FBQyxFQUFFLENBQUM7UUFDOUUsTUFBTSxJQUFJLG1CQUFtQixDQUFDLDhCQUE4QixFQUFFLDJDQUEyQyxDQUFDLENBQUM7SUFDN0csQ0FBQztJQUNELElBQUksV0FBVyxLQUFLLFNBQVMsRUFBRSxDQUFDO1FBQzlCLElBQUksQ0FBQyxzQkFBc0IsQ0FBQyxJQUFJLENBQUMsV0FBVyxDQUFDLEVBQUUsQ0FBQztZQUM5QyxNQUFNLElBQUksbUJBQW1CLENBQUMsOEJBQThCLEVBQUUsbUNBQW1DLENBQUMsQ0FBQztRQUNyRyxDQUFDO1FBQ0QsSUFBSSxXQUFXLEtBQUssTUFBTSxDQUFDLEdBQUcsQ0FBQztZQUFFLE9BQU8sSUFBSSxDQUFDO0lBQy9DLENBQUM7SUFDRCxPQUFPLE1BQU0sQ0FBQyxJQUFJLENBQUMsQ0FBQztBQUN0QixDQUFDLENBQUMifQ==

package/dist_ts_systemdruntime/systemdruntime.validation.d.ts

@@ -0,0 +1,13 @@
+/** `FDNAME_MAX`: the longest descriptor name systemd accepts. */
+export declare const descriptorNameMaximumLength = 255;
+/**
+ * systemd's `fdname_is_valid()` (src/basic/fd-util.c, v255): printable ASCII except `:`, at most
+ * 255 characters. systemd also admits the empty name; `nonEmptyArg` refuses it where a name has to
+ * identify a descriptor.
+ */
+export declare const isSystemdDescriptorName: (nameArg: unknown, nonEmptyArg: boolean) => nameArg is string;
+/** An `AF_UNIX` notification address: an absolute path or an abstract name written `@name`. */
+export declare const isSystemdNotifySocketAddress: (addressArg: unknown) => addressArg is string;
+export declare const assertSystemdNotifySocketAddress: (addressArg: string) => void;
+export declare const isSystemdDescriptor: (descriptorArg: unknown) => descriptorArg is number;
+export declare const assertSystemdDescriptor: (descriptorArg: number) => void;

package/dist_ts_systemdruntime/systemdruntime.validation.js

@@ -0,0 +1,29 @@
+import { SystemdRuntimeError } from './classes.systemdruntimeerror.js';
+import { socketAddressMaximumBytes } from './systemdruntime.libc.js';
+/** `FDNAME_MAX`: the longest descriptor name systemd accepts. */
+export const descriptorNameMaximumLength = 255;
+/**
+ * systemd's `fdname_is_valid()` (src/basic/fd-util.c, v255): printable ASCII except `:`, at most
+ * 255 characters. systemd also admits the empty name; `nonEmptyArg` refuses it where a name has to
+ * identify a descriptor.
+ */
+export const isSystemdDescriptorName = (nameArg, nonEmptyArg) => typeof nameArg === 'string' && nameArg.length <= descriptorNameMaximumLength &&
+    (!nonEmptyArg || nameArg.length > 0) && /^[\x20-\x39\x3b-\x7e]*$/.test(nameArg);
+/** An `AF_UNIX` notification address: an absolute path or an abstract name written `@name`. */
+export const isSystemdNotifySocketAddress = (addressArg) => typeof addressArg === 'string' && /^[/@]./s.test(addressArg) && !addressArg.includes('\0') &&
+    Buffer.byteLength(addressArg, 'utf8') <= socketAddressMaximumBytes;
+export const assertSystemdNotifySocketAddress = (addressArg) => {
+    if (!isSystemdNotifySocketAddress(addressArg)) {
+        throw new SystemdRuntimeError('notify_socket_invalid', 'NOTIFY_SOCKET must be an absolute AF_UNIX path or an abstract name (@name) of at most 107 bytes without NUL.');
+    }
+};
+/** The largest descriptor number the kernel can hand out (`INT_MAX`). */
+const descriptorMaximum = 2_147_483_647;
+export const isSystemdDescriptor = (descriptorArg) => typeof descriptorArg === 'number' && Number.isSafeInteger(descriptorArg) && descriptorArg >= 0 &&
+    descriptorArg <= descriptorMaximum;
+export const assertSystemdDescriptor = (descriptorArg) => {
+    if (!isSystemdDescriptor(descriptorArg)) {
+        throw new SystemdRuntimeError('descriptor_invalid', `${String(descriptorArg)} is not a descriptor number.`);
+    }
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3lzdGVtZHJ1bnRpbWUudmFsaWRhdGlvbi5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX3N5c3RlbWRydW50aW1lL3N5c3RlbWRydW50aW1lLnZhbGlkYXRpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sa0NBQWtDLENBQUM7QUFDdkUsT0FBTyxFQUFFLHlCQUF5QixFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFFckUsaUVBQWlFO0FBQ2pFLE1BQU0sQ0FBQyxNQUFNLDJCQUEyQixHQUFHLEdBQUcsQ0FBQztBQUUvQzs7OztHQUlHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sdUJBQXVCLEdBQUcsQ0FBQyxPQUFnQixFQUFFLFdBQW9CLEVBQXFCLEVBQUUsQ0FDbkcsT0FBTyxPQUFPLEtBQUssUUFBUSxJQUFJLE9BQU8sQ0FBQyxNQUFNLElBQUksMkJBQTJCO0lBQzVFLENBQUMsQ0FBQyxXQUFXLElBQUksT0FBTyxDQUFDLE1BQU0sR0FBRyxDQUFDLENBQUMsSUFBSSx5QkFBeUIsQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDLENBQUM7QUFFbEYsK0ZBQStGO0FBQy9GLE1BQU0sQ0FBQyxNQUFNLDRCQUE0QixHQUFHLENBQUMsVUFBbUIsRUFBd0IsRUFBRSxDQUN4RixPQUFPLFVBQVUsS0FBSyxRQUFRLElBQUksU0FBUyxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUMsSUFBSSxDQUFDLFVBQVUsQ0FBQyxRQUFRLENBQUMsSUFBSSxDQUFDO0lBQzFGLE1BQU0sQ0FBQyxVQUFVLENBQUMsVUFBVSxFQUFFLE1BQU0sQ0FBQyxJQUFJLHlCQUF5QixDQUFDO0FBRXJFLE1BQU0sQ0FBQyxNQUFNLGdDQUFnQyxHQUFHLENBQUMsVUFBa0IsRUFBUSxFQUFFO0lBQzNFLElBQUksQ0FBQyw0QkFBNEIsQ0FBQyxVQUFVLENBQUMsRUFBRSxDQUFDO1FBQzlDLE1BQU0sSUFBSSxtQkFBbUIsQ0FDM0IsdUJBQXVCLEVBQ3ZCLDhHQUE4RyxDQUMvRyxDQUFDO0lBQ0osQ0FBQztBQUNILENBQUMsQ0FBQztBQUVGLHlFQUF5RTtBQUN6RSxNQUFNLGlCQUFpQixHQUFHLGFBQWEsQ0FBQztBQUV4QyxNQUFNLENBQUMsTUFBTSxtQkFBbUIsR0FBRyxDQUFDLGFBQXNCLEVBQTJCLEVBQUUsQ0FDckYsT0FBTyxhQUFhLEtBQUssUUFBUSxJQUFJLE1BQU0sQ0FBQyxhQUFhLENBQUMsYUFBYSxDQUFDLElBQUksYUFBYSxJQUFJLENBQUM7SUFDOUYsYUFBYSxJQUFJLGlCQUFpQixDQUFDO0FBRXJDLE1BQU0sQ0FBQyxNQUFNLHVCQUF1QixHQUFHLENBQUMsYUFBcUIsRUFBUSxFQUFFO0lBQ3JFLElBQUksQ0FBQyxtQkFBbUIsQ0FBQyxhQUFhLENBQUMsRUFBRSxDQUFDO1FBQ3hDLE1BQU0sSUFBSSxtQkFBbUIsQ0FBQyxvQkFBb0IsRUFBRSxHQUFHLE1BQU0sQ0FBQyxhQUFhLENBQUMsOEJBQThCLENBQUMsQ0FBQztJQUM5RyxDQUFDO0FBQ0gsQ0FBQyxDQUFDIn0=

package/package.json

@@ -1,10 +1,21 @@
 {
   "name": "@push.rocks/smartdaemon",
-  "version": "2.20.1",
+  "version": "2.22.0",
   "private": false,
   "description": "Start scripts as long running daemons and manage them.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist_ts/index.d.ts",
+      "default": "./dist_ts/index.js"
+    },
+    "./systemd-runtime": {
+      "types": "./dist_ts_systemdruntime/index.d.ts",
+      "default": "./dist_ts_systemdruntime/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "type": "module",
   "author": "Task Venture Capital GmbH <hello@task.vc>",
   "license": "MIT",
@@ -26,10 +37,10 @@
   },
   "homepage": "https://code.foss.global/push.rocks/smartdaemon",
   "devDependencies": {
-    "@git.zone/tsbuild": "^5.1.2",
-    "@git.zone/tsrun": "^3.0.2",
-    "@git.zone/tstest": "^7.1.0",
-    "@types/node": "^26.6.3"
+    "@git.zone/tsbuild": "^6.0.2",
+    "@git.zone/tsrun": "^3.0.3",
+    "@git.zone/tstest": "^7.2.1",
+    "@types/node": "^26.6.4"
   },
   "dependencies": {
     "@push.rocks/lik": "^6.4.4",
@@ -41,6 +52,7 @@
   },
   "files": [
     "ts/**/*",
+    "ts_systemdruntime/**/*",
     "ts_web/**/*",
     "dist/**/*",
     "dist_*/**/*",
@@ -58,7 +70,7 @@
   ],
   "scripts": {
     "test": "tstest test/ --verbose --timeout 60",
-    "build": "tsbuild --web",
+    "build": "tsbuild tsfolders --web",
     "format": "gitzone format",
     "buildDocs": "tsdoc"
   }

package/readme.md

@@ -338,6 +338,12 @@ installation scope, after any required offline commissioning. A failed or timed
 out command can leave partial enablement; inspect and retry the exact operation
 without assuming cancellation or undoing the application's retained protection.
 
+`disable()` is its counterpart: it removes the enablement links the unit's `[Install]`
+section names (`systemctl disable`) and returns a fresh snapshot. It does not stop a running
+unit, mask, unmask or remove the definition, so a disabled service keeps running until it is
+stopped. A failed or timed out command can leave partial enablement as well; inspect and retry.
+Disable a unit before `SystemdUnitFile.uninstall()` removes its definition.
+
 `inspectRelationships()` returns immutable sorted arrays for `before`, `after`,
 `requires`, `wants`, `conflicts`, `requiredBy` and `wantedBy` from the loaded manager
 graph. Literal systemd hex escapes are preserved. The bounded snapshot rejects
@@ -391,7 +397,7 @@ try {
 explicit restart policy, kill mode and stop timeout. System-scope definitions require
 `user` and `group`; user-scope definitions reject both directives because the user
 manager already runs under the calling identity. It defaults to `Type=exec`,
-journal output and null stdin. It introduces no shell; percent specifiers and
+journal output (see `standardOutput` and `standardError` below) and null stdin. It introduces no shell; percent specifiers and
 argument environment expansion are escaped. Paths must be absolute and normalized.
 Descriptions, paths and arguments reject control characters, lone surrogates and Unicode
 noncharacters (U+FDD0–U+FDEF and every code point ending in FFFE or FFFF), which systemd
@@ -464,6 +470,7 @@ A user-scope `SystemdUnitFile` validates each value where it is read:
   calls need, plus a well-formed config root (`XDG_CONFIG_HOME`, or `~/.config`), and
   rejects anything missing or malformed with `invalid_options` before touching any
   directory or running `systemctl`.
+- `uninstall()` needs the same and refuses the same way, before removing anything.
 
 An owner can therefore ask whether its definition is installed from a context without
 a login session:
@@ -631,6 +638,41 @@ and `%` doubled, so systemd applies no specifier; `Environment=` never expands `
 taken literally. An empty object renders nothing. Systemd merges these variables over its own
 (`HOME`, `USER`, `INVOCATION_ID`, …), so a name such as `NOTIFY_SOCKET` overrides the manager's value.
 
+`standardOutput` and `standardError` say where the service's output streams go
+(`StandardOutput=`, `StandardError=`): `'journal'`, the default, `'null'`, which discards the
+stream, or `{ append: path }`, which appends it to a file (`append:`, systemd 240 and later).
+Omitted, both render `journal` as before, so existing definitions keep their bytes.
+
+```typescript
+const controller = new SystemdServiceDefinition({
+  scope: 'user',
+  unitName: 'app-controller.service',
+  description: 'App controller',
+  executable: '/home/owner/.local/share/pnpm/app',
+  args: ['serve'],
+  workingDirectory: '/home/owner',
+  restart: 'on-failure',
+  killMode: 'process',
+  timeoutStopSeconds: 90,
+  standardOutput: 'null',
+  standardError: { append: '/home/owner/.config/app/logs/controller.log' },
+});
+// StandardOutput=null
+// StandardError=append:/home/owner/.config/app/logs/controller.log
+```
+
+The path must be absolute and normalized, without a backslash, surrounding whitespace or a
+trailing slash; `%` is doubled, so systemd applies no specifier. The service manager opens the file
+before it invokes the executable and before it switches to the service's `User=`, so with its own
+privileges: as root under the system manager, as the user under a user manager. It creates a missing
+file owned by that user with mode 0666 masked by the unit's umask (0644 under the usual umask 0022).
+Its directory must already exist, or the service fails to start. A caller that needs another owner
+or a private file creates it with the owner and mode it wants first; an existing file keeps both.
+Systemd reads `append:` from version 240 and an older manager would ignore the line, so a definition
+with an `append` output has `requiredManagerMajor` 240 (254 with `fileDescriptorStorePreserve` as
+well) and `SystemdUnitFile.install()` refuses it on an older manager with `manager_too_old`. The manager reports only the kind of output (`append`) as a property, not the path, so
+`inspectServiceSettings()` does not report it: verify an installed definition by its digest.
+
 #### Notify access and the file descriptor store
 
 A service that keeps a descriptor across its own restarts, such as a network namespace a child
@@ -654,8 +696,9 @@ empties the store; a `systemctl soft-reboot` keeps the running kernel, so a pres
 descriptors in it pass on to the next userspace boot. Systemd reads `FileDescriptorStorePreserve=` from version 254
 and an older manager would ignore the line, so a definition with `fileDescriptorStorePreserve` has
 `requiredManagerMajor` 254 and `SystemdUnitFile.install()` refuses it on an older manager with
-`SystemdUnitManagerTooOldError` (`manager_too_old`) before touching anything; every other definition
-has `requiredManagerMajor` null. Sending `FDSTORE=1` needs an `AF_UNIX` socket, so a definition
+`SystemdUnitManagerTooOldError` (`manager_too_old`) before touching anything. `requiredManagerMajor` is
+the highest major any rendered line needs (240 for an `append` output, see above); a definition with
+neither has it null. Sending `FDSTORE=1` needs an `AF_UNIX` socket, so a definition
 with a store or a notify access other than `'none'` that restricts its socket families must allow
 `AF_UNIX`. Omitted, each option renders nothing.
 
@@ -910,6 +953,42 @@ user scope requires `expectedUid` to match the caller's actual uid. The manager'
 selected fragment must match the installed file after reload, so an unrecognized
 custom user unit path fails closed.
 
+#### Removing an installed definition
+
+`uninstall(expectedSha256)` removes what `install()` wrote: the unit file, when it holds exactly
+the bytes `expectedSha256` digests, and every previous definition retained beside it
+(`<unit>.previous-<sha256>`), then reloads the manager and verifies its view.
+
+```typescript
+const unit = new SystemdUnit({ scope: 'user', unitName: 'authswitch.service' });
+const userFile = new SystemdUnitFile({ scope: 'user', unitName: 'authswitch.service' });
+await unit.stop();
+await unit.disable();
+const installed = await userFile.inspect();
+if (installed) {
+  const result = await userFile.uninstall(installed.sha256);
+  console.log(result.removed, result.masked, result.removedPaths);
+}
+```
+
+It admits the unit only at rest (`systemdUnitQuiescence()`) with no job queued, no pending reload
+and no drop-ins, while the manager still selects this file, and refuses with the same
+`SystemdUnitFileUnsafeUnitError` reasons as installation. Removal admits fewer unit-file states: a
+loaded unit must be `disabled`, so no enablement link outlives its definition (an enabled one is
+refused with `unexpected_file_state`; disable it first), a masked unit keeps its mask, and a unit the
+manager does not find is admitted. A stopped service whose `killMode: 'process'` left processes
+running still has a control group and is refused with `active` until they end.
+
+Every file is checked as installation checks the unit file (regular, single link, mode 0644, owned
+by the expected uid) and is removed only while its name still holds the file that was checked; a
+retained definition whose bytes do not match the digest in its name, or a unit file with other bytes
+than expected, refuses the removal with `changed` before anything is removed. After removal the
+manager must report the unit not found (still masked, for a masked unit) and at rest, or the call
+rejects with `reload_failed`, the files already removed and the cause attached. With nothing to
+remove the call resolves `{ removed: false, … }` without reloading the manager. `removed` reports
+whether the unit file itself was removed and `removedPaths` every file that was. Removal never
+stops, disables or unmasks the unit.
+
 With `killMode: 'mixed'`, the main process owns graceful child shutdown and must
 remain alive until its children have joined. Systemd sends SIGTERM to the main
 process first and can send SIGKILL to the whole cgroup when the main process exits
@@ -919,6 +998,106 @@ other process in the unit survives, so the main process must own their shutdown
 deliberate retention (as with `Delegate=yes` workloads). A successful systemd start still requires application readiness
 verification, and a completed stop alone does not prove database drain.
 
+### The service side: notifications and passed descriptors (`/systemd-runtime`, Node.js 26)
+
+The definitions above tell the manager what to expect; a Node.js main process answers it through
+the `@push.rocks/smartdaemon/systemd-runtime` subpath: `sd_notify(3)` messages (with descriptors
+for the store) and the descriptors the manager passes (`LISTEN_FDS`). Node.js has no `AF_UNIX`
+datagram socket and no `fcntl(2)`, so the subpath calls glibc through `node:ffi`:
+
+- It requires **Node.js 26 or later**. Importing it on an older Node.js throws
+  `SystemdRuntimeError` with code `runtime_unsupported`; the main entry is unaffected and keeps
+  its Node.js range. The package is ES modules: CommonJS can `require()` either entry only on a
+  Node.js that loads ES modules through `require()` by default (20.19+, 22.12+, 23+), where the
+  subpath throws the same `runtime_unsupported` below 26; an older Node.js throws `ERR_REQUIRE_ESM`.
+- It runs on Linux x64 and arm64 with glibc (`libc.so.6`). Elsewhere, and with `node:ffi`
+  unavailable (`--no-experimental-ffi`) or denied by the permission model, the first call that
+  needs libc throws `runtime_unsupported`. Under the permission model pass `--allow-ffi`.
+- `node:ffi` is experimental: loading it prints one `ExperimentalWarning`. A single executable
+  application suppresses it through its `execArgv` (`--disable-warning=ExperimentalWarning`).
+- libc is opened on first use. Outside systemd nothing is loaded: without `NOTIFY_SOCKET`
+  `SystemdNotifier.fromEnvironment()` returns null, and without `LISTEN_*` variables
+  `takeSystemdListenDescriptors()` returns an empty list.
+
+```typescript
+import {
+  SystemdNotifier,
+  takeSystemdListenDescriptors,
+  watchdogIntervalUsec,
+} from '@push.rocks/smartdaemon/systemd-runtime';
+
+// Descriptors passed for this process, numbered from 3, already close-on-exec.
+const passed = takeSystemdListenDescriptors(); // [{ descriptor: 3, name: 'pallet-router' }]
+const namespaceDescriptor = passed.find(({ name }) => name === 'pallet-router')?.descriptor ?? createNamespace();
+
+// null when no service manager listens; the caller decides what that means.
+const notifier = SystemdNotifier.fromEnvironment({ take: true });
+if (notifier) {
+  notifier.extendTimeout(60_000_000, 'replaying journal');
+  notifier.replaceDescriptors('pallet-router', [namespaceDescriptor], { poll: false });
+  notifier.ready('serving');
+  const interval = watchdogIntervalUsec();
+  if (interval !== null) setInterval(() => notifier.watchdog(), interval / 2000);
+}
+```
+
+| Call | Sends or does |
+| --- | --- |
+| `ready(status?)` | `READY=1` (and `STATUS=`) |
+| `status(text)` | `STATUS=` |
+| `stopping(status?)` | `STOPPING=1` |
+| `reloading(status?)` | `RELOADING=1` with `MONOTONIC_USEC=` (`CLOCK_MONOTONIC`); send `ready()` when done |
+| `watchdog()` | `WATCHDOG=1` |
+| `extendTimeout(usec, status?)` | `EXTEND_TIMEOUT_USEC=` |
+| `storeDescriptors(name, fds, { poll? })` | `FDSTORE=1`, `FDNAME=`, `FDPOLL=0` for `poll: false`; descriptors as `SCM_RIGHTS` |
+| `removeDescriptors(name)` | `FDSTOREREMOVE=1`, `FDNAME=` |
+| `replaceDescriptors(name, fds, { poll? })` | remove, then store: two messages, handled in order |
+| `send(fields, fds?)` | any `NAME=value` fields in insertion order |
+| `takeSystemdNotifySocket()` | removes `NOTIFY_SOCKET` from the environment and returns it validated, or null |
+| `takeSystemdListenDescriptors()` | removes `LISTEN_PID`/`LISTEN_FDS`/`LISTEN_FDNAMES`; for this process marks every passed descriptor close-on-exec and returns it with its name (`unknown` without names) |
+| `setCloseOnExec(fd)` | `fcntl(F_SETFD, FD_CLOEXEC)`, verified |
+| `watchdogIntervalUsec()` | `WATCHDOG_USEC` for this process (`WATCHDOG_PID`), or null |
+
+Every call is synchronous and either completes or throws `SystemdRuntimeError` (`code`, and
+`errno` when a libc call failed); nothing is dropped silently. systemd ignores a message it cannot
+parse without telling the sender, so the notifier refuses it first: field names are upper-case,
+values carry no newline or NUL, a message is at most 4096 bytes (`notify_field_invalid`); a
+descriptor name is 1–255 printable ASCII characters without `:` (`descriptor_name_invalid`); one
+message carries 1–253 descriptors (`descriptor_invalid`). `NOTIFY_SOCKET` must be an absolute
+path or an abstract name (`@name`) of at most 107 bytes; anything else, `vsock:` addresses
+included, is `notify_socket_invalid`. A send the kernel refuses is `notify_failed` with its errno
+(`ENOENT` for a missing path, `ECONNREFUSED` for an abstract name nobody holds). `LISTEN_*`
+variables naming another process are removed and nothing else is touched; a partial or malformed
+set (`LISTEN_FDS` not a positive integer, a names list of another length) is
+`listen_environment_invalid` before any descriptor is touched, and a passed descriptor that is not
+open is `close_on_exec_failed`.
+
+`LISTEN_FDS` is also bounded by the process's hard `RLIMIT_NOFILE` before any descriptor is touched:
+a count whose last descriptor (`2 + count`) is at or above that limit is
+`listen_environment_invalid`. No descriptor systemd passed can lie at or above the hard limit,
+because it moves them into place with `fcntl(F_DUPFD)` (which refuses a number at or above the soft
+limit) after applying the unit's limits; a wrapper that lowers its hard limit below a passed
+descriptor before starting Node.js is refused. The hard limit can be as large as `fs.nr_open`
+(`LimitNOFILE=infinity`), so nothing is allocated per counted descriptor up front: like
+`sd_listen_fds(3)`, the descriptors are marked one by one from 3, the first that is not open throws
+`close_on_exec_failed` (the ones before it keep the flag), and the list grows only with open
+descriptors.
+
+Sends are blocking `sendmsg(2)` calls on a fresh `AF_UNIX` datagram socket, the same as
+`sd_notify(3)`: when the manager's receive queue is full, the call waits for room and the event loop
+stalls for that time.
+
+`node:ffi` has no errno API: the subpath reads glibc's thread-local `errno` through
+`__errno_location()` immediately after the failed call. Node.js itself calls libuv's
+`uv_disable_stdio_inheritance()` at startup (`InitializeNodeWithArgsInternal()` in `src/node.cc`;
+`deps/uv/src/unix/core.c`, Node.js 25.9.0 and 26.11.1), which marks descriptors 0–15 close-on-exec
+and continues past 15 until the first descriptor that is not open. The subpath still sets and
+verifies the flag on every passed descriptor, as `sd_listen_fds(3)` does.
+
+`test/test.systemdruntimeunit.node.ts` proves the subpath under a real `Type=notify` unit of the
+caller's user manager (`systemd-run --user`), and skips with the reason without Node.js 26 or a
+user manager.
+
 ### Starting a program in its own transient scope
 
 A service that launches a long-lived program keeps that program in its own
@@ -1172,7 +1351,11 @@ console.log(template); // View generated systemd unit file
 - **systemd 254 or later** for `SystemdUnit.inspectServiceSettings()`, `SystemdUnit.cleanFileDescriptorStore()`,
   `runInTransientScope()` and for installing a definition with `fileDescriptorStorePreserve` (Debian 13,
   Ubuntu 24.04, Fedora 39 and later ship it); an older manager is refused by name with `manager_too_old`
+- **systemd 240 or later** for installing a definition with an `append` output (`standardOutput` or
+  `standardError`), refused the same way
 - **Node.js**: Version 14.x or higher
+- **Node.js 26 or later** for the `@push.rocks/smartdaemon/systemd-runtime` subpath (`node:ffi`), on Linux
+  x64 or arm64 with glibc
 - **Permissions**: Either root access or properly configured sudo
 
 ## ⚙️ Generated Systemd Service Files

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartdaemon',
-  version: '2.20.1',
+  version: '2.22.0',
   description: 'Start scripts as long running daemons and manage them.'
 }

package/ts/classes.systemdservicedefinition.ts

@@ -1,11 +1,12 @@
 import * as plugins from './smartdaemon.plugins.js';
 import { environmentByteLimit, environmentVariableLimit, isCleanText, renderServiceRelations, systemdAddressFamilies,
   systemdCapabilities, type TSystemdServiceStartup, type ISystemdServiceDependencies, type ISystemdServiceInstallTargets,
-  type ISystemdServiceCredential, type TSystemdCapability, type TSystemdAddressFamily } from './systemd.definition.js';
-import { fileDescriptorStorePreserveMajor } from './systemd.managerversion.js';
+  type ISystemdServiceCredential, type TSystemdCapability, type TSystemdAddressFamily,
+  type TSystemdServiceOutput } from './systemd.definition.js';
+import { fileDescriptorStorePreserveMajor, outputAppendMajor } from './systemd.managerversion.js';
 export type { ISystemdServiceStartup, ISystemdServiceNotifyStartup, TSystemdServiceStartup,
   ISystemdServiceDependencies, ISystemdServiceInstallTargets, ISystemdServiceCredential, TSystemdCapability,
-  TSystemdAddressFamily } from './systemd.definition.js';
+  TSystemdAddressFamily, TSystemdServiceOutput } from './systemd.definition.js';
 export { systemdCapabilities, systemdAddressFamilies } from './systemd.definition.js';
 
 interface ISystemdServiceDefinitionBaseOptions {
@@ -78,6 +79,17 @@ interface ISystemdServiceDefinitionBaseOptions {
    * 64 variables and 8192 UTF-8 bytes of `NAME=value` in total. They are taken literally: `%` is escaped, and `Environment=` never expands `$`.
    */
   environment?: Readonly<Record<string, string>>;
+  /**
+   * Where the service's standard output goes (`StandardOutput=`): `'journal'` (the default),
+   * `'null'`, or `{ append: path }`, an absolute normalized path without a backslash, surrounding
+   * whitespace or trailing slash, whose file systemd appends to (`append:`, systemd 240 and later).
+   * An `append` output sets `requiredManagerMajor` to at least 240, so `SystemdUnitFile.install()`
+   * refuses an older manager, which would ignore the line. Omitted, the unit renders
+   * `StandardOutput=journal` as before.
+   */
+  standardOutput?: TSystemdServiceOutput;
+  /** Where the service's standard error goes (`StandardError=`), as `standardOutput`; omitted, `journal`. */
+  standardError?: TSystemdServiceOutput;
   /**
    * System scope only. Runs the service as a transient user and group allocated at start
    * (`DynamicUser=`), named by `user` and `group`, which then must not be `root` and have at most
@@ -177,8 +189,9 @@ export class SystemdServiceDefinition {
   public readonly sha256: string;
   /**
    * The oldest systemd major whose manager reads every directive this definition renders, when it
-   * renders one an older manager would ignore: 254 with `fileDescriptorStorePreserve`; otherwise
-   * null. `SystemdUnitFile.install()` refuses a definition on an older manager.
+   * renders one an older manager would ignore: the highest of 254 with `fileDescriptorStorePreserve`
+   * and 240 with an `append` output; otherwise null. `SystemdUnitFile.install()` refuses a
+   * definition on an older manager.
    */
   public readonly requiredManagerMajor: number | null;
 
@@ -217,7 +230,8 @@ export class SystemdServiceDefinition {
     const optionalKeys: TSystemdServiceDefinitionOption[] = ['scope', 'startup', 'dependencies', 'install',
       'restartSeconds', 'restartPreventExitStatus', 'successExitStatus', 'startLimitIntervalSeconds',
       'startLimitBurst', 'delegate', 'limitNoFile', 'tasksMax', 'oomScoreAdjust', 'notifyAccess',
-      'fileDescriptorStoreMax', 'fileDescriptorStorePreserve', 'environment', ...systemOnlyOptions];
+      'fileDescriptorStoreMax', 'fileDescriptorStorePreserve', 'environment', 'standardOutput', 'standardError',
+      ...systemOnlyOptions];
     // Every own key is a known option held by an enumerable data property, so no accessor or trap runs.
     for (const key of Reflect.ownKeys(options)) {
       requireValue(typeof key === 'string' && [...keys, ...optionalKeys, 'user', 'group'].includes(key as never), 'options');
@@ -334,6 +348,25 @@ export class SystemdServiceDefinition {
       service.push(...[...assignments.keys()].sort()
         .map((name) => `Environment=${quote(assignments.get(name)!)}`));
     }
+    /**
+     * An output stream's directive value, read once through the object's own data descriptor. An
+     * `append:` path is taken raw after specifier expansion, so only `%` is escaped.
+     */
+    const output = (value: unknown, option: 'standardOutput' | 'standardError'): string => {
+      if (value === undefined || value === 'journal') return 'journal';
+      if (value === 'null') return 'null';
+      plainObject(value, option);
+      const entryKeys = Reflect.ownKeys(value as object);
+      const descriptor = Object.getOwnPropertyDescriptor(value, 'append');
+      requireValue(entryKeys.length === 1 && entryKeys[0] === 'append' && descriptor?.enumerable &&
+        'value' in descriptor, option);
+      const file: unknown = descriptor!.value;
+      requireValue(absolute(file) && !file.endsWith('/') && file.trim() === file &&
+        !file.includes('\\'), option);
+      return `append:${(file as string).replaceAll('%', '%%')}`;
+    };
+    const standardOutput = output(options.standardOutput, 'standardOutput');
+    const standardError = output(options.standardError, 'standardError');
     // Every system-only option is refused by name in a user manager's service.
     for (const option of systemOnlyOptions) {
       requireValue(scope === 'system' || options[option] === undefined, option);
@@ -508,8 +541,8 @@ export class SystemdServiceDefinition {
       `TimeoutStopSec=${options.timeoutStopSeconds}s`,
       ...service,
       'StandardInput=null',
-      'StandardOutput=journal',
-      'StandardError=journal',
+      `StandardOutput=${standardOutput}`,
+      `StandardError=${standardError}`,
       '',
       '[Install]',
       ...relations.install,
@@ -517,8 +550,12 @@ export class SystemdServiceDefinition {
     ].join('\n');
     requireValue(Buffer.byteLength(this.content) <= 16384, 'options');
     this.sha256 = plugins.crypto.createHash('sha256').update(this.content).digest('hex');
-    this.requiredManagerMajor = options.fileDescriptorStorePreserve !== undefined
-      ? fileDescriptorStorePreserveMajor : null;
+    // An older manager ignores a directive it does not read, so the newest one any line needs counts.
+    const requiredMajors = [
+      ...(options.fileDescriptorStorePreserve !== undefined ? [fileDescriptorStorePreserveMajor] : []),
+      ...([standardOutput, standardError].some((value) => value.startsWith('append:')) ? [outputAppendMajor] : []),
+    ];
+    this.requiredManagerMajor = requiredMajors.length > 0 ? Math.max(...requiredMajors) : null;
     Object.freeze(this);
   }
 }

package/ts/classes.systemdunit.ts

@@ -539,6 +539,17 @@ export class SystemdUnit {
     return this.inspect();
   }
 
+  /**
+   * Persistently disables the unit: removes the enablement links its `[Install]` section names
+   * (`systemctl disable`, which reloads the manager), then inspects. Never stops, masks, unmasks or
+   * removes the definition; a running unit keeps running. A failed or timed out command can leave
+   * partial enablement: inspect and retry the exact operation.
+   */
+  public async disable(): Promise<ISystemdUnitState> {
+    await this.command(['disable', this.unitName]);
+    return this.inspect();
+  }
+
   /** Loaded manager graph, including reverse edges. Enablement alone does not prove every required link. */
   public async inspectRelationships(): Promise<ISystemdUnitRelationships> {
     const keys = ['Id', 'Before', 'After', 'Requires', 'Wants', 'Conflicts', 'RequiredBy', 'WantedBy'];