From a4ad4cbdf31c6802ea370fa3d4565dbaddbedc9c Mon Sep 17 00:00:00 2001 From: Nick Anderson Date: Wed, 8 Nov 2023 15:24:27 -0600 Subject: [PATCH] Added documentation for --simulate --- .../controls-cf_agent.markdown | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/reference/masterfiles-policy-framework/controls-cf_agent.markdown b/reference/masterfiles-policy-framework/controls-cf_agent.markdown index 3d3387117..386963ab3 100644 --- a/reference/masterfiles-policy-framework/controls-cf_agent.markdown +++ b/reference/masterfiles-policy-framework/controls-cf_agent.markdown @@ -8,3 +8,51 @@ This is where `body agent control` is defined. `body agent control` is where various settings related to `cf-agent` can be tuned. [%CFEngine_library_include(controls/cf_agent)%] + +## Options +### --simulate + +Like the `--dry-run` option, the `--simulate` option tries to identify changes +to your system without making changes to the system, however it goes further +than `--dry-run` by making changes in a `chroot` and making a distinction +between *safe* and *unsafe* functions, e.g. `execresult()`. + +The agent will execute promises with unsafe functions when the `--simulate` +options is given only if the promise using the function is tagged `simulate_safe`. + +For example: + +```cf3 +bundle agent __main__ +{ + vars: + "msg" + string => execresult( "/bin/echo Hello world!", "useshell" ), + meta => { "simulate_safe" }; + +} +``` + +The simulate option takes a parameter, `diff`, `manifest`, or `manifest-full` +which is used to determine the summary output shown at the end of the run. + +* `diff` - Show only things that changed during the simulated run. +* `manifest` - Show files and packages changed by the simulated run. +* `manifest-full` - Show all files evaluated by the simulated run (including unchanged ones) + + - cf-agent can now simulate the changes done to files in a chroot, printing + diff or manifest information about what it would do in a normal evaluation. + Use the new command line option: `--simulate=diff` or `--simulate=manifest`. + Please note that only files and packages promises are simulated currently. + + - Added a new --simulate=manifest-full mode + New simulation mode that manifests all changed files as well as + all other files evaluated by the agent run which were not skipped + (by file selection rules) (CFE-3506) + +#### Notes +* Supported on Linux for `files` and `packages` type promises + +#### History +* Introduced in version 3.17.0 +* `--simulate=manifest-full` introduced in version 3.18.0