upstart-socket-bridge

upstart-socket-bridge [OPTIONS] FILE

-b, --backlog
    Sets the maximum number of pending connections that can be queued for the socket. Default is 128.

-k, --keep-fd
    Prevents the closing of inherited file descriptors, useful when running in conjunction with upstart-event-bridge.

-p, --pidfile
    Writes the process ID (PID) of the upstart-socket-bridge process to the specified file.

-s, --socket-perms
    Sets the octal file permissions (e.g., 0666) for the created UNIX domain socket file. Default is 0600.

-S, --socket-owner
    Sets the user and group owner for the created socket file in the format user:group.

-u, --user
    Changes the effective user ID of the process to the specified user. Implies also changing the group to the user's primary group.

-g, --group
    Changes the effective group ID of the process to the specified group.

-v, --version
    Displays version information for the upstart-socket-bridge utility and exits.

upstart-socket-bridge is a specialized utility within the Upstart init system designed to establish and manage communication channels between an Upstart job and an external process using a UNIX domain socket (AF_UNIX). Its primary function is to create a specified socket file on the filesystem and bridge it to its own standard input and output streams. This mechanism enables a daemon or application to communicate over a socket without the need for it to directly handle socket creation, binding, or cleanup. It is particularly valuable for implementing socket activation: Upstart can listen on a socket, and when a connection arrives, it can start the relevant service, passing the pre-opened socket file descriptor. upstart-socket-bridge ensures the socket's correct creation, handles its permissions and ownership, and automatically cleans it up upon termination. It is designed to exit when its standard input stream is closed, indicating the parent process (typically Upstart) has signaled its end.

upstart-socket-bridge is an integral part of the Upstart init system, which has been largely superseded by systemd in most contemporary Linux distributions (e.g., Ubuntu from version 15.04 onwards). Consequently, its primary relevance is for managing services on older or legacy systems that still utilize Upstart.

This command plays a crucial role in Upstart's socket activation capabilities. Instead of a service running continuously and listening on a port, Upstart can manage the socket directly. When an incoming connection is detected on that socket, Upstart can then trigger the start of the associated service, passing the pre-opened socket file descriptor to it. upstart-socket-bridge is specifically used to create and manage this socket file on the filesystem, establishing the necessary communication bridge between the Upstart init system and the actual service application.

The upstart-socket-bridge process is designed to terminate automatically when its standard input (stdin) stream is closed. This behavior implies that it is typically run as a child process of a supervisor, such as Upstart itself, or within a pipeline where a parent process controls its lifecycle by managing the stdin stream. This design ensures proper cleanup and release of the socket file resources when the bridging process is no longer required.

upstart-socket-bridge was developed as part of the Upstart project by Canonical, initially gaining prominence as the default init system in Ubuntu and other distributions. Upstart aimed to provide an event-driven alternative to the traditional sysvinit. However, its development and widespread adoption gradually declined with the rise and eventual dominance of systemd, which became the preferred init system across much of the Linux ecosystem, leading to Upstart's phased retirement in new installations.

upstart(8), upstart-event-bridge(8), socket(7), systemd.socket(5), init(8)