A JSON schema describes these files and you can configure some editors to validate the YAML file based on that. The command
choria machine validate can validate a machine.yaml against this schema.
All watchers share a common set of properties detailed below, watcher specific properties are always in the properties key:
|name||yes||A unique name for the watcher|
|type||yes||A known type of watcher like file or exec|
|state_match||no||A list of state names where this watcher is valid for|
|fail_transition||If set this event fires on failure|
|success_transition||If set this event fires on success|
|interval||Runs the watcher every interval, valid intervals are of the form 1s, 1m, 1h|
|announce_interval||Announce the current state of the watcher regularly, valid intervals are of the form 1s, 1m, 1h|
|properties||yes||Watcher specific settings|
The file watcher observes a specific file for changes and presence. Today only a basic mtime check is done, in time other dimensions like hashes or even inotify based observation will be supported.
|path||yes||The path to the file to watch relative to the watcher manifest directory|
|gather_initial_state||Gathers the initial file mode, stats etc for regular announces but only perform first watch after interval|
A file watcher will at interval times do an mtime check on the file.
If the file is missing a fail_transition event fires and an announcement is made.
If the file has changed since the previous run a success_transition event fires and an announcement is made. This means the first check would set the initial state after which changes are detected. You could by setting gather_initial_state have the system gather initial file state on startup so the first regular watch would detect a change.
If the file has not changed nothing is published on every check, however a regular state announce can be done by setting announce_interval.
The exec watcher supports running shell commands, it has a very basic exit code based interface, output from the commands is not significant.
|command||yes||The command to run relative to the watcher manifest directory|
|timeout||How long the command is allowed to run, 10s default|
|suppress_success_announce||Do not publish a state JSON document after every run, useful for frequently run items. Still publish on error. Still support regular publish via
|environment||A list of custom environment variables to set in the form
An exec watcher will at interval times run the command specified with a few machine specific environment variables set in addition to any set using
environment. Since version 0.11.1 when the interval is not set or set to 0 the the command will run only on transitions.
|MACHINE_WATCHER_NAME||The name of the watcher being run|
|MACHINE_NAME||The name of the machine being run|
|PATH||Includes the machine directory as last entry|
The command is run with current directory set to the directory where the machine.yaml is, when the command exits 0 a success_transition fires, when it exits !0 a fail_transition fires. Both cases publish an event announcing the execution.
The scheduler watcher flips between success and fail states based on a set of schedules specified in a crontab like format. Use it to enter and exit a state on a schedule and combine it with an exec watcher to run commands on a schedule.
This feature is available since Choria Server 0.11.1
|duration||yes||How long the scheduler should be in the
|schedules||yes||A list of crontab like schedules based on which the
The schedules specified is a list of times when the scheduler will be in success transition, at the end of the trigger time + duration it will fire a fail transition. The fields are like crontab(5), supports ranges, special characters and predefined schedules like
@daily, see robfib/cron section CRON Expression Format for what we’d understand. We do not support the seconds field.
- name: scheduler type: schedule fail_transition: stop success_transition: start state_match: [switched_on, switched_off] interval: 1h properties: duration: 1h schedules: - "0 8 * * *" - "0 12 * * *" - "0 17 * * *" - "0 20 * * SAT,SUN"
The scheduler above will switch on daily at 8am, 12pm and 5pm but also at 8pm on Saturdays and Sundays. It will stay on for a hour.
If the machine transitions into an eligible state_match while a schedule is started it will immediately fire the success_transition. If Choria starts up in the middle of a scheduled period it will be ignored and the next schedule will trigger. Overlapping schedules is supported.