Markdown Cheatsheet
Markdown formatting is simple, and the CFEngine generator adds a few things to make it even simpler. Here's a list of the most commonly used formats.
Remember
- "Always pull never push"
Basic Formatting
One
Paragraph
Two
Paragraphs
One Paragraph
Two Paragraphs
**Bold**
Bold
*Italic*
Italic
Links
Link within documentation and to known pages
You can link to any documentation page section using [linktext][PageTitle#optional section]
.
For example I can link to collecting functions using [collecting functions][Functions#collecting functions]
.
[top of the page][Markdown Cheatsheet], to the [Markdown Cheatsheet][], [inside page][Markdown Cheatsheet#Links] and [inside current page][Markdown Cheatsheet#Links]
top of the page, to the Markdown Cheatsheet, inside page and inside current page
Note: For known pages, see the _references.md file.
Link to CFEngine keyword
The documentation pre-processor will create those automatically.
`classes` and `readfile()`
classes
and readfile()
However, the preprocess will not create links if the code word is in triple backticks:
```classes``` and ```readfile()```
classes
and readfile()
Link to External URL
[Markdown Documentation](http://daringfireball.net/projects/markdown/)
Lists
Unordered lists - Markdown supports other markers than the asterisk, but in
CFEngine we use only *
.
* Item 1
* Item 2
* Item 2a
* Multi paragraph item
Four spaces indented
- Item 1
- Item 2
- Item 2a
Multi paragraph item
Four spaces indented
Ordered lists - the numbers you use don't matter.
1. first
1. second
9. Third
- first
- second
- Third
Tables
Wiki-syntax for tables is supported, and you can be a bit sloppy
about it, although it's better to align the |
properly.
| Header | Left aligned | Centered | Right aligned |
|--------|:-------------|:--------:|--------------:|
|text | text | X | 234 |
Header | Left aligned | Centered | Right aligned |
---|---|---|---|
text | text | X | 234 |
Code
Inline code
This renders as `inline code`.
This renders as inline code
.
This also renders as ```inline code```.
This also renders as inline code
.
See the note above on implicit linking - single backticks will link, triple backticks won't.
Code Blocks
Code blocks are either indendented by four spaces:
Just indent by four spaces:
$ code block
$ without syntax highlighting
$ code block
$ without syntax highlighting
or use three backticks:
```
some more code
in a block
```
some more code
in a block
To turn on syntax highlighting, specify the brush directly after the opening three backticks. Syntax highlighting is provided by pygments. Find all available lexers here.
CFEngine Code Blocks
If you want CFEngine syntax highlighting, use
```cf3
# CFEngine block
bundle agent example()
{
}
```
# CFEngine code block
bundle agent example()
{
}
Other frequently used syntax highlighers shown below.
Bash Script Code Blocks
```bash
#!/bin/bash
echo hi
for i in `seq 1 10`;
do
echo $i
done
```
#!/bin/bash
echo hi
for i in `seq 1 10`;
do
echo $i
done
Console Blocks
```console
root@policy_server # /etc/init.d/cfengine3 stop
```
root@policy_server # /etc/init.d/cfengine3 stop
SQL Code Blocks
```sql
SELECT
FileChanges.FileName,
Count(Distinct(FileChanges.HostKey)) AS DistinctHostCount,
COUNT(1) AS ChangeCount
FROM
FileChanges JOIN Contexts
WHERE
Contexts.ContextName='ubuntu'
GROUP BY
FileChanges.FileName
ORDER BY
ChangeCount DESC
```
SELECT
FileChanges.FileName,
Count(Distinct(FileChanges.HostKey)) AS DistinctHostCount,
COUNT(1) AS ChangeCount
FROM
FileChanges JOIN Contexts
WHERE
Contexts.ContextName='ubuntu'
GROUP BY
FileChanges.FileName
ORDER BY
ChangeCount DESC
Diff Code Blocks
```diff
diff --git a/README.md b/README.md
index 92555a2..b49c0bb 100644
--- a/README.md
+++ b/README.md
@@ -377,8 +377,12 @@ As a general note, avoiding abbreviations provides better readability.
* follow the [Policy Style Guide](manuals/policy-style.markdown)
in examples and code snippets
-* always run it through Pygments plus the appropriate lexer (only cf3
- supported for now)
+* always run it through Pygments plus the appropriate lexer
+
+Most important are the `cf3` lexer, as well as `bash`, `console`,
+`diff`, `shell-session` and `postgresql`. But Jekyll supports
+[many more lexers](http://pygments.org/docs/lexers/)
+
* avoid custom color schemes and hand-coded HTML
* document the example after the example code
```
diff --git a/README.md b/README.md
index 92555a2..b49c0bb 100644
--- a/README.md
+++ b/README.md
@@ -377,8 +377,12 @@ As a general note, avoiding abbreviations provides better readability.
* follow the [Policy Style Guide](manuals/policy-style.markdown)
in examples and code snippets
-* always run it through Pygments plus the appropriate lexer (only cf3
- supported for now)
+* always run it through Pygments plus the appropriate lexer
+
+Most important are the `cf3` lexer, as well as `bash`, `console`,
+`diff`, `shell-session` and `postgresql`. But Jekyll supports
+[many more lexers](http://pygments.org/docs/lexers/)
+
* avoid custom color schemes and hand-coded HTML
* document the example after the example code
JSON Code Blocks
{
"classes":{
"services_autorun": [ "any" ]
}
}
{
"classes":{
"services_autorun": [ "any" ]
}
}
YAML Code Blocks
---
classes:
services_autorun:
- "any"
---
classes:
services_autorun:
- "any"
Code Blocks and Lists
If you want to include a code block within a list, put two tabs (8 spaces) in front of the entire block (4 to make the paragraph part of the list item, and 4 for it a code block):
* List item with code
<code goes here>
List item with code
<code goes here>
You can also use backticks (and get syntax highlighting) - just make sure the backticks are indented once:
1. First
```cf3
# CFEngine block
bundle agent example()
{
}
```
2. Second
3. Third
First
# CFEngine block bundle agent example() { }
Second
Third
Headers
Horizontal bar
***
# Level 1
Level 1
## Level 2
Level 2
### Level 3
Level 3
#### Level 4
Level 4
##### Level 5
Level 5
###### Level 6
Level 6
Including External Files
Sometimes it's nice to include an external file
# Changelog Notable changes to the framework should be documented here 3.10.7: - Added ability to avoid limiting robot agents (CFE-3161) - Added and transitioned to using master_software_updates shortcut (ENT-4953) - Added continual checking for policy_server state (CFE-3073) - Added documentation how to enable systemd unit management and disable agents on all hosts (CFE-3416) - Added package_module for snap (CFE-2811) - Always set files_single_copy from augments if available (CFE-3064) - Fixed cleanup of future timestamps from status table (ENT-4331, ENT-4992) - Fixed maintenance policy for promise log cleanup to respect history_length_days (ENT-4588) - Fixed pkgsrc in case where multiple Prefix paths are returned for pkg_install (CFE-3152) - Fixed pkgsrc module on Solaris/NetBSD (CFE-3151) - Set default access promises for directories to only share if directory exists (CFE-3060) - Suppressed stderr output from lldpctl when using path defined by def.lldpctl_json (CFE-3109) - lib/paths.cf: Add usermod path for redhat systems - yum package_module gets updates available from online repos if local cache fails (CFE-3094) 3.10.6: - Add path support for setfacl - Add path support for timedatectl and journalctl (CFE-3013) - Add trailing slash to access promises expecting directories (CFE-3024) - Do not suppress repair outcome for starting cf-monitord or cf-execd (CFE-2964) - Enforce restrictive permissions on hub install log (ENT-4506) - Ensure that asynchronous query API semaphores are writable (ENT-4551) - Fix standalone_self_upgrade not triggering because of stale data (ENT-4317) - Improve performance of enterprise license utilization logging - Log version of Enterprise agent outside of state (ENT-4352) - Prevent performance overhead on hubs that don't enable license utilization logging (ENT-4333) - Purge collection status records from the future (ENT-4362) - Reduce cost of knowing when setopt is available in yum (CFE-2993) - Separate termination and observation promises for cf-monitord (CFE-2963) - Set default value for purge_scheduled_reports_older_than_days (ENT-4404) - Constrain variables in cfe_internal_enterprise_mission_portal_apache policy_server.enterprise_edition to reduce unnecessary resource utilization (CFE-3011) - redhat_pure is no longer defined on Fedora hosts (CFE-3022) 3.10.5: - Add 'system-uuid' to default dmidecode inventory (CFE-2925) - Add inventory of AWS EC2 linux instances (CFE-2924) - Add ubuntu 18 to package map for self upgrade (ENT-4118) - Allow dmidefs inventory to be overridden via augments (CFE-2927) - apt_get module now includes held packages when listing updates (CFE-2855) - Analyze yum return code before parsing its output (CFE-2868) - Cleanup old report data relative to the most recent changetimestamp (ENT-4807) - Create desired version tracking data when necessary (ENT-3937) - Detect systemd service enablement for non-native services (CFE-2932) - Fix name of tunable to control max client-side report history (CFE-2926) - Fix package_latest detecting larger version in some cases (CFE-1743) - Fix standalone self-upgrade when path contains spaces (ENT-4117) - Fix unattended self-upgrade on AIX (ENT-3972) - Inventory Physical Memory MB when dmidecode is found (CFE-2896) - Only consider files that exist for rotation (ENT-3946) - Prevent noise when a service that should be disabled is missing. (CFE-2690) - Prevent standalone self-upgrade from triggering un-necessarily (ENT-4092) - Remove more smartquotes (ENT-3823) - Remove un-necessary agent run during self upgrade (ENT-4116) - Replace unicode smartquotes with apostrophe (ENT-3823) - Specify scope => "namespace" when using persistent classes (CFE-2860) - Store epoch for packages managed by zypper module (CFE-2875) - Store the epoch of packages in cache db with zypper - Updated yum package module to take arbitrary options (ENT-4177) - apt_get package module includes held packages when listing updates (CFE-2855) 3.10.4: - Avoid executing self upgrade policy unnecessarily (ENT-3592) - Change class identifying runagent initiated executions from cfruncommand to cf_runagent_initated - Fix cf-runagent during 3.7.x -> 3.10.x migration (CFE-2776, CFE-2781, CFE-2782) - Improve MPF agent self upgrade docs (ENT-3592) - Localize delete tidy in ha update policy (ENT-3659) 3.10.3: - Add oracle linux support to standalone self upgrade - Fix systemctl path detection - Add support for 32bit rpms in standalone self upgrade (ENT-3377) - make apt_get package module work with repositories containing spaces in the label (ENT-3438) - Be less noisy when a promised service is not found (CFE-2690) - Fix to frequent logging of enterprise license utilization (ENT-3390) - Include scheduled report assets in self maintenance (ENT-3558) - Allow hubs to collect from themselves over loopback (ENT-3329) - Allow multiple sections in insert_ini_section (CFE-2721) - Ensure HA standby hubs have am_policy_hub state marker (ENT-3328) - fixed an error in the file_make_mustache_*, incorrect variable name used (CFE-2714) - Add json templates for rendering serial and multiline data (CFE-2713) - Allow configuration of allowlegacyconnects from augments (ENT-3375) - Fix self upgrade for hosts older than 3.7.4 (ENT-3368) - Ignore empty options in apt_get module (CFE-2685) - cf-execd service override template now only kills cf-execd on stop (ENT-3395) - Policy Release Id is now inventoried by default (CFE-2097) - Avoid triggering self upgrade during bootstrap (ENT-3394) - Maintain access to exported CSV reports in older versions (ENT-3572) - prevent yum from locking in package_methods when possible (CFE-2759) 3.10.2: - Disable package inventory via modules on redhat like systems with unsupported python versions (CFE-2602) - Pass --oldpackage to zypper to allow downgrading packages, but check first if the zypper version supports it. (CFE-2643) - Rename enable_client_initiated_reporting to client_initiated_reporting_enabled - Add postgres.log to enterprise log file rotation (ENT-3191) - Add: prunetree bundle to stdlib The prunetree bundle allws you to delete files and directories up to a sepcified depth older than a specified number of days. - Add the path to mailx on Linux, Darwin, OpenBSD, NetBSD and FreeBSD - Add aix OOTB oslevel inventory (ENT-3117) - Configure networks allowed to initiate report collection (client initiated reporting) via augments (#910) (CFE-2624) - Add templates shortcut (CFE-2582) - Fix: suppress error about unknown lvalue - Configure call_collect_interval from augments (enable_client_initiated_reporting) (#905) (CFE-2623) - Allow specification of files_single_copy via augments (CFE-2458) - Add zypper package module (CFE-2533) - zendesk#3432: fix zypper package downgrade - Enable settig def.max_client_history_size via augments (CFE-2560) - Enable specification of monitoring_include via augments (CFE-2505) - Include previous_state and untracked reports when client clear a buildup of unreported data (ENT-3161) - Configure exclude_hosts in body hub control via augments (CFE-2622) - Change self upgrade now uses standalone policy (ENT-3155) - Directories for ubuntu 16 and centos 7 should exist in master_software_updates (ENT-3136) - Add oslevel to well known paths. (ENT-3121) - server control maxconnections can be configured via augments (CFE-2660) - Fix command to restart apache on config change (ENT-3134) - Add policy to track CFEngine Enterprise license utilization (ENT-3186) - apt_get package module: Fix bug which prevented updates from being picked up if there was more than one source listed in the 'apt upgrade' output, without a comma in between. (CFE-2605) - Change: Do not silence Enterprise hub maintenance - Remove bundle agent cfe_internal_bins (CFE-2636) 3.10.1: - Ensure MP SSL Cert is readable (ENT-3050) - Change Opportunisticaly monitor file integrity (ENT-3040) - Fix systemd unit restart when not running (CFE-2541) - Make stock policy update more resiliant (CFE-2587) - FixesMake apt_get module compatible with Ubuntu 16.04 (CFE-2445) - Add default report collection exclusion based on promise handle (ENT-3061) - Fix: Automatic client upgrades for deb hosts - Do not symlink agents to /usr/local/bin on coreos (ENT-3047) - Add: Ability to set default_repository via augments 3.10.0: - Add: Classes body tailored for use with diff - Change: Session Cookies use HTTPOnly and secure attribtues (ENT-2781) - Change: Verify transfered files during policy update - Add: Inventory for system product name (model) (ENT-2780) - Add: Ensure appropriate permissions for SSL files (ENT-760) - Fix rare bug that would sometimes prevent redis-server from launching. - Change: Enable strict transport security - Add: Definition of from_cfexecd for cf-execd initiated runs (CFE-2386) - Add testing jUnit and TAP bundles and include them in stdlib.cf - Change: Rename duplicate bodies in ha_update.cf (ENT-2753) - Change: Disable RC4 Cipher for ssl in Mission Portal - Pass package promise options to underlying apt-get call (#802) (CFE-2468) - Change: Enable agent component management policy on systemd hosts (CFE-2429) - Add: Enterprise appliaction log dir to rotation - Change: re-enable hub process maintainance - Add: edit_line contains_literal_string to stdlib - Fix: Services starting or stopping unnecessarily (CFE-2421) - Allow specifying agent maxconnections via def.json (CFE-2461) - Change: Disable http TRACE method - Change: Reduce Enteprise webserver info - Change: cronjob bundle tolerates different spacing - Fix: CFEngine choking on standard services (CFE-2806) - Change select_region INI_section to match end of section or end of file (CFE-2519) - Fix ability to manage INI sections with metachars for manage_variable_values_ini and set_variable_values_ini (CFE-2519) - Fix apt_get package module incorrectly using interactive mode. - Add ability to append to bundlesequnece with def.json (CFE-2460) - Behaviour change: when used with CFEngine 3.10.0 or greater, bundles set_config_values() and set_line_based() are appending a trailing space when inserting a configuration option with empty value. (CFE-2466) 3.7.0: - Support for user specified overring of framework defaults without modifying policy supplied by the framework itself (see example_def.json) - Support for def.json class augmentation in update policy - Run vacuum operation on postgresql every night as a part of maintenance. - Add measure_promise_time action body to lib (3.5, 3.6, 3.7, 3.8) - New negative class guard `cfengine_internal_disable_agent_email` so that agent email can be easily disabled by augmenting def.json - Relocate def.cf to controls/VER/ - Relocate update_def to controls/VER - Relocate all controls to controls/VER - Only load cf_hub and reports.cf on CFEngine Enterprise installs - Relocate acls related to report collection from bundle server access_rules to controls/VER/reports.cf into bundle server report_access_rules - Re-organize cfe_internal splitting core from enterprise specific policies and loading the appropriate inputs only when necessary - Moved update directory into cfe_internal as it is not generally intended to be modified - services/autorun.cf moved to lib/VER/ as it is not generally intended to be modified - To improve predictibility autorun bundles are activated in lexicographical order - Relocate services/file_change.cf to cfe_internal/enterprise. This policy is most useful for a good OOTB experience with CFEngine Enterprise Mission Portal. - Relocate service_catalogue from promsies.cf to services/main.cf. It is intended to be a user entry. This name change correlates with the main bundle being activated by default if there is no bundlesequence specified. - Reduce benchmarks sample history to 1 day. - Update policy no longer generates a keypair if one is not found. (Redmine: #7167) - Relocate cfe_internal_postgresql_maintenance bundle to lib/VER/ - Set postgresql_monitoring_maintenance only for versions 3.6.0 and 3.6.1 - Move hub specific bundles from lib/VER/cfe_internal.cf into lib/VER/cfe_internal_hub.cf and load them only if policy_server policy if set. - Re-organize lib/VER/stdlib.cf from lists into classic array for use with getvalues - inform_mode classes changed to DEBUG|DEBUG_$(this.bundle):: (Redmine: #7191) - Enabled limit_robot_agents in order to work around multiple cf-execd processes after upgrade. (Redmine #7185) - Remove Diff reporting on /etc/shadow (Enterprise) - Update policy from promise.cf inputs. There is no reason to include the update policy into promsies.cf, update.cf is the entry for the update policy - _not_repaired outcome from classes_generic and scoped_classes generic (Redmine: # 7022) - standard_services now restarts the service if it was not already running when using service_policy => restart with chkconfig (Redmine #7258) - Fix process_result logic to match the purpose of body process_select days_older_than (Redmine #3009)
Including chunks of policy from the MPF
Here I am including a bundle named cfe_autorun_inventory_listening_ports
. It may be a common or an agent bundle (in case the bundle ever changes types).
```cf3 bundle agent cfe_autorun_inventory_listening_ports { vars: "ports" -> { "ENT-150" } slist => sort( "mon.listening_ports", "int"), meta => { "inventory", "attribute_name=Ports listening" }, ifvarclass => some("[0-9]+", "mon.listening_ports"), comment => "We only want to inventory the listening ports if we have values that make sense."; } ```
bundle agent cfe_autorun_inventory_listening_ports
{
vars:
"ports" -> { "ENT-150" }
slist => sort( "mon.listening_ports", "int"),
meta => { "inventory", "attribute_name=Ports listening" },
ifvarclass => some("[0-9]+", "mon.listening_ports"),
comment => "We only want to inventory the listening ports if we have
values that make sense.";
}
Comments inside documentation
Sometimes it's nice to be able to put an internal comment into the documentation that will not be rendered.
You can use the comment and endcomment tags in markdown files.
For example:
{% comment %} TODO: We should try to improve this at some point.{% endcomment %}
Would render like this:
Sandbox
symlink example
body link_from ln_s(x)
{
link_type => "symlink";
source => "$(x)";
when_no_source => "force";
}
Self Documenting Policy
For the stdlib:
agent bundles
daemonize
Prototype: daemonize(command)
Description: Run a command as a daemon. I.e., fully detaches from Cfengine.
Arguments:
command
: The command to run detached Note: There will be no output from the command reported by cf-agent. This bundle has no effect on windows
Example:
cf3
methods:
"Launch Daemon"
usebundle => daemonize("/bin/sleep 30");
Implementation:
bundle agent daemonize(command)
{
commands:
!windows::
"exec 1>&-; exec 2>&-; $(command) &"
contain => in_shell;
reports:
"windows.(DEBUG|DEBUG_$(this.bundle))"::
"DEBUG $(this.bundle): This bundle does not support Windows";
}
contain bodies
silent
Prototype: silent
Description: suppress command output
Implementation:
body contain silent
{
no_output => "true";
}
in_dir
Prototype: in_dir(dir)
Description: run command after switching to directory "dir"
Arguments:
dir
: directory to change into
Example:
commands:
"/bin/pwd"
contain => in_dir("/tmp");
Implementation:
body contain in_dir(dir)
{
chdir => "$(dir)";
}
in_dir_shell
Prototype: in_dir_shell(dir)
Description: run command after switching to directory "dir" with full shell
Arguments:
dir
: directory to change into
Example:
commands:
"/bin/pwd | /bin/cat"
contain => in_dir_shell("/tmp");
Implementation:
body contain in_dir_shell(dir)
{
chdir => "$(dir)";
useshell => "true"; # canonical "useshell" but this is backwards-compatible
}
silent_in_dir
Prototype: silent_in_dir(dir)
Description: run command after switching to directory and suppress output
Arguments:
dir
: directory to change into
Example:
"/bin/pwd"
contain => silent_in_dir("/tmp");
Implementation:
body contain silent_in_dir(dir)
{
chdir => "$(dir)";
no_output => "true";
}
in_shell
Prototype: in_shell
Description: run command in shell
Example:
commands:
"/bin/pwd | /bin/cat"
contain => in_shell;
Implementation:
body contain in_shell
{
useshell => "true"; # canonical "useshell" but this is backwards-compatible
}
in_shell_bg
Prototype: in_shell_bg
Description: deprecated This bundle previously had an invalid background attribute that was caught by parser strictness enhancements. Backgrounding is handeled by the body action background attribute.
Implementation:
body contain in_shell_bg
{
useshell => "true"; # canonical "useshell" but this is backwards-compatible
}
in_shell_and_silent
Prototype: in_shell_and_silent
Description: run command in shell and suppress output
Example:
commands:
"/bin/pwd | /bin/cat"
contain => in_shell_and_silent,
comment => "Silently run command in shell";
Implementation:
body contain in_shell_and_silent
{
useshell => "true"; # canonical "useshell" but this is backwards-compatible
no_output => "true";
}
in_dir_shell_and_silent
Prototype: in_dir_shell_and_silent(dir)
Description: run command in shell after switching to 'dir' and suppress output
Arguments:
dir
: directory to change into
Example:
commands:
"/bin/pwd | /bin/cat"
contain => in_dir_shell_and_silent("/tmp"),
comment => "Silently run command in shell";
Implementation:
body contain in_dir_shell_and_silent(dir)
{
useshell => "true"; # canonical "useshell" but this is backwards-compatible
no_output => "true";
chdir => "$(dir)";
}
setuid
Prototype: setuid(owner)
Description: run command as specified user
Arguments:
owner
: username or uid to run command as
Example:
commands:
"/usr/bin/id"
contain => setuid("apache");
"/usr/bin/id"
contain => setuid("503");
Implementation:
body contain setuid(owner)
{
exec_owner => "$(owner)";
}
setuid_sh
Prototype: setuid_sh(owner)
Description: run command as specified user in shell
Arguments:
owner
: username or uid to run command as
Example:
commands:
"/usr/bin/id | /bin/cat"
contain => setuid("apache");
"/usr/bin/id | /bin/cat"
contain => setuid("503");
Implementation:
body contain setuid_sh(owner)
{
exec_owner => "$(owner)";
useshell => "true"; # canonical "useshell" but this is backwards-compatible
}
setuidgid_dir
Prototype: setuidgid_dir(owner, group, dir)
Description: run command as specified owner and group in shell
Arguments:
owner
: username or uid to run command asgroup
: groupname or gid to run command asdir
: directory to run command from
Implementation:
body contain setuidgid_dir(owner,group,dir)
{
exec_owner => "$(owner)";
exec_group => "$(group)";
chdir => "$(dir)";
}
setuidgid_sh
Prototype: setuidgid_sh(owner, group)
Description: run command as specified owner and group in shell
Arguments:
owner
: username or uid to run command asgroup
: groupname or gid to run command as
Implementation:
body contain setuidgid_sh(owner,group)
{
exec_owner => "$(owner)";
exec_group => "$(group)";
useshell => "true"; # canonical "useshell" but this is backwards-compatible
}
jail
Prototype: jail(owner, jail_root, dir)
Description: run command as specified user in specified directory of jail
Arguments:
owner
: username or uid to run command asjail_root
: path that will be the root directory for the processdir
: directory to change to before running command (must be within 'jail_root')
Implementation:
body contain jail(owner,jail_root,dir)
{
exec_owner => "$(owner)";
useshell => "true"; # canonical "useshell" but this is backwards-compatible
chdir => "$(dir)";
chroot => "$(jail_root)";
}
setuid_umask
Prototype: setuid_umask(owner, umask)
Description: run command as specified user with umask
Valid Values | Umask | Octal (files) | Symbolic (files) | Octal (dirs) | Symbolic (dirs) |
---|---|---|---|---|---|
0 |
000 |
666 |
(rw-rw-rw-) |
777 |
(rwxrwxrwx) |
002 |
002 |
664 |
(rw-rw-r--) |
775 |
(rwxrwxr-x) |
22 , 022 |
022 |
644 |
(rw-r--r--) |
755 |
(rwxr-xr-x) |
27 , 027 |
027 |
640 |
(rw-r-----) |
750 |
(rwxr-x---) |
77 , 077 |
077 |
600 |
(rw-------) |
700 |
(rwx------) |
72 , 072 |
072 |
604 |
(rw----r--) |
705 |
(rwx---r-x) |
Arguments:
owner
: username or uid to run command asumask
: controls permissions of created files and directories
Example:
commands:
"/usr/bin/git pull"
contain => setuid_umask("git", "022");
Implementation:
body contain setuid_umask(owner, umask)
{
exec_owner => "$(owner)";
umask => "$(umask)";
}
setuid_gid_umask
Prototype: setuid_gid_umask(uid, gid, umask)
Description: run command as specified user with umask
Valid Values | Umask | Octal (files) | Symbolic (files) | Octal (dirs) | Symbolic (dirs) |
---|---|---|---|---|---|
0 |
000 |
666 |
(rw-rw-rw-) |
777 |
(rwxrwxrwx) |
002 |
002 |
664 |
(rw-rw-r--) |
775 |
(rwxrwxr-x) |
22 , 022 |
022 |
644 |
(rw-r--r--) |
755 |
(rwxr-xr-x) |
27 , 027 |
027 |
640 |
(rw-r-----) |
750 |
(rwxr-x---) |
77 , 077 |
077 |
600 |
(rw-------) |
700 |
(rwx------) |
72 , 072 |
072 |
604 |
(rw----r--) |
705 |
(rwx---r-x) |
Arguments:
uid
: username or uid to run command asgid
: group name or gid to run command asumask
: controls permissions of created files and directories
Example:
commands:
"/usr/bin/git pull"
contain => setuid_gid_umask("git", "minions", "022");
Implementation:
body contain setuid_gid_umask(uid, gid, umask)
{
exec_owner => "$(uid)";
exec_group => "$(uid)";
umask => "$(umask)";
}
For update.cf?
common bodies
cfengine_update_controls
Prototype: cfengine_update_controls
Implementation:
bundle common cfengine_update_controls
{
vars:
# 3.6 uses the split controls
cfengine_3_6::
"update_def_inputs"
slist => {
"controls/$(sys.cf_version_major).$(sys.cf_version_minor)/update_def.cf",
"controls/$(sys.cf_version_major).$(sys.cf_version_minor)/update_def_inputs.cf",
};
# 3.7+ uses the re-unified controls
!cfengine_3_6::
"update_def_inputs"
slist => {
"controls/update_def.cf",
"controls/update_def_inputs.cf",
};
reports:
DEBUG|DEBUG_cfengine_update_controls::
"DEBUG $(this.bundle): update def inputs='$(update_def_inputs)'";
}
agent bundles
cfengine_internal_standalone_self_upgrade
Prototype: cfengine_internal_standalone_self_upgrade
Description: Manage desired version state and execution of policy to reach the target version.
Implementation:
bundle agent cfengine_internal_standalone_self_upgrade
{
methods:
"cfengine_internal_standalone_self_upgrade_state_data";
"cfengine_internal_standalone_self_upgrade_execution";
}
cfengine_internal_standalone_self_upgrade_state_data
Prototype: cfengine_internal_standalone_self_upgrade_state_data
Description: Clear stale recorded desired version information from state
Implementation:
bundle agent cfengine_internal_standalone_self_upgrade_state_data
{
vars:
"binary_upgrade_entry"
string => "$(this.promise_dirname)/standalone_self_upgrade.cf";
"desired_pkg_data_path" string =>
"$(cfengine_internal_standalone_self_upgrade_execution.desired_pkg_data_path)";
files:
# We consider the data stale if it's older than the policy that generated it
"$(desired_pkg_data_path)" -> { "ENT-4317" }
delete => u_tidy,
if => isnewerthan( $(binary_upgrade_entry) , $(desired_pkg_data_path) );
}
cfengine_internal_standalone_self_upgrade_execution
Prototype: cfengine_internal_standalone_self_upgrade_execution
Description: Manage the version of CFEngine that is currently installed. This policy executes a stand alone policy as a sub agent. If systemd is found we assume that it is necessary to escape the current unit via systemd-run.
If the running version matches either the desired version information in state or the version supplied from augments, then we skip running the standalone upgrade policy.
Implementation:
bundle agent cfengine_internal_standalone_self_upgrade_execution
{
vars:
"exec_prefix"
string => ifelse( isexecutable("/bin/systemd-run"), "/bin/systemd-run --unit=cfengine-upgrade --scope ", # trailing space in commands important
isexecutable( "/usr/bin/systemd-run" ), "/usr/bin/systemd-run --unit=cfengine-upgrade --scope ",
"");
"desired_pkg_data_path" -> { "ENT-3592" }
string => "$(sys.statedir)/MPF/desired-cfengine-package-version.json";
"desired_pkg_data" -> { "ENT-3592" }
data => readjson( $(desired_pkg_data_path) ),
if => fileexists( $(desired_pkg_data_path) );
"local_update_log_dir"
string => translatepath("$(sys.workdir)/software_updates/update_log"),
comment => "This directory is used for logging the current version of cfengine running.";
classes:
# If we are running the version desired by the self upgrade policy
"at_desired_version_by_policy_specification" -> { "ENT-3592" }
expression => strcmp( "$(desired_pkg_data[version])", "$(sys.cf_version)" );
# If we are running the version explicitly defined by the user
"at_desired_version_by_user_specification" -> { "ENT-3592" }
expression => strcmp( "$(def.cfengine_software_pkg_version)", "$(sys.cf_version)" );
"at_desired_version"
or => { "at_desired_version_by_user_specification", "at_desired_version_by_policy_specification" };
files:
enterprise_edition::
"$(local_update_log_dir)/$(sys.cf_version)_is_running" -> { "ENT-4352" }
comment => "This results in a record of the first time the enterprise
agent of a given version is seen to run on a host.",
handle => "cfe_internal_update_bins_files_version_is_running",
create => "true";
commands:
trigger_upgrade.!at_desired_version::
"$(exec_prefix)$(sys.cf_agent)"
handle => "standalone_self_upgrade",
args => '--inform --timestamp --file "$(this.promise_dirname)$(const.dirsep)standalone_self_upgrade.cf" --define trigger_upgrade,update_cf_initiated';
reports:
inform_mode|verbose_mode|DEBUG|DEBUG_cfengine_internal_standalone_self_upgrade::
"Skipped self upgrade because we are running the desired version $(sys.cf_version)" -> { "ENT-3592" }
if => "at_desired_version";
}
common bodies
control
Prototype: control
Implementation:
body common control
{
bundlesequence => {
"update_def",
"u_cfengine_enterprise",
@(u_cfengine_enterprise.def),
"cfe_internal_dc_workflow",
"cfe_internal_update_policy",
"cfengine_internal_standalone_self_upgrade",
"cfe_internal_update_processes",
};
version => "update.cf $(update_def.current_version)";
inputs => {
"cfe_internal/update/lib.cf",
"cfe_internal/update/systemd_units.cf",
@(cfengine_update_controls.update_def_inputs),
"cfe_internal/update/cfe_internal_dc_workflow.cf",
"cfe_internal/update/cfe_internal_local_git_remote.cf",
"cfe_internal/update/cfe_internal_update_from_repository.cf",
"cfe_internal/update/update_policy.cf",
"cfe_internal/update/update_processes.cf"
};
}
agent bodies
control
Prototype: control
Implementation:
body agent control
{
ifelapsed => "1";
skipidentify => "true";
}
classes bodies
u_kept_successful_command
Prototype: u_kept_successful_command
Description: Set command to "kept" instead of "repaired" if it returns 0
Implementation:
body classes u_kept_successful_command
{
kept_returncodes => { "0" };
failed_returncodes => { "1" };
}
for Promises.cf?
common bodies
inventory
Prototype: inventory
Description: Set up inventory inputs
This bundle creates the inputs for inventory bundles.
Inventory bundles are simply common bundles loaded before anything else in promises.cf
Tested to work properly against 3.5.x
Implementation:
bundle common inventory
{
classes:
"other_unix_os" expression => "!windows.!macos.!linux.!freebsd";
"specific_linux_os" expression => "redhat|debian|suse";
vars:
# This list is intended to grow as needed
debian::
"inputs" slist => { "inventory/any.cf", "inventory/linux.cf", "inventory/lsb.cf", "inventory/debian.cf", "inventory/os.cf" };
"bundles" slist => { "inventory_control", "inventory_any", "inventory_autorun", "inventory_linux", "inventory_lsb", "inventory_debian", "inventory_os" };
redhat::
"inputs" slist => { "inventory/any.cf", "inventory/linux.cf", "inventory/lsb.cf", "inventory/redhat.cf", "inventory/os.cf" };
"bundles" slist => { "inventory_control", "inventory_any", "inventory_autorun", "inventory_linux", "inventory_lsb", "inventory_redhat", "inventory_os" };
suse::
"inputs" slist => { "inventory/any.cf", "inventory/linux.cf", "inventory/lsb.cf", "inventory/suse.cf", "inventory/os.cf" };
"bundles" slist => { "inventory_control", "inventory_any", "inventory_autorun", "inventory_linux", "inventory_lsb", "inventory_suse", "inventory_os" };
windows::
"inputs" slist => { "inventory/any.cf", "inventory/windows.cf", "inventory/os.cf" };
"bundles" slist => { "inventory_control", "inventory_any", "inventory_autorun", "inventory_windows", "inventory_os" };
macos::
"inputs" slist => { "inventory/any.cf", "inventory/macos.cf", "inventory/os.cf" };
"bundles" slist => { "inventory_control", "inventory_any", "inventory_autorun", "inventory_macos", "inventory_os" };
freebsd::
"inputs" slist => { "inventory/any.cf", "inventory/freebsd.cf", "inventory/os.cf" };
"bundles" slist => { "inventory_control", "inventory_any", "inventory_autorun", "inventory_freebsd", "inventory_os" };
linux.!specific_linux_os::
"inputs" slist => { "inventory/any.cf", "inventory/linux.cf", "inventory/lsb.cf", "inventory/os.cf" };
"bundles" slist => { "inventory_control", "inventory_any", "inventory_autorun", "inventory_linux", "inventory_lsb", "inventory_os" };
aix::
"inputs" slist => { "inventory/any.cf", "inventory/generic.cf", "inventory/aix.cf", "inventory/os.cf" };
"bundles" slist => { "inventory_control", "inventory_any", "inventory_autorun", "inventory_generic", "inventory_aix", "inventory_os" };
other_unix_os::
"inputs" slist => { "inventory/any.cf", "inventory/generic.cf", "inventory/os.cf" };
"bundles" slist => { "inventory_control", "inventory_any", "inventory_autorun", "inventory_generic", "inventory_os" };
reports:
verbose_mode::
"$(this.bundle): loading inventory module '$(inputs)'";
}
cfe_internal_inputs
Prototype: cfe_internal_inputs
Description: Include internal self management policies
Implementation:
bundle common cfe_internal_inputs
{
vars:
any::
"input[cfe_internal_management]"
string => "cfe_internal/CFE_cfengine.cf",
comment => "This policy activates internal management policies
for both core and enterprise";
"input[core_main]"
string => "cfe_internal/core/main.cf",
comment => "This policy activates other core policies";
"input[core_limit_robot_agents]"
string => "cfe_internal/core/limit_robot_agents.cf",
comment => "The policy here ensures that we don't have too many
cf-monitord or cf-execd processes";
"input[core_log_rotation]"
string => "cfe_internal/core/log_rotation.cf",
comment => "This policy ensures that various cfengine log files
do not grow without bound and fill up the disk";
"input[core_host_info_report]"
string => "cfe_internal/core/host_info_report.cf",
comment => "This policy produces a text based host info report
and serves as a functional example of using mustache templates";
"input[cfengine_internal_core_watchdog]"
string => "cfe_internal/core/watchdog/watchdog.cf",
comment => "This policy configures external watchdogs to ensure that
cf-execd is always running.";
enterprise_edition::
"input[enterprise_hub_specific]"
string => "cfe_internal/enterprise/CFE_hub_specific.cf",
comment => "Policy relating to CFEngine Enterprise Hub, for example
software updates, webserver configuration, and alerts";
"input[enterprise_knowledge]"
string => "cfe_internal/enterprise/CFE_knowledge.cf",
comment => "Settings mostly releated to CFEngine Enteprise Mission Portal";
"input[enterprise_main]"
string => "cfe_internal/enterprise/main.cf",
comment => "This policy activates other enterprise specific policies";
"input[change_management]"
string => "cfe_internal/enterprise/file_change.cf",
comment => "This policy monitors critical system files for change";
"input[enterprise_mission_portal]"
string => "cfe_internal/enterprise/mission_portal.cf",
comment => "This policy manages Mission Portal related configurations.";
any::
"inputs" slist => getvalues("input");
}
cfengine_stdlib
Prototype: cfengine_stdlib
Description: Include the standard library
Implementation:
bundle common cfengine_stdlib
{
vars:
!cfengine_3_7::
# CFEngine 3.6 can include through a secondary file
# CFEngine version 3.6 and prior use the split library to avoid syntax
# errors introduced by new functionality. For example new functions.
# This also works for 3.8 because local_libdir should be set to lib
# instead of lib/3.8
"inputs" slist => { "$(sys.local_libdir)/stdlib.cf" };
cfengine_3_7::
# CFEngine 3.7 has local_libdir set to $(sys.inputdir)/lib/3.7, but with
# the @if macro support we can re-unify the split library for 3.7+ so we
# specify the unified lib relative to local_libdir.
"inputs" slist => { "$(sys.local_libdir)/../stdlib.cf" };
reports:
verbose_mode::
"$(this.bundle): defining inputs='$(inputs)'";
}
cfengine_controls
Prototype: cfengine_controls
Description: Include various agent control policies
Implementation:
bundle common cfengine_controls
{
vars:
# 3.7+ uses the re-unified controls
cfengine_3_6::
"def_inputs"
slist => {
"controls/$(sys.cf_version_major).$(sys.cf_version_minor)/def.cf",
"controls/$(sys.cf_version_major).$(sys.cf_version_minor)/def_inputs.cf",
},
comment => "We strictly order the def inputs because they should be parsed first";
"input[cf_agent]"
string => "controls/$(sys.cf_version_major).$(sys.cf_version_minor)/cf_agent.cf",
comment => "Agent control options";
"input[cf_execd]"
string => "controls/$(sys.cf_version_major).$(sys.cf_version_minor)/cf_execd.cf",
comment => "Executor (scheduler) control options";
"input[cf_monitord]"
string => "controls/$(sys.cf_version_major).$(sys.cf_version_minor)/cf_monitord.cf",
comment => "Monitor/Measurement control options";
"input[cf_serverd]"
string => "controls/$(sys.cf_version_major).$(sys.cf_version_minor)/cf_serverd.cf",
comment => "Server control options";
"input[cf_runagent]"
string => "controls/$(sys.cf_version_major).$(sys.cf_version_minor)/cf_runagent.cf",
comment => "Runagent (remote activation request) control options";
enterprise_edition.cfengine_3_6::
"input[cf_hub]" -> { "CFEngine Enterprise" }
string => "controls/$(sys.cf_version_major).$(sys.cf_version_minor)/cf_hub.cf",
comment => "Hub (agent report collection) control options";
"input[reports]" -> { "CFEngine Enterprise" }
string => "controls/$(sys.cf_version_major).$(sys.cf_version_minor)/reports.cf",
comment => "Report collection options";
# 3.7+ uses the re-unified controls
!cfengine_3_6::
"def_inputs"
slist => {
"controls/def.cf",
"controls/def_inputs.cf",
},
comment => "We strictly order the def inputs because they should be parsed first";
"input[cf_agent]"
string => "controls/cf_agent.cf",
comment => "Agent control options";
"input[cf_execd]"
string => "controls/cf_execd.cf",
comment => "Executor (scheduler) control options";
"input[cf_monitord]"
string => "controls/cf_monitord.cf",
comment => "Monitor/Measurement control options";
"input[cf_serverd]"
string => "controls/cf_serverd.cf",
comment => "Server control options";
"input[cf_runagent]"
string => "controls/cf_runagent.cf",
comment => "Runagent (remote activation request) control options";
enterprise_edition.!cfengine_3_6::
"input[cf_hub]" -> { "CFEngine Enterprise" }
string => "controls/cf_hub.cf",
comment => "Hub (agent report collection) control options";
"input[reports]" -> { "CFEngine Enterprise" }
string => "controls/reports.cf",
comment => "Report collection options";
any::
"inputs" slist => getvalues(input);
reports:
DEBUG|DEBUG_cfengine_controls::
"DEBUG $(this.bundle)";
"$(const.t)defining inputs='$(inputs)'";
}
services_autorun
Prototype: services_autorun
Description: Include autorun policy and discover autorun bundles if enabled
Implementation:
bundle common services_autorun
{
vars:
!cfengine_3_7.services_autorun::
# Both 3.6 and 3.8+ can use local_libdir
# 3.6 will use the split library in the version specific path
# 3.8+ will use the common lib as it supports the @if macro
"inputs" slist => { "$(sys.local_libdir)/autorun.cf" };
"found_inputs" slist => lsdir("$(this.promise_dirname)/services/autorun", ".*\.cf", "true");
"bundles" slist => { "autorun" }; # run loaded bundles
cfengine_3_7.services_autorun::
# We have to point 3.7 at the unified library because sys.local_libdir in
# 3.7 binaries it is set to a version specific path. However since 3.7
# knows about the @if macro it is safe to share the same policy as 3.8+
"inputs" slist => { "$(sys.local_libdir)/../autorun.cf" };
"found_inputs" slist => lsdir("$(this.promise_dirname)/services/autorun", ".*\.cf", "true");
"bundles" slist => { "autorun" }; # run loaded bundles
!services_autorun::
# If services_autorun is not enabled, then we should not extend inputs
# automatically.
"inputs" slist => { };
"found_inputs" slist => {};
"bundles" slist => { "services_autorun" }; # run self
reports:
DEBUG|DEBUG_services_autorun::
"DEBUG $(this.bundle): Services Autorun Disabled"
ifvarclass => "!services_autorun";
"DEBUG $(this.bundle): Services Autorun Enabled"
ifvarclass => "services_autorun";
"DEBUG $(this.bundle): adding input='$(inputs)'"
ifvarclass => isvariable("inputs");
"DEBUG $(this.bundle): adding input='$(found_inputs)'"
ifvarclass => isvariable("found_inputs");
}
common bodies
control
Prototype: control
Description: Control options common to all agents
Implementation:
body common control
{
bundlesequence => {
# Common bundle first (Best Practice)
inventory_control,
@(inventory.bundles),
def,
@(cfengine_enterprise_hub_ha.classification_bundles),
# Design Center
cfsketch_run,
# autorun system
services_autorun,
@(services_autorun.bundles),
# Agent bundle
cfe_internal_management, # See cfe_internal/CFE_cfengine.cf
main,
@(cfengine_enterprise_hub_ha.management_bundles),
@(def.bundlesequence_end),
};
inputs => {
# File definition for global variables and classes
@(cfengine_controls.def_inputs),
# Inventory policy
@(inventory.inputs),
# Design Center
"sketches/meta/api-runfile.cf",
@(cfsketch_g.inputs),
# CFEngine internal policy for the management of CFEngine itself
@(cfe_internal_inputs.inputs),
# Control body for all CFEngine robot agents
@(cfengine_controls.inputs),
# COPBL/Custom libraries. Eventually this should use wildcards.
@(cfengine_stdlib.inputs),
# autorun system
@(services_autorun.inputs),
"services/main.cf",
};
version => "CFEngine Promises.cf 3.10.7";
# From 3.7 onwards there is a new package promise implementation using package
# modules in which you MUST provide package modules used to generate
# software inventory reports. You can also provide global default package module
# instead of specifying it in all package promises.
debian.!disable_inventory_package_refresh::
package_inventory => { $(package_module_knowledge.platform_default) };
# We only define pacakge_invetory on redhat like systems that have a
# python version that works with the package module.
(redhat|centos|suse).cfe_yum_package_module_supported.!disable_inventory_package_refresh::
package_inventory => { $(package_module_knowledge.platform_default) };
(debian|redhat|suse)::
package_module => $(package_module_knowledge.platform_default);
}
Variables
Referencing a version of CFEngine? Consider if that appearance should be updated with each new version.
Variables that are defined in the front matter (thats the content between the three dashes at the top) or in _config.yaml in the documentation-generator repository can be used directly within markdown.
For example this is the '3.10' version of the documentation. That variable comes from _config.yaml.
Since liquid variables look a lot like mustache variables any time you want to show the actual variables will need to be inside of raw tags.
site.CFE_manuals_version {{ site.CFE_manuals_version }}