systemd-socket-activate

Activate a service when a specific socket is connected

$ systemd-socket-activate [path/to/socket.service]

$ systemd-socket-activate [path/to/socket1.service] [path/to/socket2.service]

$ [SYSTEMD_SOCKET_ACTIVATION=1] systemd-socket-activate [path/to/socket.service]

$ systemd-socket-activate [path/to/socket.socket] [path/to/service.service]

$ systemd-socket-activate [path/to/socket.service] [[-l|--listen]] [8080]

systemd-socket-activate [OPTIONS...] [COMMAND] [ARGUMENTS...]
systemd-socket-activate --service=UNIT

--help, -h
    Displays a short help text and exits.

--version
    Prints a short version string and exits.

--quiet
    Suppresses informative messages.

--listen=ADDR
    Specifies a socket address to listen on. This option can be used multiple times to listen on several addresses. Addresses can be IP addresses, port numbers, or Unix domain socket paths.

--fdname=NAME
    Assigns a name to the file descriptor(s) passed to the invoked command. This name can be used by the invoked program (e.g., via SD_LISTEN_FDS_NAMES environment variable).

--inetd
    Enables inetd-style operation. For each incoming connection, systemd-socket-activate forks, sets up standard I/O (stdin/stdout) to the new connection, and executes the specified command.

--accept
    Similar to --inetd but does not fork. Instead, the main process accepts connections, and the invoked command inherits the socket and is expected to accept connections itself. Useful for single-threaded servers.

--pid-file=PATH
    Writes the PID of systemd-socket-activate to the specified file.

--make-setsid
    Places the invoked command into a new session before execution.

--watch-pid=PID
    If specified, systemd-socket-activate will monitor the specified PID and terminate itself when that PID exits.

--keep-ready
    Keeps systemd-socket-activate running and listening for new connections even after the command exits. It will restart the command on the next connection.

--exec-fd=FD
    Uses an already existing file descriptor (specified by number) as the listening socket, instead of creating a new one.

--service=UNIT
    Activates a specified systemd service unit (.service) upon an incoming connection. Instead of executing a command directly, this triggers systemd to start the service.

systemd-socket-activate is a utility program that facilitates socket activation for systemd services. It listens on specified network or Unix domain sockets and, upon an incoming connection or datagram, launches a specified command or activates a systemd service unit. The core idea behind socket activation, which systemd-socket-activate embodies, is to decouple the listening socket from the service that processes connections. This allows services to be started only when they are actually needed, leading to faster boot times, reduced resource consumption (as services don't run perpetually if idle), and improved robustness (services can be restarted independently of their listening sockets).

When systemd-socket-activate starts a command, it passes the pre-opened file descriptors (representing the listening sockets) to the newly launched process, typically starting from file descriptor 3. The invoked program can then use these inherited file descriptors to accept connections or receive datagrams directly, without needing to bind to ports itself. This utility can emulate traditional inetd-style behavior using the --inetd or --accept options, where it forks a new process for each incoming connection. Alternatively, it can activate a systemd service unit via the --service option, leveraging systemd's full activation capabilities. It's an essential component for designing efficient, on-demand, and resilient system services under systemd.

systemd-socket-activate is primarily designed for use within the systemd ecosystem. While it can be used standalone, its full power and integration are realized when combined with systemd.socket units. It relies on the kernel's socket functionality and the ability to pass file descriptors, which might have implications for certain security contexts or containerization environments. It's not a direct, drop-in replacement for all inetd functionalities, as it adheres to systemd's more structured activation model. Complex service logic, like protocols that require initial data before a connection is fully established, might need careful handling by the activated application.

Socket activation is a core systemd concept where a service's listening sockets are created and managed by systemd itself, rather than by the service application. When a connection arrives on such a socket, systemd (or utilities like systemd-socket-activate) starts the corresponding service, passing the pre-opened socket file descriptors to it. This design allows for:
1. Parallel Startup: Services don't need to wait for others to bind ports.
2. Resource Efficiency: Services only run when active, saving memory and CPU.
3. Robustness: Services can crash and restart without dropping existing connections, as the socket remains open.
4. Dependency Management: Sockets can be activated before the services themselves are fully up.

A crucial aspect of systemd-socket-activate (and socket activation in general) is the passing of file descriptors. When a service is activated, the listening socket(s) are handed over to the new process. These file descriptors are typically made available to the child process starting from file descriptor 3. The child process then uses standard library functions (like accept() or recvmsg()) on these inherited FDs. This method eliminates the need for services to handle bind() and listen() calls themselves, simplifying service design and enhancing security by allowing systemd to manage privileged port bindings.

systemd-socket-activate was introduced early in the development of systemd as a fundamental component to implement its socket activation feature. This mechanism was a key innovation aimed at improving system boot times, resource management, and service robustness compared to traditional init systems. It effectively superseded the role of classic inetd and xinetd daemons within the systemd framework, providing a more integrated and flexible way to activate services on demand, particularly for network-bound applications. Its development paralleled systemd's growth as a modern init system, solidifying its position as a core utility for building resilient and efficient Linux services.

systemd(1), systemd.socket(5), systemd.service(5), sd_listen_fds(3), sd_is_socket(3), inetd(8)