Restart systemd services without dropping their clients.
A service that stops hands its state and the connections of its clients over to its next instance, through the file descriptor store that systemd keeps for the service across its restarts. The clients notice nothing but a pause: the next instance serves them on the same connections, from where the previous one stopped, while those that connect meanwhile wait in the socket of socket activation, which systemd keeps open.
zoter does what a service needs for that, except what depends on the service's protocol, such as D-Bus or Varlink:
Passedtakes the file descriptors that systemd passes a service: the sockets of socket activation, and what the previous instance stored.Storehands the service over to its next instance. In the instance that stops,Store::hand_overstores the state of the service and items, such as the connections of its clients, each a record of bytes and file descriptors, however many there are. In the next instance,Store::take_overtakes them over, as aRestored, and tells systemd that the service has started. A hand-over is stored whole and taken over whole, or either fails: nothing of it is left out.
A protocol takes part through two traits, Save and Restore, which the hand-overs of its
connections implement, so that a service hands those over as they are. The testing feature adds
what the tests of the restarts of a service need: testing::Manager, a fake service manager,
and testing::store, the store of a service that a test runs in its own process.
zoter is named after Soter, the Greek daimon of safety, preservation, and deliverance from harm. It builds nothing on platforms other than Linux, where systemd is. Its API is synchronous, and depends on no async runtime.
The life of a service
use OwnedFd;
use ;
The units of a service that restarts so, example, are:
# example.socket
[Socket]
ListenStream=/run/example
[Install]
WantedBy=sockets.target
# example.service
[Unit]
# systemd otherwise starts the service without its socket where the socket unit isn't active.
Requires=example.socket
[Service]
# The service has started once it took over, which zoter tells systemd.
Type=notify
ExecStart=/usr/bin/example
# The memfd of the hand-over, and the sockets that hold its file descriptors, some 70000 in each.
FileDescriptorStoreMax=16
systemctl restart example then restarts the service with its clients, which needs systemd 254 or
later. A stop, or a start after a stop, doesn't keep them: systemd closes the store as the service
stops for good. Without FileDescriptorStoreMax= in the unit, or under an older systemd, there is
no store, and Store::from_env fails with Error::NoStore. Without a socket of socket
activation, which Requires= on the socket unit sees to, there is none either, and it fails with
Error::NoSocket: the service tells systemd that it has started as it takes over, and its
clients wait in the socket meanwhile.
Errors
The fallible functions of zoter return a zoter::Result. The one exception is restoring an item,
which fails with the error that its Restore implementation chooses. An Error says what went
wrong:
Error::NoManagermeans that systemd takes no notifications from the process, as when it doesn't run it at all. A service that also runs without systemd goes on without a store then.Error::NoStore,Error::StoreTooSmallandError::StoreFullname the unit setting to raise,FileDescriptorStoreMax=.Error::NoSocketmeans that systemd passed the service no socket of socket activation, which needs a socket unit, andRequires=on it in the unit of the service.Error::InvalidHandoverandError::UnsupportedHandovermean that the next instance can't take over the hand-over. It then starts afresh without it.Error::Iois the error that the system returned, such asEMFILEwhen the file descriptors of a hand-over don't fit under the limit of open files.
Each variant converts into an std::io::Error of a matching kind. So a service whose functions
return std::io::Result can use ? on these errors too.
Status
In development: the API can change from one minor version to the next.