Environmental variables

Below variables are available for programs (most frequently shell scripts) executed from Flatconf:

  • $FC_ROOT - absolute path to directory tree holding configuration values, usually /etc/fc,
  • $FC_PATH - Flatconf path (ie. relative) to the variable or directory that caused the event (e.g. /net/routing/mode),
    • for list elements it contains the translated path (with elid), e.g. /net/routing/table/123,
  • $FC_ROOT_CWD - $FC_ROOT + $FC_PATH,
  • $FC_META - absolute path to directory tree holding configuration metadata, often /usr/share/fc/main,
  • $FC_META_CWD - as $FC_ROOT_CWD, but path to metadata (e.g. /usr/share/fc/main/net/routing),
  • $FC_LANG - user language.

For on*change and onapply events:

  • $FC_OLDVAL - (where applicable) old value,
  • $FC_NEWVAL - (where applicable) new value.

For on*el* events, if applicable and available:

  • $FC_ELID - element's elid,
  • $FC_ELNAME - element's elname.

Output

If not stated otherwise, the general rules are:

  • all data from standard output is passed to the user,
  • all data from standard error output is passed to the user only when user interface is in debugging mode,
  • exit code equal to 0 means success,
  • exit code equal to 2 means warning,
  • other exit codes mean error.

Events

Following properties hold scripts to execute on particular events. Note that these properties can have a single textual value as well as be an array of textual values. In the second case scripts will be executed in the order they appear in the array.

Obviously, it's also possible to execute any programs on below events, not only shell scripts.

Scripts are started in $FC_ROOT_CWD directory.

  • on*change - changes to values of files under fc:tree except list.order files:
    • onbeforechange - executed just before the variable value changes,
      • for all types of directories except lists, it matches when at least one variable in the directory changes,
      • if the script returns an error, the value is not updated,
    • onafterchange - the same as onbeforechange, but run just after the variable value changes
      • scripts should not generate errors; variables will not be reverted to previous values
  • on*el* - changes to list.order files (properties of list definitions):
    • oneladd, onbefeladd - matches adding/copying an element, does not match moving - after and before the actual change, respectively,
    • oneldel, onbefeldel - matches deleting an element, does not match moving,
    • onelup, onbefelup - when element is moved one position up,
    • oneldown, onbefeldown - when element is moved one position down,
    • onelenable, onbefelenable - when element is enabled,
    • oneldisable, onbefeldisable - when element is disabled,
    • onelmove, onbefelmove - matches cross-moves and renames
      • $FC_NEW_ELNAME - new element name,
      • $FC_NEW_LISTPATH - fc:path to new list (in case of cross-moves);
  • special events:
    • onapply - run when user requests to apply the changes; applicable only when version control is present;
      • the list of added, deleted and modified variables along with previous values is taken from the version control system embedded in configuration (see version control),
      • if the script fails, system appends relevant fc:path to fc:/flatconf/vc-apply-failed file,
        • special care should be taken about accepting changes by onbef* scripts so the new values can be applied without errors; particulary, it's hard to revert changes (properly) in list.order files;
      • for lists, initial parsing is done and the script has access to the following environmental variables holding space-separated lists of elids:
        • $FC_ADDED_ELEMENTS,
        • $FC_DELETED_ELEMENTS,
        • $FC_RENAMED_ELEMENTS
          • note that it's hard to trace cross-moves, so such elements will show up either in the list of added or deleted elements,
        • $FC_ENABLED_ELEMENTS,
        • $FC_DISABLED_ELEMENTS
    • onsubmit - for directories of action type only - executed when user submits an action

Apply order

Whenever a variable or a directory needs to be applied after some other entry (say /dir/foobar), add it's path to property applyafter, e.g.

applyafter = { "/dir/foobar" }

This property matches from longest to shortest paths, e.g. if you apply /dir1/dir2/dir3/file4, then following properties will be checked:

  1. fs:/dir1/dir2/dir3/file4/applyafter,
  2. fs:/dir1/dir2/dir3/applyafter,
  3. fs:/dir1/dir2/applyafter,
  4. fs:/dir1/applyafter,
  5. fs:/applyafter, and

...it will stop (ie. use the property value) on first match.

Apply groups

Whenever applying settings requires restarting some services (or sending them some signals), there's a need to prevent restarting the same service twice (or more) in case two different variables (or more) require that.

This may be accomplished by assigning group names to the scripts in the onapply array as in the example below:

onapply = {
  "/etc/rc.d/rc.hostname restart",
  { group: "firewall", cmd: "/etc/rc.d/rc.firewall restart" }
}

Whenever the same group name (firewall) repeats anywhere else in the whole apply process, actions defined in it won't be run (/etc/rc.d/rc.firewall restart won't be run again).