upstart-file-bridge

upstart-file-bridge [OPTIONS] FILE...
upstart-file-bridge [OPTIONS] --dir DIRECTORY...

FILE...
    One or more files to monitor for changes. If a directory is specified here, upstart-file-bridge will only monitor events directly on the directory itself (e.g., its deletion or attributes change), not its contents.

--dir DIRECTORY...
    One or more directories to monitor. When a directory is monitored using this option, upstart-file-bridge will watch for events happening within that directory, such as the creation, modification, or deletion of files and subdirectories inside it. This also includes events for the directory itself.

--event NAME
    Specifies the base name for the Upstart events emitted. For example, if NAME is 'config-change', events like 'config-change-created', 'config-change-modified', 'config-change-deleted' might be emitted, depending on the file event type. If not specified, a default event name related to the file path is typically used.

--system
    Connects to the system-wide Upstart instance. This is the default behavior when running as root.

--user
    Connects to the user-specific Upstart instance. This is the default behavior when running as a non-root user.

--no-daemon
    Prevents upstart-file-bridge from forking into the background. Useful for debugging or running within a supervised process.

--all-events
    Emit Upstart events for all supported inotify event types, providing more granular notifications of file system changes (e.g., attribute changes, moves from/to, unmounts).

--help
    Displays a help message and exits.

--version
    Displays version information and exits.

The upstart-file-bridge command is a utility designed to integrate file system activity with the Upstart init system. It leverages the Linux inotify mechanism to monitor specified files or directories for changes such as creation, modification, deletion, or moves. When an event is detected, upstart-file-bridge emits a corresponding Upstart event, allowing Upstart jobs to react dynamically to file system changes. This is particularly useful for scenarios where services or scripts need to be triggered automatically based on the presence or alteration of specific configuration files, log files, or data directories. For instance, an Upstart job could be configured to restart a service whenever its configuration file is modified, or to process new data when a file appears in an input directory. It acts as a crucial link between the dynamic file system and the event-driven nature of Upstart.

The upstart-file-bridge command is part of the Upstart init system, which has largely been superseded by systemd in most modern Linux distributions (e.g., Ubuntu from 15.04 onwards, Debian, Fedora, CentOS, RHEL). Consequently, this command is primarily relevant and functional only on systems still utilizing Upstart as their primary init system. On systemd-based systems, file event monitoring and service activation are typically handled by systemd path units (.path files) and inotify-based tools like inotifywait or custom scripts integrated with systemd. Attempting to use upstart-file-bridge on a non-Upstart system will likely result in errors or no functionality.

upstart-file-bridge relies on the Linux kernel's inotify mechanism for efficient file system event monitoring and requires a running Upstart daemon to emit and process events. It also requires appropriate permissions to monitor the specified files/directories and to communicate with the Upstart session (either system or user).

By default, the emitted Upstart event names are constructed from the monitored file or directory path, often with a prefix indicating the event type (e.g., file-created, file-modified). When the --event option is used, it provides a custom base name for these events, making them easier to manage and match in Upstart job configurations.

The upstart-file-bridge utility was developed as part of the Upstart init system, which was created by Canonical Ltd. (the developers of Ubuntu) and first introduced in Ubuntu 6.10 (Edgy Eft) in 2006. Upstart aimed to be an event-driven replacement for the traditional SysVinit init system, allowing services to start and stop asynchronously based on events rather than fixed runlevels. upstart-file-bridge provided a crucial mechanism to bridge low-level file system events into Upstart's event model, enabling more dynamic service management. Its usage peaked during Upstart's widespread adoption, particularly in Ubuntu distributions up to version 14.10. However, with the rise of systemd, which offered a more comprehensive and robust init system solution, most major Linux distributions, including Ubuntu (starting from 15.04), transitioned away from Upstart. As a result, the active development and general usage of upstart-file-bridge have significantly declined, becoming a legacy tool primarily found on older or specialized Upstart-based systems.

upstart(8), init(8), inotifywait(1), systemd.path(5), systemd(1)