Bcfg2 depends heavily on file activity monitoring (FAM) to reload data from disk when it changes. A number of FAM backends are supported (documented thoroughly below), but you may wish to develop additional backends. For instance, the current best FAM backend on Linux is INotify, but if you are running a non-Linux system that lacks INotify support you may wish to write a backend for your OS (e.g., a kqueue backend for BSD-based Bcfg2 servers). This page documents the FAM API and the existing FAM backends.
Five event codes are generally understood:
Event | Description |
---|---|
exists | Produced when a monitor is added to a file or directory that exists, and produced for all files or directories inside a directory that is monitored (non-recursively). |
endExist | Produced immediately after exists. No plugins should process this event meaningfully, so FAM backends do not need to produce it. |
created | Produced when a file is created inside a monitored directory. |
changed | Produced when a monitored file, or a file inside a monitored directory, is changed. |
deleted | Produced when a monitored file, or a file inside a monitored directory, is deleted. |
Bcfg2.Server.FileMonitor provides the support for monitoring files. The FAM acts as a dispatcher for events: An event is detected on a file (e.g., the file content is changed), and then that event is dispatched to the HandleEvent method of an object that knows how to handle the event. Consequently, Bcfg2.Server.FileMonitor.FileMonitor.AddMonitor() takes two arguments: the path to monitor, and the object that handles events detected on that event.
HandleEvent is called with a single argument, the Bcfg2.Server.FileMonitor.Event object to be handled.
The FAM API Bcfg2 uses is based on the API of SGI’s File Alteration Monitor (also called “FAM”). Consequently, a few assumptions apply:
Bases: object
Base class for all FAM events.
Parameters: |
|
---|
The event code produced. I.e., the type of event.
Return the event code for this event. This is just an alias for action.
The file or directory on which the event was detected. An event on a file or directory that is monitored directly yields the full path to the file or directory; an event on a file or directory that is only contained within a monitored directory yields the relative path to the file or directory within the monitored parent.
The handler ID of the monitor that produced this event
Bases: Bcfg2.Server.Plugin.base.Debuggable
The base class that all FAM implementions must inherit.
The simplest instance of a FileMonitor subclass needs only to add monitor objects to handles and received events to events; the basic interface will handle the rest.
Parameters: |
|
---|
The relative priority of this FAM backend. Better backends should have higher priorities.
Monitor the specified path, alerting obj to events. This method must be overridden by a subclass of Bcfg2.Server.FileMonitor.FileMonitor.
Parameters: |
|
---|---|
Returns: | Varies - The handler ID for the newly created monitor |
Queue of events to handle
Get the oldest pending event in events.
Returns: | Bcfg2.Server.FileMonitor.Event |
---|
Handle all pending events.
Parameters: | lock (threading.Lock) – A thread lock to use while handling events. If None, then no thread locking will be performed. This can possibly lead to race conditions in event handling, although it’s unlikely to cause any real problems. |
---|---|
Returns: | None |
Handle events for the specified period of time (in seconds). This call will block for interval seconds and handle all events received during that period by calling handle_event_set().
Parameters: | interval (int) – The interval, in seconds, during which events should be handled. Any events that are already pending when handle_events_in_interval() is called will also be handled. |
---|---|
Returns: | None |
Handle the given event by dispatching it to the object that handles it. This is only called by handle_event_set(), so if a backend overrides that method it does not necessarily need to implement this function.
Parameters: | event (Bcfg2.Server.FileMonitor.Event) – The event to handle. |
---|---|
Returns: | None |
A dict that records which objects handle which events. Keys are monitor handle IDs and values are objects whose HandleEvent method will be called to handle an event
List of filename globs to ignore events for. For events that include the full path, both the full path and the bare filename will be checked against ignore.
Returns True if there are pending events (i.e., events in events that have not been processed), False otherwise.
Returns True if an event should be ignored, False otherwise. For events that include the full path, both the full path and the bare filename will be checked against ignore. If the event is ignored, a debug message will be logged with debug_log().
Parameters: | event (Bcfg2.Server.FileMonitor.Event) – Check if this event matches ignore |
---|---|
Returns: | bool - Whether not to ignore the event |
Start threads or anything else that needs to be done after the server forks and daemonizes. Note that monitors may (and almost certainly will) be added before start() is called, so if a backend depends on being started to add monitors, those requests will need to be enqueued and added after start(). See Bcfg2.Server.FileMonitor.Inotify.Inotify for an example of this.
A dict of all available FAM backends. Keys are the human-readable names of the backends, which are used in bcfg2.conf to select a backend; values are the backend classes. In addition, the default key will be set to the best FAM backend as determined by Bcfg2.Server.FileMonitor.FileMonitor.__priority__
Pseudo provides static monitor support for file alteration events. That is, it only produces “exists” and “endExist” events and does not monitor for ongoing changes.
Bases: Bcfg2.Server.FileMonitor.FileMonitor
File monitor that only produces events on server startup and doesn’t actually monitor for ongoing changes at all.
Parameters: |
|
---|
The Pseudo monitor should only be used if no other FAM backends are available.