xenial (8) upstart-file-bridge.8.gz

Provided by: upstart_1.13.2-0ubuntu21.1_amd64 bug

NAME
       upstart-file-bridge - Bridge between Upstart and inotify


SYNOPSIS
       upstart-file-bridge [OPTIONS]...


DESCRIPTION
       upstart-file-bridge  receives  information  about  kernel  file  events  that inotify(7) has received and
       creates init(8) events for them.

       Supported events exposed to Upstart allow  jobs  to  detect  creation,  modification  and  deletion.  See
       file-event(7) for further details.

       The  bridge  works  by querying the init(8) daemon at bridge startup time to determine a list of all jobs
       whose start on or stop on conditions reference the  file  event.  Further,  the  bridge  arranges  to  be
       notified  automatically  when new jobs are created such that any subsequent jobs which reference the file
       event are also handled (as are job deletions).

       See inotify(7) and for further details.


OPTIONS
       --daemon
              Detach and run in the background.

       --debug
              Enable debugging output.

       --help Show brief usage summary.

       --user User-session mode: connect to Upstart via the user session rather than over the D-Bus system bus.

       --verbose
              Enable verbose output.


JOB ENVIRONMENT VARIABLES
       FILE   Path to file to watch. When run without --user, this must  be  an  absolute  path.  If  --user  is
              specified, certain relative path types are supported:

              • If  the  path  begins with '~/', the value will be expanded as would be performed by a shell for
                matching purposes (although when the event is emitted, the original value will be used).

              • If the path begins with './', '.' will be assumed to be the users home directory.

              • In all other scenarios, if the path does not begin with '/', it will be assumed to  represent  a
                file below the users home directory.

              If  the  path  ends  with  a  slash,  it  is  considered to be a directory which changes the match
              behaviour (see below).

              If the path is not a directory, the file (but not the directory) portion of the path  may  contain
              wildcard matches. See fnmatch(3) and glob(7) for further details.

       EVENT  Event  relating to FILE that job is interested in. If this variable is specified the value must be
              set to create, modify or delete depending on what type of file event the job is interested in.  If
              FILE  is  not  specified,  the  bridge  will  watch  for  all  types  and set this variable to the
              appropriate value when emitting the event.


WATCH TYPE BEHAVIOUR
       The bridge emits events depending not only on the value of EVENT, but also on  the  entity  specified  by
       FILE:

   File
       An  event  will  be emitted when the named file is created, modified or deleted depending on the value of
       EVENT. If EVENT is not specified, react to creation, modification and deletion.

       If the file already exists when the job is registered, and EVENT either specifies create or the  variable
       is not specified, the event will be emitted.

   Directory
       An  event  will  be  emitted  when the named directory is created, modified (files within it are created,
       modified or deleted) or deleted depending on the value of EVENT. If EVENT  is  not  specified,  react  to
       creation, modification and deletion.

       If  the  directory  already  exists  when the job is registered, and EVENT either specifies create or the
       variable is not specified, the event will be emitted.

   Glob
       One event will be emitted per match when the glob wildcard matches any files in  the  directory  part  is
       created,  modified  or  deleted,  depending  on  the  value of EVENT. If EVENT is not specified, react to
       creation, modification and deletion.

       If any matches already exist when the job is  registered,  and  EVENT  either  specifies  create  or  the
       variable is not specified, events will be emitted.


NOTES
       •   A single instance of the bridge may be run at the system level, but multiple further instances may be
           run per user session instance by using the --user.

       •   All job conditions specifying the file event are multi-shot: if the same file event  occurs  multiple
           times, the bridge will emit an Upstart event each time.


LIMITATIONS
       •   Since  the  bridge  currently  uses  inotify(7),  it  is subject to the same limitations; namely that
           recursive watches cannot be created reliably in all circumstances. As  such,  pathological  scenarios
           such  as  deep directory trees being created and then quickly removed cannot be handled reliably. The
           following provides advice to minimise unexpected behaviour:

           •   Attempt to only watch for files to be created,  modified  or  deleted  in  directories  that  are
               guaranteed to already exist at the time the job is registered by the bridge.

           •   If  the  system  cannot guarantee that the directory will exist at job registration time, arrange
               for the directory to be created by an Upstart job before the bridge itself starts.

           •   In user session mode, if a job specifies a file to  watch  for  and  that  file  is  created  but
               inaccessible to the user running the bridge, no event will be emitted.

       •   Tilde expansion is only supported for the current user; that is '~otheruser' will not work.


AUTHOR
       Written by James Hunt <james.hunt@canonical.com>


BUGS
       Report bugs at <https://launchpad.net/ubuntu/+source/upstart/+bugs>


       Copyright © 2013 Canonical Ltd.

       This  is  free  software;  see  the  source  for  copying conditions.  There is NO warranty; not even for
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


SEE ALSO
       init(5) init(8) inotify(7) file-event(7)