diff --git a/examples.markdown b/examples.markdown index 6ce8a48c2..3c5634736 100644 --- a/examples.markdown +++ b/examples.markdown @@ -51,6 +51,7 @@ Following these steps, you will login to your policy server via the SSH protocol 5. In the vi editor, enter ```i``` for "Insert" and enter the following content (ie. copy and paste from a text editor): ```cf3 + [file=hello_world.cf] bundle agent hello_world { reports: @@ -78,21 +79,23 @@ hosts][Classes and decisions]. Activate the bundle manually by executing the following command at prompt: -```console +```command /var/cfengine/bin/cf-agent --no-lock --file ./hello_world.cf --bundlesequence hello_world ``` This command instructs CFEngine to ignore [locks][Controlling frequency], load the `hello_world.cf` policy, and activate the `hello_world` bundle. See the output below: -```console +```command # /var/cfengine/bin/cf-agent --no-lock --file ./hello_world.cf --bundlesequence hello_world +``` +```output 2013-08-20T14:03:43-0500 notice: R: Hello World! ``` As you get familiar with CFEngine, you'll probably start shortening this command to this equivalent: -```console +```command /var/cfengine/bin/cf-agent -Kf ./hello_world.cf -b hello_world ``` @@ -118,6 +121,7 @@ Go back into vi by typing "vi" at the prompt. Then type ```i``` to insert shown in the following example: ```cf3 +[file=hello_world.cf] body common control { bundlesequence => { "hello_world" }; @@ -138,20 +142,23 @@ Now press "esc" to exit the "Insert" mode, then type ```:w``` to save the file c Exit vi by typing ```:q``` then "Enter." This will return to the prompt. Execute the following command: -```console +```command /var/cfengine/bin/cf-agent --no-lock --file ./hello_world.cf ``` The output is shown below: -```console +```command # /var/cfengine/bin/cf-agent --no-lock --file ./hello_world.cf +``` +```output 2013-08-20T14:25:36-0500 notice: R: Hello World! ``` Note: It may be necessary to add a reference to the standard library within the body common control section, and remove the bundlesequence line. Example: ```cf3 +[file=hello_world.cf] body common control { inputs => { "libraries/cfengine_stdlib.cf", @@ -171,6 +178,7 @@ Again type "vi" then "Enter" then ```i``` to insert the following: Add it before __body common control__, as shown below: ```cf3 +[file=hello_world.cf] #!/var/cfengine/bin/cf-agent --no-lock body common control { @@ -193,21 +201,19 @@ then exit vi by typing ```:q``` then "Enter". This will return to the prompt. Make the policy file executable, and then run it, by typing the following two commands: -```console +```command chmod +x ./hello_world.cf ``` Followed by: -```console +```command ./hello_world.cf ``` See the output below: -```console -# chmod +x ./hello_world.cf -# ./hello_world.cf +```output 2013-08-20T14:39:34-0500 notice: R: Hello World! ``` diff --git a/examples/example-snippets/promise-patterns/example_aborting_execution.markdown b/examples/example-snippets/promise-patterns/example_aborting_execution.markdown index 1dd079d36..cae5db3af 100644 --- a/examples/example-snippets/promise-patterns/example_aborting_execution.markdown +++ b/examples/example-snippets/promise-patterns/example_aborting_execution.markdown @@ -14,18 +14,20 @@ If any of these classes becomes defined, it will cause the current bundle to be [%CFEngine_include_example(abort.cf)%] This is how the policy runs when the userlist is valid: - - # cf-agent -f unit_abort.cf - R: User name mark is valid at 4 letters - R: User name john is valid at 4 letters - # - +```command +cf-agent -f unit_abort.cf +``` +```output +R: User name mark is valid at 4 letters +R: User name john is valid at 4 letters +``` This is how the policy runs when the userlist contains an invalid entry: - - # cf-agent -f unit_abort.cf - Bundle example aborted on defined class "invalid" - # - +```command +cf-agent -f unit_abort.cf +``` +```output +Bundle example aborted on defined class "invalid" +``` To run this example file as part of your main policy you need to make an additional change: diff --git a/examples/example-snippets/promise-patterns/example_change_detection.markdown b/examples/example-snippets/promise-patterns/example_change_detection.markdown index fcecc79f4..90c3ae9d7 100644 --- a/examples/example-snippets/promise-patterns/example_change_detection.markdown +++ b/examples/example-snippets/promise-patterns/example_change_detection.markdown @@ -22,18 +22,21 @@ First, let's create some files for CFEngine to monitor: CFEngine detects new files and adds them to the file integrity database: +```command +cf-agent -f unit_change_detect.cf ``` -# cf-agent -f unit_change_detect.cf +```output 2013-06-06T20:53:26-0700 error: /example/files/'/etc/example': File '/etc/example/example.conf' was not in 'md5' database - new file found -# cf-agent -f unit_change_detect.cf -K +``` +```command +cf-agent -f unit_change_detect.cf -K ``` If there are no changes, CFEngine runs silently: -``` -# cf-agent -f unit_change_detect.cf -# +```command +cf-agent -f unit_change_detect.cf ``` Now let's update the mtime, and then the mtime and content. diff --git a/examples/example-snippets/promise-patterns/example_create_filedir.markdown b/examples/example-snippets/promise-patterns/example_create_filedir.markdown index ae5606d9c..da0c7ef10 100644 --- a/examples/example-snippets/promise-patterns/example_create_filedir.markdown +++ b/examples/example-snippets/promise-patterns/example_create_filedir.markdown @@ -12,10 +12,11 @@ and set permissions on both. Example output: +```command +cf-agent -f unit_create_filedir.cf -I ``` -# cf-agent -f unit_create_filedir.cf -I +```output 2013-06-08T14:56:26-0700 info: /example/files/'/home/mark/tmp/test_plain': Created file '/home/mark/tmp/test_plain', mode 0640 2013-06-08T14:56:26-0700 info: /example/files/'/home/mark/tmp/test_dir/.': Created directory '/home/mark/tmp/test_dir/.' 2013-06-08T14:56:26-0700 info: /example/files/'/home/mark/tmp/test_dir/.': Object '/home/mark/tmp/test_dir' had permission 0755, changed it to 0750 -# ``` diff --git a/examples/example-snippets/promise-patterns/example_diskfree.markdown b/examples/example-snippets/promise-patterns/example_diskfree.markdown index 8545f9757..5722b30c9 100644 --- a/examples/example-snippets/promise-patterns/example_diskfree.markdown +++ b/examples/example-snippets/promise-patterns/example_diskfree.markdown @@ -12,11 +12,16 @@ Check how much space (in KB) is available on a directory's current partition. Example output: +```command +cf-agent -f unit_diskfree.cf ``` -# cf-agent -f unit_diskfree.cf +```output R: Freedisk 48694692 -# df -k /tmp +``` +```command +df -k /tmp +``` +```output Filesystem 1K-blocks Used Available Use% Mounted on /dev/sda1 149911836 93602068 48694692 66% / -# ``` diff --git a/examples/example-snippets/promise-patterns/example_edit_motd.markdown b/examples/example-snippets/promise-patterns/example_edit_motd.markdown index e90b09061..c36cd564c 100644 --- a/examples/example-snippets/promise-patterns/example_edit_motd.markdown +++ b/examples/example-snippets/promise-patterns/example_edit_motd.markdown @@ -30,8 +30,10 @@ The bundle is defined like this: **Example run:** -```console -root@debian8:~/core/examples# cf-agent -KIf ./mustache_template_motd.cf; cat /etc/motd +```command + cf-agent -KIf ./mustache_template_motd.cf; cat /etc/motd + ``` +```output info: Updated rendering of '/etc/motd' from mustache template 'inline' info: files promise '/etc/motd' repaired # Managed by CFEngine diff --git a/examples/example-snippets/promise-patterns/example_enable_service.markdown b/examples/example-snippets/promise-patterns/example_enable_service.markdown index 89b863890..a03da13d6 100644 --- a/examples/example-snippets/promise-patterns/example_enable_service.markdown +++ b/examples/example-snippets/promise-patterns/example_enable_service.markdown @@ -24,8 +24,10 @@ correct return codes for status checks. We can see that before the policy run `sysstat` is *inactive*, `apache2` is *active*, `cups` is *active*, `ssh` is *active* and `cron` is *inactive*. -```console -root@ubuntu:# systemctl is-active sysstat apache2 cups ssh cron +```command +systemctl is-active sysstat apache2 cups ssh cron +``` +```output inactive active active @@ -35,21 +37,25 @@ inactive Now we run the policy to converge the system to the desired state. -```console -root@ubuntu:# cf-agent --no-lock --inform --file ./services.cf - info: Executing 'no timeout' ... '/bin/systemctl --no-ask-password --global --system -q stop apache2' - info: Completed execution of '/bin/systemctl --no-ask-password --global --system -q stop apache2' - info: Executing 'no timeout' ... '/bin/systemctl --no-ask-password --global --system -q stop cups' - info: Completed execution of '/bin/systemctl --no-ask-password --global --system -q stop cups' - info: Executing 'no timeout' ... '/bin/systemctl --no-ask-password --global --system -q start cron' - info: Completed execution of '/bin/systemctl --no-ask-password --global --system -q start cron' +```command +cf-agent --no-lock --inform --file ./services.cf +``` +```output +info: Executing 'no timeout' ... '/bin/systemctl --no-ask-password --global --system -q stop apache2' +info: Completed execution of '/bin/systemctl --no-ask-password --global --system -q stop apache2' +info: Executing 'no timeout' ... '/bin/systemctl --no-ask-password --global --system -q stop cups' +info: Completed execution of '/bin/systemctl --no-ask-password --global --system -q stop cups' +info: Executing 'no timeout' ... '/bin/systemctl --no-ask-password --global --system -q start cron' +info: Completed execution of '/bin/systemctl --no-ask-password --global --system -q start cron' ``` After the policy run we can see that `systat`, `apache2`, and `cups` are *inactive*. `ssh` and `cron` are *active* as specified in the policy. -```console -root@ubuntu:/home/nickanderson/CFEngine/core/examples# systemctl is-active sysstat apache2 cups ssh cron +```command +systemctl is-active sysstat apache2 cups ssh cron +``` +```output inactive inactive inactive @@ -63,52 +69,90 @@ We can see that before the policy run `sysstat` is not reporting status correctly , `httpd` is *running*, `cups` is *running*, `sshd` is *running* and `crond` is *not running*. -```console -[root@localhost examples]# service sysstat status; echo $? +```command +service sysstat status; echo $? +``` +```output 3 -[root@localhost examples]# service httpd status; echo $? +``` +```command +service httpd status; echo $? +``` +```output httpd (pid 3740) is running... 0 -[root@localhost examples]# service cups status; echo $? +``` +```command +service cups status; echo $? +``` +```output cupsd (pid 3762) is running... 0 -[root@localhost examples]# service sshd status; echo $? +``` +```command +service sshd status; echo $? +``` +```output openssh-daemon (pid 3794) is running... 0 -[root@localhost examples]# service crond status; echo $? +``` +```command +service crond status; echo $? +``` +```output crond is stopped 3 ``` Now we run the policy to converge the system to the desired state. -```console -[root@localhost examples]# cf-agent -KIf ./services.cf - info: Executing 'no timeout' ... '/etc/init.d/crond start' - info: Completed execution of '/etc/init.d/crond start' - info: Executing 'no timeout' ... '/etc/init.d/httpd stop' - info: Completed execution of '/etc/init.d/httpd stop' - info: Executing 'no timeout' ... '/etc/init.d/cups stop' - info: Completed execution of '/etc/init.d/cups stop' +```command +cf-agent -KIf ./services.cf +``` +```output +info: Executing 'no timeout' ... '/etc/init.d/crond start' +info: Completed execution of '/etc/init.d/crond start' +info: Executing 'no timeout' ... '/etc/init.d/httpd stop' +info: Completed execution of '/etc/init.d/httpd stop' +info: Executing 'no timeout' ... '/etc/init.d/cups stop' +info: Completed execution of '/etc/init.d/cups stop' ``` After the policy run we can see that `systat` is still not reporting status correctly (some services do not respond to standard checks), `apache2`, and `cups` are *inactive*. `ssh` and `cron` are *active* as specified in the policy. -```console -[root@localhost examples]# service sysstat status; echo $? +```command +service sysstat status; echo $? +``` +```output 3 -[root@localhost examples]# service httpd status; echo $? +``` +```command +service httpd status; echo $? +``` +```output httpd is stopped 3 -[root@localhost examples]# service cups status; echo $? -cupsd is stopped +``` +```command +service cups status; echo $? +``` +```output +cups is stopped 3 -[root@localhost examples]# service sshd status; echo $? +``` +```command +service sshd status; echo $? +``` +```output openssh-daemon (pid 3794) is running... 0 -[root@localhost examples]# service crond status; echo $? +``` +```command +service crond status; echo $? +``` +```output crond (pid 3929) is running... 0 ``` diff --git a/examples/example-snippets/promise-patterns/example_find_mac_addr.markdown b/examples/example-snippets/promise-patterns/example_find_mac_addr.markdown index 47fc72f7f..e5d494ab9 100644 --- a/examples/example-snippets/promise-patterns/example_find_mac_addr.markdown +++ b/examples/example-snippets/promise-patterns/example_find_mac_addr.markdown @@ -75,10 +75,11 @@ This policy can be found in `/var/cfengine/masterfiles/example_find_mac_addr.cf` Example run: +```command +cf-agent -f example_find_mac_addr.cf ``` -# cf-agent -f example_find_mac_addr.cf +```output 2013-06-08T16:59:19-0700 notice: R: MAC address is a4:ba:db:d7:59:32 -# ``` While the above illustrates the flexiblity of CFEngine in diff --git a/examples/example-snippets/promise-patterns/example_install_package.markdown b/examples/example-snippets/promise-patterns/example_install_package.markdown index 7e0f8434d..6e7f7fb17 100644 --- a/examples/example-snippets/promise-patterns/example_install_package.markdown +++ b/examples/example-snippets/promise-patterns/example_install_package.markdown @@ -50,16 +50,24 @@ CFEngine downloads the necessary packages from the default repositories if they Example run: +```command +dpkg -r lynx ntp # remove packages so CFEngine has something to repair ``` -# dpkg -r lynx ntp # remove packages so CFEngine has something to repair +```output (Reading database ... 234887 files and directories currently installed.) Removing lynx ... Removing ntp ... * Stopping NTP server ntpd [ OK ] Processing triggers for ureadahead ... Processing triggers for man-db ... -# cf-agent -f install_packages.cf # install packages -# dpkg -l lynx ntp # show installed packages +``` +```command +cf-agent -f install_packages.cf # install packages +``` +```command +dpkg -l lynx ntp # show installed packages +``` +```output Desired=Unknown/Install/Remove/Purge/Hold | Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend |/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad) @@ -67,7 +75,6 @@ Desired=Unknown/Install/Remove/Purge/Hold +++-===============================-====================-====================-==================================================================== ii lynx 2.8.8dev.12-2ubuntu0 all Text-mode WWW Browser (transitional package) ii ntp 1:4.2.6.p3+dfsg-1ubu amd64 Network Time Protocol daemon and utility programs -# ``` There are examples in `/var/cfengine/share/doc/examples/` of installing packages using specific package managers: diff --git a/examples/example-snippets/promise-patterns/example_mount_nfs.markdown b/examples/example-snippets/promise-patterns/example_mount_nfs.markdown index 7371442e9..473463dca 100644 --- a/examples/example-snippets/promise-patterns/example_mount_nfs.markdown +++ b/examples/example-snippets/promise-patterns/example_mount_nfs.markdown @@ -46,14 +46,23 @@ Here is an example run. At start, the filesystem is not in /etc/fstab and is no Now we run CFEngine to mount the filesystem and add it to /etc/fstab: +```command +cf-agent -f example_mount_nfs.cf ``` -# cf-agent -f example_mount_nfs.cf +```output 2013-06-08T17:48:42-0700 error: Attempting abort because mount went into a retry loop. -# grep mnt /etc/fstab +``` +```command +grep mnt /etc/fstab +``` +```output fileserver:/home /mnt nfs rw -# df |grep mnt +``` +```command +df |grep mnt +``` +```output fileserver:/home 149912064 94414848 47882240 67% /mnt -# ``` Note: CFEngine errors out after it mounts the filesystem and updates diff --git a/examples/example-snippets/promise-patterns/example_process_kill.markdown b/examples/example-snippets/promise-patterns/example_process_kill.markdown index 09eb668fa..32a86a704 100644 --- a/examples/example-snippets/promise-patterns/example_process_kill.markdown +++ b/examples/example-snippets/promise-patterns/example_process_kill.markdown @@ -31,31 +31,43 @@ This policy can be found in `/var/cfengine/share/doc/examples/unit_process_kill. Example run: +```command +/bin/sleep 1000 & ``` -# /bin/sleep 1000 & +```output [1] 5370 -# cf-agent -f unit_process_kill.cf +``` +```command +cf-agent -f unit_process_kill.cf +``` +```output [1]+ Terminated /bin/sleep 1000 -# ``` Now let's do it again with inform mode turned on, and CFEngine will show the process table entry that matched the pattern we specified ("sleep"): +```command +/bin/sleep 1000 & ``` -# /bin/sleep 1000 & +```output [1] 5377 -# cf-agent -f unit_process_kill.cf -IK +``` +```command +cf-agent -f unit_process_kill.cf -IK +``` +```output 2013-06-08T16:30:06-0700 info: This agent is bootstrapped to '192.168.183.208' 2013-06-08T16:30:06-0700 info: Running full policy integrity checks 2013-06-08T16:30:06-0700 info: /process_kill/processes/'sleep': Signalled 'term' (15) to process 5377 (root 5377 3854 5377 0.0 0.0 11352 0 612 1 16:30 00:00:00 /bin/sleep 1000) [1]+ Terminated /bin/sleep 1000 -# ``` If we add the -v switch to turn on verbose mode, we see the /bin/ps command CFEngine used to dump the process table: +```command +cf-agent -f unit_process_kill.cf -Kv ``` -# cf-agent -f unit_process_kill.cf -Kv +```output ... 2013-06-08T16:38:20-0700 verbose: Observe process table with /bin/ps -eo user,pid,ppid,pgid,pcpu,pmem,vsz,ni,rss,nlwp,stime,time,args 2013-06-08T16:38:20-0700 verbose: Matched 'root 5474 3854 5474 0.0 0.0 11352 0 612 1 16:38 00:00:00 /bin/sleep 1000' diff --git a/examples/example-snippets/promise-patterns/example_process_restart.markdown b/examples/example-snippets/promise-patterns/example_process_restart.markdown index 7197bf246..907e14d9a 100644 --- a/examples/example-snippets/promise-patterns/example_process_restart.markdown +++ b/examples/example-snippets/promise-patterns/example_process_restart.markdown @@ -64,13 +64,16 @@ root 8008 1 0 18:18 ? 00:00:00 /var/cfengine/bin/cf-serverd And again, in Inform mode: +```command +kill 8008 ``` -# kill 8008 -# cf-agent -f unit_process_restart.cf -I +```command +cf-agent -f unit_process_restart.cf -I +``` +```output 2013-06-08T18:19:51-0700 info: This agent is bootstrapped to '192.168.183.208' 2013-06-08T18:19:51-0700 info: Running full policy integrity checks 2013-06-08T18:19:51-0700 info: /process_restart/processes/'$(component)': Making a one-time restart promise for 'cf-serverd' 2013-06-08T18:19:51-0700 info: Executing 'no timeout' ... '/var/cfengine/bin/cf-serverd' 2013-06-08T18:19:52-0700 info: Completed execution of '/var/cfengine/bin/cf-serverd' -# ``` diff --git a/examples/example-snippets/promise-patterns/example_ssh_keys.markdown b/examples/example-snippets/promise-patterns/example_ssh_keys.markdown index 9a7d1519b..b7a5bb229 100644 --- a/examples/example-snippets/promise-patterns/example_ssh_keys.markdown +++ b/examples/example-snippets/promise-patterns/example_ssh_keys.markdown @@ -14,7 +14,8 @@ the [Masterfiles Policy Framework][Masterfiles Policy Framework]. The you do not have a `def.json` in the root of your masterfiles directory simply create it with the following content. -``` +```json +[file=def.json] { "classes": { "services_autorun": [ "any" ] @@ -57,22 +58,24 @@ root@host001:~# useradd kelly Then update the policy and run it: +```command +cf-agent -Kf update.cf; cf-agent -KI ``` -root@host001:~# cf-agent -Kf update.cf; cf-agent -KI - info: Installing cfe_internal_non_existing_package... - info: Created directory '/home/bob/.ssh/.' - info: Owner of '/home/bob/.ssh' was 0, setting to 1002 - info: Object '/home/bob/.ssh' had permission 0755, changed it to 0700 - info: Copying from '192.168.56.2:/srv/ssh_authorized_keys/bob' - info: Owner of '/home/bob/.ssh/authorized_keys' was 0, setting to 1002 - info: Created directory '/home/frank/.ssh/.' - info: Owner of '/home/frank/.ssh' was 0, setting to 1003 - info: Object '/home/frank/.ssh' had permission 0755, changed it to 0700 - info: Copying from '192.168.56.2:/srv/ssh_authorized_keys/frank' - info: Owner of '/home/frank/.ssh/authorized_keys' was 0, setting to 1003 - info: Created directory '/home/kelly/.ssh/.' - info: Owner of '/home/kelly/.ssh' was 0, setting to 1004 - info: Object '/home/kelly/.ssh' had permission 0755, changed it to 0700 - info: Copying from '192.168.56.2:/srv/ssh_authorized_keys/kelly' - info: Owner of '/home/kelly/.ssh/authorized_keys' was 0, setting to 1004 +```output +info: Installing cfe_internal_non_existing_package... +info: Created directory '/home/bob/.ssh/.' +info: Owner of '/home/bob/.ssh' was 0, setting to 1002 +info: Object '/home/bob/.ssh' had permission 0755, changed it to 0700 +info: Copying from '192.168.56.2:/srv/ssh_authorized_keys/bob' +info: Owner of '/home/bob/.ssh/authorized_keys' was 0, setting to 1002 +info: Created directory '/home/frank/.ssh/.' +info: Owner of '/home/frank/.ssh' was 0, setting to 1003 +info: Object '/home/frank/.ssh' had permission 0755, changed it to 0700 +info: Copying from '192.168.56.2:/srv/ssh_authorized_keys/frank' +info: Owner of '/home/frank/.ssh/authorized_keys' was 0, setting to 1003 +info: Created directory '/home/kelly/.ssh/.' +info: Owner of '/home/kelly/.ssh' was 0, setting to 1004 +info: Object '/home/kelly/.ssh' had permission 0755, changed it to 0700 +info: Copying from '192.168.56.2:/srv/ssh_authorized_keys/kelly' +info: Owner of '/home/kelly/.ssh/authorized_keys' was 0, setting to 1004 ``` diff --git a/examples/example-snippets/promise-patterns/example_sudoers.markdown b/examples/example-snippets/promise-patterns/example_sudoers.markdown index 9a04b61f6..7d300ee6b 100644 --- a/examples/example-snippets/promise-patterns/example_sudoers.markdown +++ b/examples/example-snippets/promise-patterns/example_sudoers.markdown @@ -41,13 +41,14 @@ We recommend editing the master sudoers file using `visudo` or a similar tool. I Example run: +```command +cf-agent -f temp.cf -KI ``` -# cf-agent -f temp.cf -KI +```output 2013-06-08T19:13:21-0700 info: This agent is bootstrapped to '192.168.183.208' 2013-06-08T19:13:22-0700 info: Running full policy integrity checks 2013-06-08T19:13:23-0700 info: Copying from '192.168.183.208:/var/cfengine/masterfiles/sudoers' 2013-06-08T19:13:23-0700 info: /sudoers/files/'/tmp/sudoers': Object '/tmp/sudoers' had permission 0600, changed it to 0440 -# ``` For reference we include an example of a simple sudoers file: diff --git a/examples/tutorials/custom_inventory.markdown b/examples/tutorials/custom_inventory.markdown index 131bbe1fc..eab373430 100644 --- a/examples/tutorials/custom_inventory.markdown +++ b/examples/tutorials/custom_inventory.markdown @@ -47,6 +47,7 @@ Create `/var/cfengine/masterfiles/services/tutorials/inventory/owner.cf` with th following content: ```cf3 +[file=owner.cf] bundle agent tutorials_inventory_owner # @brief Inventory Owner information # @description Inventory owner information from `/vagrant/inventory_owner.csv`. @@ -114,7 +115,6 @@ You can use your favorite JSON validate. I like [`jq`][jq-project], plus it's ha ```console [root@hub ~]# wget -q -O /var/cfengine/bin/jq https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64 [root@hub ~]# chmod +x /var/cfengine/bin/jq -[root@hub ~]# ``` Once it's installed, we can use it to validate our JSON. @@ -141,8 +141,10 @@ You can also perform a manual policy run and check that the correct owner is dis **Manual Policy Run:** -```console -[root@hub ~]# cf-agent -KIf /var/cfengine/masterfiles/promises.cf -b tutorials_inventory_owner +```command +cf-agent -KIf /var/cfengine/masterfiles/promises.cf -b tutorials_inventory_owner +``` +```output info: Using command line specified bundlesequence R: tutorials_inventory_owner: Discovered Owner='Operations Team ' ``` @@ -178,8 +180,10 @@ Let's query the API from the hub itself, and use [`jq`][jq-project] to make it e Now that we have jq in place, let's query the Inventory API to see what inventory attributes are available. -```console -[root@hub ~]# curl -s -k --user admin:admin -X GET https://localhost/api/inventory/attributes-dictionary | jq '.[].attribute_name' +```command +curl -s -k --user admin:admin -X GET https://localhost/api/inventory/attributes-dictionary | jq '.[].attribute_name' +``` +```output "Architecture" "BIOS vendor" "BIOS version" @@ -223,8 +227,10 @@ Yes, we can see our attribute `Owner` is reported. Now, let's query the Inventory API to see what Owners are reported. -```console -[root@hub ~]# curl -s -k --user admin:admin -X POST -H 'content-type: application/json' -d '{ "select": [ "Host name", "Owner" ]}' https://localhost/api/inventory | jq '.data[].rows[]' +```command +curl -s -k --user admin:admin -X POST -H 'content-type: application/json' -d '{ "select": [ "Host name", "Owner" ]}' https://localhost/api/inventory | jq '.data[].rows[]' +``` +```output [ "host001.example.com", "Development " diff --git a/examples/tutorials/distribute-files-from-a-central-location.markdown b/examples/tutorials/distribute-files-from-a-central-location.markdown index e93239b56..ef3e82f0c 100644 --- a/examples/tutorials/distribute-files-from-a-central-location.markdown +++ b/examples/tutorials/distribute-files-from-a-central-location.markdown @@ -18,11 +18,14 @@ perform the following instructions: CFEngine stores the master copy of all policy in the `/var/cfengine/masterfiles` directory. Ensure that you are working with the latest version of your `masterfiles`. +```command +git clone url +``` - git clone url or - - git pull origin master +```command +git pull origin master +``` ## Make policy changes @@ -43,7 +46,8 @@ These variables provide path definitions for storing and deploying patches. Add the following variable information to the `masterfiles/def.cf` file: -``` +```cf +[file=def.cf] "dir_patch_store" string => "/storage/patches", comment => "Define patch files source location", @@ -71,6 +75,7 @@ promise type in a `server` bundle. The default access rules defined by the MPF ( There is no need to modify the vendored policy, instead define your own server bundle. For our example, add the following to `services/main.cf`: ```cf3 +[file=main.cf] bundle server my_access_rules { access: @@ -90,6 +95,7 @@ use is a good idea. This information is stored in a custom library. Create a custom library called `lib/custom/files.cf`. Add the following content: ```cf3 +[file=files.cf] bundle agent sync_from_policyserver(source_path, dest_path) # @brief Sync files from the policy server to the agent # @@ -115,6 +121,7 @@ policy by services. Create `services/patching.cf` with the following content: ```cf3 +[file=patching.cf] # Patching Policy bundle agent patching @@ -212,25 +219,34 @@ This tracker allows you to see how the policy reacts as it is activated on your ### Deploy changes (Enterprise and Community Users) Always inspect what you expect. `git status` shows the status of your current branch. +```command +git status +``` - git status - -Inspect the changes contained in each file. Once satisfied, add them to Git's commit staging area. +Inspect the changes contained in each file. +```command +git diff file +``` - git diff file - git add file +Once satisfied, add them to Git's commit staging area. +```command +git add file +``` Iterate over using git **diff**, **add**, and **status** until all of the changes that you expected are listed as **Changes to be committed**. Check the status once more before you commit the changes. - - git status +```command +git status +``` Commit the changes to your local repository. - - git commit +```command +git commit +``` Push the changes to the central repository so they can be pulled down to your policy server for distribution. - - git push origin master +```command +git push origin master +``` diff --git a/examples/tutorials/files-tutorial.markdown b/examples/tutorials/files-tutorial.markdown index 07bdae445..16d903041 100644 --- a/examples/tutorials/files-tutorial.markdown +++ b/examples/tutorials/files-tutorial.markdown @@ -29,6 +29,7 @@ Note: The following workflow assumes the directory /home/user already exists. If 1. Create a file /var/cfengine/masterfiles/file_test.cf that includes the following text: ```cf3 + [file=file_test.cf] bundle agent list_file { @@ -43,49 +44,50 @@ Note: The following workflow assumes the directory /home/user already exists. If 2. Run the following command to remove any existing test file at the location we wish to use for testing this example: - ```console + ```command rm /home/user/test_plain.txt ``` 3. Test to ensure there is no file /home/user/test_plain.txt, using the following command (the expected result is that there should be no file listed at the location /home/user/test_plain.txt): - ```console + ```command ls /home/user/test_plain.txt ``` 5. Run the following command to instruct CFEngine to see if the file exists (the expected result is that no report will be generated (because the file does not exist): - ```console + ```command /var/cfengine/bin/cf-agent --no-lock --file /var/cfengine/masterfiles/file_test.cf --bundlesequence list_file ``` 6. Create a file for testing the example, using the following command: - ```console + ```command touch /home/user/test_plain.txt ``` 7. Run the following command to instruct CFEngine to search for the file (the expected result is that a report will be generated, because the file exists): - ```console + ```command /var/cfengine/bin/cf-agent --no-lock --file /var/cfengine/masterfiles/file_test.cf --bundlesequence list_file ``` 8. Double check the file exists, using the following command (the expected result is that there will be a file listed at the location /home/user/test_plain.txt): - ```console + ```command ls /home/user/test_plain.txt ``` 9. Run the following command to remove the file: - ```console + ```command rm /home/user/test_plain.txt ``` ## Create a File ```cf3 + [file=file_create.cf] bundle agent testbundle { @@ -125,7 +127,7 @@ body perms system mode => "0640"; } ``` - +```console ls /home/user/test_plain.txt /var/cfengine/bin/cf-agent --no-lock --file ./file_test.cf --bundlesequence list_file,testbundle,list_file_2 @@ -135,11 +137,12 @@ ls /home/user/test_plain.txt ls /home/user/test_plain.txt rm /home/user/test_plain.txt - +``` ## Delete a File ```cf3 +[file=file_delete.cf] body common control { inputs => { @@ -195,35 +198,27 @@ body perms system mode => "0640"; } ``` - +```bash rm /home/user/test_plain.txt - ls /home/user/test_plain.txt - /var/cfengine/bin/cf-agent --no-lock --file ./file_test.cf --bundlesequence list_file,testbundle,list_file_2 - /var/cfengine/bin/cf-agent --no-lock --file ./file_test.cf --bundlesequence list_file,list_file_2 - /var/cfengine/bin/cf-agent --no-lock --file ./file_test.cf --bundlesequence list_file,test_delete,list_file_2 - ls /home/user/test_plain.txt - rm /home/user/test_plain.txt - +``` (last command will throw an error because the file doesn't exist!) ## Modify a File - +```bash rm /home/user/test_plain.txt - ls /home/user/test_plain.txt - /var/cfengine/bin/cf-agent --no-lock --file ./file_test.cf --bundlesequence list_file,testbundle,list_file_2 - /var/cfengine/bin/cf-agent --no-lock --file ./file_test.cf --bundlesequence list_file,list_file_2 - +``` ```cf3 +[file=file_modify.cf] body common control { inputs => { @@ -332,16 +327,16 @@ body perms system ``` - +```bash /var/cfengine/bin/cf-agent --no-lock --file ./file_test.cf --bundlesequence list_file,test_delete,list_file_2 - ls /home/user/test_plain.txt - rm /home/user/test_plain.txt +``` ## Copy a file and edit its text ```cf3 +[file=file_copy.cf] body common control { inputs => { @@ -521,6 +516,6 @@ body perms system } ``` -```console +```command /var/cfengine/bin/cf-agent --no-lock --file ./file_test.cf --bundlesequence test_delete,do_files_exist,testbundle,outer_bundle_1,copy_a_file,do_files_exist_2,list_file_1,outer_bundle_2,list_file_2 ``` diff --git a/examples/tutorials/high-availability/installation-guide.markdown b/examples/tutorials/high-availability/installation-guide.markdown index eeb90ef0f..8c761a88b 100644 --- a/examples/tutorials/high-availability/installation-guide.markdown +++ b/examples/tutorials/high-availability/installation-guide.markdown @@ -56,7 +56,7 @@ Detailed network configuration is shown on the picture below: **On both nodes:** - ``` + ```command yum -y install pcs pacemaker cman fence-agents ``` @@ -85,20 +85,20 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 4. Authenticate hacluster user for each node of the cluster. Run the command below **on the node1**: - ``` + ```command pcs cluster auth node1 node2 -u hacluster ``` After entering password, you should see a message similar to one below: - ``` + ```output node1: Authorized node2: Authorized ``` 5. Create the cluster by running the following command **on the node1**: - ``` + ```command pcs cluster setup --name cfcluster node1 node2 ``` @@ -107,7 +107,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 6. Give the cluster time to settle (cca 1 minute) and then start the cluster by running the following command **on the node1**: - ``` + ```command pcs cluster start --all ``` @@ -116,7 +116,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 7. At this point the cluster should be up and running. Running ```pcs status``` should print something similar to the output below. - ``` + ```output Cluster name: cfcluster WARNING: no stonith devices and stonith-enabled is not false Stack: cman @@ -159,13 +159,13 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 10. Verify that the cfvirtip resource is properly configured and running. - ``` + ```command pcs status ``` should give something like this: - ``` + ```output Cluster name: cfcluster Last updated: Tue Jul 7 09:29:10 2015 Last change: Fri Jul 3 08:41:24 2015 @@ -188,7 +188,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 1. Install the CFEngine hub package **on both node1 and node2**. 2. Make sure CFEngine is not running (**on both node1 and node2**): - ``` + ```command service cfengine3 stop ``` @@ -232,7 +232,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 4. Do an initial sync of PostgreSQL: 1. Start PostgreSQL **on node1**: - ``` + ```command pushd /tmp; su cfpostgres -c "/var/cfengine/bin/pg_ctl -w -D /var/cfengine/state/pg/data -l /var/log/postgresql.log start"; popd ``` @@ -258,33 +258,33 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 5. Start PostgreSQL on the **node2** by running the following command: - ``` + ```command pushd /tmp; su cfpostgres -c "/var/cfengine/bin/pg_ctl -D /var/cfengine/state/pg/data -l /var/log/postgresql.log start"; popd ``` 6. Check that PostgreSQL replication is setup and working properly: 1. The **node2** should report it is in the recovery mode: - ``` + ```command /var/cfengine/bin/psql -x cfdb -c "SELECT pg_is_in_recovery();" ``` should return: - ``` + ```output -[ RECORD 1 ]-----+-- pg_is_in_recovery | t ``` 2. The **node1** should report it is replicating to node2: - ``` + ```command /var/cfengine/bin/psql -x cfdb -c "SELECT * FROM pg_stat_replication;" ``` should return something like this: - ``` + ```output -[ RECORD 1 ]----+------------------------------ pid | 11401 usesysid | 10 @@ -309,7 +309,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 7. Stop PostgreSQL **on both nodes**: - ``` + ```command pushd /tmp; su cfpostgres -c "/var/cfengine/bin/pg_ctl -D /var/cfengine/state/pg/data -l /var/log/postgresql.log stop"; popd ``` @@ -354,7 +354,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 3. Configure PostgreSQL to work in Master/Slave (active/standby) mode (**on node1**). - ``` + ```command pcs resource master mscfpgsql cfpgsql master-max=1 master-node-max=1 clone-max=2 clone-node-max=1 notify=true ``` @@ -370,19 +370,19 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 5. Enable and start the new resource now that it is fully configured (**on node1**). - ``` + ```command pcs resource enable mscfpgsql --wait=30 ``` 6. Verify that the constraints configuration is correct. - ``` + ```command pcs constraint ``` should give: - ``` + ```output Location Constraints: Resource: mscfpgsql Enabled on: node1 (score:INFINITY) (role: Master) @@ -395,13 +395,13 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 7. Verify that the cluster is now fully setup and running. - ``` + ```command crm_mon -Afr1 ``` should give something like: - ``` + ```output Stack: cman Current DC: node1 (version 1.1.18-3.el6-bfe4e80420) - partition with quorum Last updated: Tue Oct 16 14:19:37 2018 @@ -466,7 +466,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri Bootstrap the **node1** to itself and make sure the initial policy (`promises.cf`) evaluation is skipped: - ``` + ```command cf-agent --bootstrap 192.168.100.10 --skip-bootstrap-policy-run ``` @@ -480,7 +480,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 4. Stop CFEngine **on both nodes**. - ``` + ```command service cfengine3 stop ``` @@ -506,7 +506,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri The `@NODE1_PKSHA@` and `@NODE2_PKSHA@` strings are placeholders for the host key hashes of the nodes. Replace the placeholders with real values obtained by (on any node): - ``` + ```command cf-key -s ``` @@ -515,7 +515,8 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 6. **On both nodes,** add the following class definition to the */var/cfengine/masterfiles/def.json* file to enable HA: - ``` + ```json + [file=def.json] { "classes": { "enable_cfengine_enterprise_hub_ha": [ "any::" ] @@ -528,7 +529,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 8. Start CFEngine **on both nodes**. - ``` + ```command service cfengine3 start ``` @@ -556,12 +557,13 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri Running the following command **on node1**: - ``` + ```command /var/cfengine/bin/psql cfdb -c "SELECT * FROM pg_stat_replication;" ``` Should give: - ``` + + ```output pid | usesysid | usename | application_name | client_addr | client_hostname | client_port | backend_start | state | sent_location | write_location | flush_location | replay_location | sync_priority | sync_state ------+----------+------------+------------------+----------------+-----------------+-------------+-------------------------------+-----------+---------------+----------------+----------------+-----------------+---------------+------------ 9252 | 10 | cfpostgres | node2 | 192.168.100.11 | | 58919 | 2015-08-24 07:14:45.925341+00 | streaming | 0/2A7034D0 | 0/2A7034D0 | 0/2A7034D0 | 0/2A7034D0 | 0 | async @@ -573,8 +575,10 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 6. Modify HA JSON configuration file to contain information about the node3 (see CFEngine configuration, step 2). You should have configuration similar to one below: + ```command + cat /var/cfengine/masterfiles/cfe_internal/enterprise/ha/ha_info.json ``` - [root@node3 masterfiles]# cat /var/cfengine/masterfiles/cfe_internal/enterprise/ha/ha_info.json + ```output { "192.168.100.10": { @@ -626,8 +630,10 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 2. If ```crm_mon -Afr1``` is printing errors similar to the below - ``` - [root@node1]# pcs status + ```command + pcs status + ``` + ```output Cluster name: cfcluster Last updated: Tue Jul 7 11:27:23 2015 Last change: Tue Jul 7 11:02:40 2015 @@ -653,11 +659,16 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri you can try to clear the errors by running ```pcs resource cleanup ```. This should clean errors for the appropriate resource and make the cluster restart it. - ``` - [root@node1 vagrant]# pcs resource cleanup cfpgsql - Resource: cfpgsql successfully cleaned up - - [root@node1 vagrant]# pcs status + ```command + pcs resource cleanup cfpgsql + ``` + ```output + Resource: cfpgsql successfully cleaned up + ``` + ```command + pcs status + ``` + ```output Cluster name: cfcluster Last updated: Tue Jul 7 11:29:36 2015 Last change: Tue Jul 7 11:29:08 2015 @@ -681,7 +692,9 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 3. After cluster crash make sure to always start the node that should be active first, and then the one that should be passive. If the cluster is not running on the given node after restart you can enable it by running the following command: - ``` - [root@node2]# pcs cluster start - Starting Cluster... - ``` + ```command + pcs cluster start + ``` + ```output + Starting Cluster... + ``` diff --git a/examples/tutorials/installing-cfengine-enterprise-agent.markdown b/examples/tutorials/installing-cfengine-enterprise-agent.markdown index 16f46bc54..3b72d8762 100644 --- a/examples/tutorials/installing-cfengine-enterprise-agent.markdown +++ b/examples/tutorials/installing-cfengine-enterprise-agent.markdown @@ -24,14 +24,14 @@ The installation script below has been tested on Red Hat, CentOS, SUSE, Debian a 1. Download and Install CFEngine Host Run the following command to download and automatically install CFEngine on a 32-bit or 64-bit Linux machine (the script will detect correct flavor and architecture). -```console +```command wget https://s3.amazonaws.com/cfengine.packages/quick-install-cfengine-enterprise.sh && sudo bash ./quick-install-cfengine-enterprise.sh agent ``` 2. Bootstrap the Host Once installed, the host needs to bootstrap to your CFEngine policy server. -```console +```command sudo /var/cfengine/bin/cf-agent --bootstrap ``` If you encounter any issue, please make sure the host is on the same domain/subnet as CFEngine policy server will only allow connection from these trusted sources as default configuration. @@ -41,7 +41,7 @@ The CFEngine host is installed and ready. That was easy, wasn't it? If you would like to see what version of CFEngine you are running, type: -```console +```command /var/cfengine/bin/cf-promises --version ``` diff --git a/examples/tutorials/integrating-alerts-with-pager-duty.markdown b/examples/tutorials/integrating-alerts-with-pager-duty.markdown index 423bb37d1..b24599b84 100644 --- a/examples/tutorials/integrating-alerts-with-pager-duty.markdown +++ b/examples/tutorials/integrating-alerts-with-pager-duty.markdown @@ -20,8 +20,8 @@ We will create a policy that ensures file integrity, and have CFEngine notify Pa Run the following command on your policy server to create the file we want to manage. -```console -# touch /tmp/file-integrity +```command +touch /tmp/file-integrity ``` ## Create a new policy to manage the file @@ -29,6 +29,7 @@ Run the following command on your policy server to create the file we want to ma Insert the following policy into `/tmp/file_example.cf` ```cf3 +[file=file_example.cf] bundle agent file_integrity { files: @@ -55,16 +56,16 @@ Normally, to ensure your policy file is put into action, you would need to follo Normally, to ensure your policy file is put into action, you would need to follow these three steps: - ```console - # mv /tmp/file_example.cf /var/cfengine/masterfiles/ + ```command + mv /tmp/file_example.cf /var/cfengine/masterfiles/ ``` 2. Modify `promises.cf` to include your policy Unless you use version control system, or has a non-standard CFEngine setup, modify your `promises.cf` file by adding the new bundlename and policy-file so it will be picked up by CFEngine to be included in all future runs. - ```console - # vi /var/cfengine/masterfiles/promises.cf + ```command + vi /var/cfengine/masterfiles/promises.cf ``` a) Under the body common control, add `file_integrity` to your *bundlesequence* @@ -121,8 +122,8 @@ Now we have a made a policy to monitor the `/tmp/file-integrity` file. Whenever 1. Make a change to the `/tmp/file_integrity` file on your policy server: - ```console - # echo "Hello World!!" > /tmp/file_integrity + ```command + echo "Hello World!!" > /tmp/file_integrity ``` The next time CFEngine runs, it will detect the change and send an notification to PagerDuty. Go to PagerDuty and wait for an alert to be triggered. diff --git a/examples/tutorials/integrating-with-sumo-logic.markdown b/examples/tutorials/integrating-with-sumo-logic.markdown index 9328629f1..508e033f3 100644 --- a/examples/tutorials/integrating-with-sumo-logic.markdown +++ b/examples/tutorials/integrating-with-sumo-logic.markdown @@ -13,13 +13,13 @@ In this How To we will show a simple integrate with [Sumo Logic](http://www.sumo -# How it works +## How it works Whenever there is a policy update or a new policy is detected by CFEngine, a special variable called "`sys.last_policy_update`" will be updated with current timestamp. We will store this timestamp in a file, and then via api upload the file to Sumo Logic. -# Create the CFEngine policy file +## Create the CFEngine policy file In this section we will explain the most important parts of our policy file. @@ -85,51 +85,65 @@ That's it! You can copy and paste the whole policy file at the bottom of this pa Save the policy file you make as `/tmp/sumologic_policy_update.cf` -# Ensure the policy always runs +## Ensure the policy always runs Normally, to ensure your policy file is put into action, you would need to follow these two steps: 1. Move the policy file to your masterfiles directory: -```console -# mv /tmp/sumo.cf /var/cfengine/masterfiles/ -``` + ```command + mv /tmp/sumo.cf /var/cfengine/masterfiles/ + ``` 2. Modify `promises.cf` to include your policy Unless you use version control system, or has a non-standard CFEngine setup, modify your `promises.cf` file by adding the new bundle name and policy-file so it will be picked up by CFEngine and be part of all it future runs. -```console -# vi /var/cfengine/masterfiles/promises.cf -``` + ```command + vi /var/cfengine/masterfiles/promises.cf + ``` Under the body common control, add `sumo_logic_policy_update` to your bundle sequence. -![integrating-with-sumo-logic_bundle_sequence.png](integrating-with-sumo-logic_bundle_sequence.png) +```cf3 +body common control + +{ + bundlesequence = { + # Common bundle first (Best Practice) + sumo_logic_policy_update, + inventory_control, + ... +``` Under body common control, add /sumologic\_policy\_update.cf/ to your inputs section. -![integrating-with-sumo-logic_inputs1.png](integrating-with-sumo-logic_inputs1.png) +```cf3 +inputs => { + # File definition for global variables and classes + "sumologic_policy_update.cf", + ... +``` That's all. -# Test it! +## Test it! To test it, we need to make a change to any CFEngine policy, and then go to Sumo Logic to see if there is a new timestamp reported. * Make a change to any policy file, for examle `promises.cf`: -```console -# vi /var/cfengine/masterfiles/promises.cf +```command +vi /var/cfengine/masterfiles/promises.cf ``` Add a comment and close the file. * Check if timestamp has been updated -```console -# cat /tmp/CFEngine_policy_updated +```command +cat /tmp/CFEngine_policy_updated ``` * Check with Sumo Logic @@ -144,6 +158,8 @@ As we can see above CFEngine detected a change on `Thursday Oct 2 at 01:16:42` a The policy as found in `sumologic_policy_update.cf`. +```cf3 +[file=sumo_logic_policy_update.cf] bundle agent sumo_logic_policy_update { vars: @@ -198,3 +214,4 @@ The policy as found in `sumologic_policy_update.cf`. { empty_file_before_editing => "true"; } +``` diff --git a/examples/tutorials/integrating-with-sumo-logic_bundle_sequence.png b/examples/tutorials/integrating-with-sumo-logic_bundle_sequence.png deleted file mode 100644 index 6c1510d5c..000000000 Binary files a/examples/tutorials/integrating-with-sumo-logic_bundle_sequence.png and /dev/null differ diff --git a/examples/tutorials/integrating-with-sumo-logic_inputs1.png b/examples/tutorials/integrating-with-sumo-logic_inputs1.png deleted file mode 100644 index 0b350c535..000000000 Binary files a/examples/tutorials/integrating-with-sumo-logic_inputs1.png and /dev/null differ diff --git a/examples/tutorials/integrating-with-sumo-logic_sumo.png b/examples/tutorials/integrating-with-sumo-logic_sumo.png index 9b09d6332..d0df63b20 100644 Binary files a/examples/tutorials/integrating-with-sumo-logic_sumo.png and b/examples/tutorials/integrating-with-sumo-logic_sumo.png differ diff --git a/examples/tutorials/json-yaml-support-in-cfengine.markdown b/examples/tutorials/json-yaml-support-in-cfengine.markdown index 3adf95f59..5d7faf689 100644 --- a/examples/tutorials/json-yaml-support-in-cfengine.markdown +++ b/examples/tutorials/json-yaml-support-in-cfengine.markdown @@ -77,6 +77,7 @@ expressions or class names. Easy, right? ```cf3 +[file=json_example.cf] body common control { bundlesequence => { "run" }; diff --git a/examples/tutorials/manage-local-users.markdown b/examples/tutorials/manage-local-users.markdown index 18b15d737..ce8d4f1e4 100644 --- a/examples/tutorials/manage-local-users.markdown +++ b/examples/tutorials/manage-local-users.markdown @@ -15,8 +15,8 @@ as part of creating the user. Create the files `id_rsa` and `id_rsa.pub` in `/tmp`. -```console -# touch /tmp/id_rsa /tmp/id_rsa.pub +```command +touch /tmp/id_rsa /tmp/id_rsa.pub ``` Create user group security and webadmin. @@ -31,6 +31,7 @@ Create user group security and webadmin. Create a file `/tmp/users.cf` with the following content: ```cf3 +[file=users.cf] body common control { inputs => { "$(sys.libdir)/stdlib.cf" }; @@ -65,30 +66,30 @@ bundle agent setup_home_dir(user) Run CFEngine: -```console -# /var/cfengine/bin/cf-agent -fK /tmp/users.cf +```command +/var/cfengine/bin/cf-agent -fK /tmp/users.cf ``` Verify the result: Have users have been created? -```console -# grep -P "adam|eva" /etc/passwd +```command +grep -P "adam|eva" /etc/passwd ``` Congratulations! You should now see the users adam and eva listed. Verify the result: Have users home directory have been created? -```console -# ls /home | grep -P "adam|eva" +```command +ls /home | grep -P "adam|eva" ``` Congratulations! You should now see adam and eva listed. Verify the result: Have users have been added to the correct groups? -```console -# grep -P "adam|eva" /etc/group +```command +grep -P "adam|eva" /etc/group ``` Congratulations! You should now see adam and eva added to the groups security @@ -98,16 +99,16 @@ you must make sure the groups exists. Verify the result: Have ssh-keys have been copied from `/tmp` to user's `~/.ssh` directory? -```console -# ls /home/adam/.ssh /home/eva/.ssh +```command +ls /home/adam/.ssh /home/eva/.ssh ``` Congratulations! You should now see the files `id_rsa` and `id_rsa.pub`. Ps. If you would like play around with the policy, delete the users after each run with the command -```console -# deluser -r username +```command +deluser -r username ``` Mission accomplished! diff --git a/examples/tutorials/manage-ntp.markdown b/examples/tutorials/manage-ntp.markdown index 2b8ee4554..93639f5d4 100644 --- a/examples/tutorials/manage-ntp.markdown +++ b/examples/tutorials/manage-ntp.markdown @@ -13,6 +13,7 @@ Note: For simplicity, in this tutorial we will work directly on top of the Maste ```cf3 +[file=ntp.cf] bundle agent ntp { vars: @@ -99,6 +100,7 @@ classes => results("bundle", "ntp_package_"); On your hub create `services/ntp.cf` inside *masterfiles* with the following content: ```cf3 +[file=ntp.cf] bundle agent ntp { vars: @@ -134,8 +136,10 @@ Now, we need to make sure the agent knows it should use this policy file and bun Validate it. -```console -[root@hub masterfiles]# python -m json.tool < def.json +```command +python -m json.tool < def.json +``` +```output { "inputs": [ "services/ntp.cf" @@ -150,23 +154,23 @@ Validate it. Force a policy update. Remember, CFEngine is running in the background, so it's possible that by the time you force a policy update and run the agent may have already done it and your output may differ. -``` +```command cf-agent -KIf update.cf ``` In the output, you should see something like: -``` +```output info: Updated '/var/cfengine/inputs/services/ntp.cf' from source '/var/cfengine/masterfiles/services/ntp.cf' on 'localhost' ``` Now force a policy run. -```console -[root@hub masterfiles]# cf-agent -KI +```command +cf-agent -KI ``` -``` +```output info: Successfully installed package 'ntp' ``` @@ -179,6 +183,7 @@ Now we will extend the policy to ensure that the NTP service is running. Now that the NTP service has been installed on the system, we need to make sure that it is running. ```cf3 +[file=ntp.cf] bundle agent ntp { vars: @@ -479,11 +484,16 @@ Now that we have dissected the policy, let's go ahead and give it a whirl. ### Modify and run the policy -```console -[root@hub masterfiles]# cf-agent -KIf update.cf; - info: Copied file '/var/cfengine/masterfiles/services/ntp.cf' to '/var/cfengine/inputs/services/ntp.cf.cfnew' (mode '600') - -[root@hub masterfiles]# cf-agent -KI +```command +cf-agent -KIf update.cf; +``` +```output +info: Copied file '/var/cfengine/masterfiles/services/ntp.cf' to '/var/cfengine/inputs/services/ntp.cf.cfnew' (mode '600') +``` +```command +cf-agent -KI +``` +```output info: Updated rendering of '/etc/ntp.conf' from mustache template 'inline' info: files promise '/etc/ntp.conf' repaired info: Executing 'no timeout' ... '/etc/init.d/ntpd restart' @@ -493,8 +503,10 @@ R: NTP service restarted after configuration change More interestingly, if you examine the configuration file `/etc/ntp.conf`, you will notice that it has been updated with the time `server`(s) and `driftfile` you had specified in the policy, for that specific operating system environment. This is the configuration that the NTP service has been restarted with. -```console -[root@hub masterfiles]# grep -P "^(driftfile|server)" /etc/ntp.conf +```command +grep -P "^(driftfile|server)" /etc/ntp.conf +``` +```output driftfile /var/lib/ntp/drift server time.nist.gov iburst ``` @@ -509,6 +521,7 @@ CFEngine offers out-of-the-box support for reading and writing JSON data structu {% raw %} ```cf3 +[file=ntp.cf] bundle agent ntp { vars: @@ -633,12 +646,15 @@ Notice two promises were introduced, one setting `driftfile` to the value of `$( First modify `services/ntp.cf` as shown previously (don't forget to check syntax with `cf-promises` after modification), then run the policy. -```console -[root@hub masterfiles]# cf-agent -KIf update.cf - info: Copied file '/var/cfengine/masterfiles/services/ntp.cf' to '/var/cfengine/inputs/services/ntp.cf.cfnew' (mode '600') - info: Copied file '/var/cfengine/masterfiles/def.json' to '/var/cfengine/inputs/def.json.cfnew' (mode '600') - -[root@hub masterfiles]# cf-agent -KI +```command +cf-agent -KIf update.cf +``` +```output +info: Copied file '/var/cfengine/masterfiles/services/ntp.cf' to '/var/cfengine/inputs/services/ntp.cf.cfnew' (mode '600') +info: Copied file '/var/cfengine/masterfiles/def.json' to '/var/cfengine/inputs/def.json.cfnew' (mode '600') +``` +```command +cf-agent -KI ``` We do not expect to see the ntp configuration file modified or the service to be restarted since we have only instrumented the policy so far. @@ -647,6 +663,7 @@ Now, let's modify `def.json` (in the root of masterfiles) and define some differ Modify `def.json` so that it looks like this: ```json +[file=def.json] { "inputs": [ "services/ntp.cf" ], "vars": { @@ -665,8 +682,10 @@ Modify `def.json` so that it looks like this: Now, let's validate the JSON and force a policy run and inspect the result. -```console -[root@hub masterfiles]# python -m json.tool < def.json +```command +python -m json.tool < def.json +``` +```output { "inputs": [ "services/ntp.cf" @@ -688,8 +707,11 @@ Now, let's validate the JSON and force a policy run and inspect the result. } } } - -[root@hub masterfiles]# cf-agent -KI +``` +```command +cf-agent -KI +``` +```output info: Updated rendering of '/etc/ntp.conf' from mustache template 'inline' info: files promise '/etc/ntp.conf' repaired info: Executing 'no timeout' ... '/etc/init.d/ntpd restart' @@ -697,8 +719,11 @@ Now, let's validate the JSON and force a policy run and inspect the result. R: NTP service restarted after configuration change info: Can not acquire lock for 'ntp' package promise. Skipping promise evaluation info: Can not acquire lock for 'ntp' package promise. Skipping promise evaluation - -[root@hub masterfiles]# grep -P "^(driftfile|server)" /etc/ntp.conf +``` +```command +grep -P "^(driftfile|server)" /etc/ntp.conf +``` +```output driftfile /tmp/drift server 0.north-america.pool.ntp.org iburst server 1.north-america.pool.ntp.org iburst diff --git a/examples/tutorials/manage-packages.markdown b/examples/tutorials/manage-packages.markdown index 3f85ba466..afac780a1 100644 --- a/examples/tutorials/manage-packages.markdown +++ b/examples/tutorials/manage-packages.markdown @@ -5,7 +5,6 @@ published: true sorting: 3 --- - Package management is a critical task for any system administrator. In this tutorial we will show you how easy it is to install, manage and remove packages @@ -17,9 +16,10 @@ to make sure the latest version of OpenSSL is installed in all our hosts, we can use the packages promise type, like this: ```cf3 +[file=manage_packages.cf] body common control { - inputs => { "$(sys.libdir)/stdlib.cf"" }; + inputs => { "$(sys.libdir)/stdlib.cf" }; } bundle agent manage_packages @@ -42,12 +42,20 @@ want to use. Defaults can be set up by using the `package_module` common control attribute. When we run this on an CentOS 6 system, we can verify the openssl version before and after running the policy, and we get the following output: -```console -# yum list installed | grep openssl +```command +yum list installed | grep openssl +``` +```output openssl.x86_64 1.0.0-27.el6 @anaconda-CentOS-201303020151.x86_64/6.4 openssl-devel.x86_64 1.0.0-27.el6 @anaconda-CentOS-201303020151.x86_64/6.4 -# cf-agent -K ./manage_packages.cf" -# yum list installed | grep openssl +``` +```command +cf-agent -K ./manage_packages.cf +``` +```command +yum list installed | grep openssl +``` +```output openssl.x86_64 1.0.1e-42.el6 @base openssl-devel.x86_64 1.0.1e-42.el6 @base ``` @@ -56,10 +64,16 @@ Additionally, you may want to make sure certain packages are not installed on the system. On my CentOS 6 system, I can see that the telnet package is installed. -```console -# yum list installed | grep telnet +```command +yum list installed | grep telnet +``` +```output telnet.x86_64 1:0.17-48.el6 @base -# which telnet +``` +```command +which telnet +``` +```output /usr/bin/telnet ``` @@ -67,9 +81,10 @@ Making sure this package is removed from the system is easy. Let's add one more promise to our previous policy, this time using the absent policy: ```cf3 +[file=manage_packages.cf] body common control { - inputs => { "$(sys.libdir)/stdlib.cf"" }; + inputs => { "$(sys.libdir)/stdlib.cf" }; } bundle agent manage_packages @@ -97,9 +112,11 @@ to ensure that the openssl package is always updated to its latest version. We can now see the policy in action: ```console -# cf-agent -K ./manage_packages.cf" +# cf-agent -K ./manage_packages.cf # yum list installed | grep telnet # which telnet +``` +```output /usr/bin/which: no telnet in (/sbin:/bin:/usr/sbin:/usr/bin:/var/cfengine/bin) ``` @@ -120,6 +137,7 @@ Copy `manage_packages.cf` to `/var/cfengine/masterfiles/` on your policy hub. In declaration, and `manage_packages` to the bundlesequence declaration. ```json +[file=def.json] { "inputs": [ "manage_packages.cf" ], "vars": { @@ -130,8 +148,8 @@ declaration, and `manage_packages` to the bundlesequence declaration. Run `cf-promises` on the policy to verify that there are no errors. -``` -# cf-promises -cf /var/cfengine/masterfiles/promises.cf +```command +cf-promises -cf /var/cfengine/masterfiles/promises.cf ``` Wait a few minutes for the new policy to propagate and start taking effect in diff --git a/examples/tutorials/manage-processes-and-services.markdown b/examples/tutorials/manage-processes-and-services.markdown index d981d5076..010d8a956 100644 --- a/examples/tutorials/manage-processes-and-services.markdown +++ b/examples/tutorials/manage-processes-and-services.markdown @@ -18,6 +18,7 @@ Using CFEngine to ensure certain processes are running is extremely easy. Create a new file called `ensure_process.cf`: ```cf3 +[file=ensure_process.cf] body file control { inputs => { "$(sys.libdir)/stdlib.cf" }; @@ -58,22 +59,26 @@ to true. First, we verify that the ntpd process is not running: -```console -# ps axuww | grep ntp +```command +ps axuww | grep ntp ``` Then we run our CFEngine policy: -```console -# cf-agent -f ./ensure_process.cf +```command +cf-agent -f ./ensure_process.cf +``` +```output 2014-03-20T06:33:56+0000 notice: /default/main/commands/'/etc/init.d/ntp start'[0]: Q: "...init.d/ntp star": * Starting NTP server ntpd Q: "...init.d/ntp star": ...done. ``` Finally, we verify that ntpd is now running on the system: -```console -# ps axuww | grep ntp +```command +ps axuww | grep ntp +``` +```output ntp 5756 0.3 0.1 37696 2172 ? Ss 06:33 0:00 /usr/sbin/ntpd -p /var/run/ntpd.pid -g -u 104:110 ``` diff --git a/examples/tutorials/masterfiles_policy_framework_upgrade.markdown b/examples/tutorials/masterfiles_policy_framework_upgrade.markdown index 36d0aef25..f46820aea 100644 --- a/examples/tutorials/masterfiles_policy_framework_upgrade.markdown +++ b/examples/tutorials/masterfiles_policy_framework_upgrade.markdown @@ -26,7 +26,7 @@ From `/tmp/MPF-upgrade/integration/masterfiles`. Let's inspect what we expect. Is it the root of a policy set? `promises.cf` will be present if so. ```bash - export INTEGRATION_ROOT="/tmp/MPF-upgrade/integration" +export INTEGRATION_ROOT="/tmp/MPF-upgrade/integration" cd $INTEGRATION_ROOT/masterfiles if [ -e "promises.cf" ]; then echo "promise.cf exists, it's likely the root of a policy set" @@ -35,36 +35,31 @@ else fi ``` -Output: - -``` +```output promise.cf exists, it's likely the root of a policy set ``` Let's see what version of the MPF we are starting from by looking at `version` in `body common control` of `promises.cf`. -```bash +```command grep -P "\s+version\s+=>" $INTEGRATION_ROOT/masterfiles/promises.cf 2>&1 \ || echo "promises.cf is missing, $INTEGRATION_ROOT/masterfiles does not seem to be the root of a policy set" ``` -Output: -``` +```output version => "CFEngine Promises.cf 3.18.0"; ``` And finally, is it a git repository, what is the last commit? -```bash +```command git status \ || echo "$INTEGRATION_ROOT/masterfiles does not appear to be a git repository!" \ && git log -1 ``` -Output: - -``` +```output On branch master nothing to commit, working tree clean commit f4c0e120b0b45bcb9ede01ed8fb465f40b4b1e6f @@ -86,19 +81,17 @@ Date: Wed Jul 26 18:43:06 2023 -0500 By first removing everything we will easily be able so see which files are **new**, **changed**, **moved** or **removed** upstream. -```bash +```command rm -rf * ``` Check `git status` to see that all the files have been deleted and are not staged for commit. -```bash +```command git status ``` -Output: - -``` +```output On branch master Changes not staged for commit: (use "git add/rm ..." to update what will be committed) @@ -250,10 +243,7 @@ First, clone the desired version of the MPF source. export MPF_VERSION="3.21.2" git clone -b $MPF_VERSION https://github.com/cfengine/masterfiles $INTEGRATION_ROOT/masterfiles-source-$MPF_VERSION ``` - -Output: - -``` +```output Cloning into '/tmp/MPF-upgrade/integration/masterfiles-source-3.21.2'... Note: switching to 'f495603285f9bd90d5d36df4fec4870aeee751e8'. @@ -283,10 +273,7 @@ export EXPLICIT_VERSION=$MPF_VERSION make make install prefix=$INTEGRATION_ROOT/ ``` - -Output: - -``` +```output ./autogen.sh: Running determine-version.sh ... ./autogen.sh: Running determine-release.sh ... All tags pointing to current commit: @@ -437,9 +424,7 @@ cd $INTEGRATION_ROOT/masterfiles git status ``` -Output: - -``` +```output On branch master Changes not staged for commit: (use "git add/rm ..." to update what will be committed) @@ -532,13 +517,10 @@ git add templates/federated_reporting/transfer_distributed_cleanup_items.sh We can run git status again to see the current overview: -```bash +```command git status ``` - -Output: - -``` +```output On branch master Changes to be committed: (use "git restore --staged ..." to unstage) @@ -617,17 +599,16 @@ Changes not staged for commit: Next we want to bring back any of our custom files. Look through the **deleted** files, identify your custom files and restore them with `git checkout`. -```bash +```command git ls-files --deleted ``` - -Output: - - custom-2.cf - def.json - lib/deprecated-upstream.cf - services/autorun/custom-1.cf - services/custom-3.cf +```output +custom-2.cf +def.json +lib/deprecated-upstream.cf +services/autorun/custom-1.cf +services/custom-3.cf +``` Keeping your polices organized together helps to make this process easy. The custom policy files in the example policy set are `def.json`, `services/autorun/custom-1.cf`, `custom-2.cf`, and `services/custom-3.cf`. @@ -638,36 +619,33 @@ git checkout services/autorun/custom-1.cf git checkout services/custom-3.cf ``` -Output: - - Updated 1 path from the index - Updated 1 path from the index - Updated 1 path from the index - Updated 1 path from the index +```output +Updated 1 path from the index +Updated 1 path from the index +Updated 1 path from the index +Updated 1 path from the index +``` Other deleted files from the upstream framework like `lib/deprecated-upstream.cf` should be deleted with `git rm`. **Note:** It is uncommon for any files to be moved or deleted between patch releases (e.g. `3.18.0` -> `3.18.5`) like `lib/deprecated-upstream.cf` in this example. -```bash +```command git rm lib/deprecated-upstream.cf ``` -Output: -``` +```output rm 'lib/deprecated-upstream.cf' ``` The files marked as **modified** in the `git status` output are files that have changed upstream. -```bash +```command git status ``` -Output: - -``` +```output On branch master Changes to be committed: (use "git restore --staged ..." to unstage) @@ -744,7 +722,7 @@ It's best to review the diff of **each** modified file to understand the upstrea For example, here the diff for `promises.cf` shows upstream changes but also highlights where the vendored policy had been customized to integrate a custom policy. -```bash +```command git diff promises.cf ``` @@ -890,7 +868,7 @@ index 15c0c40..4611098 100644 Carefully review the diffs and merge or re-integrate your custom changes on top of the upstream files. If you identify changes to the vendored files consider re-integrating those changes in a way that does not modify vendored files, here for example we have migrated the integration of the custom policy to Augments (`def.json`). -```bash +```command git diff def.json ``` @@ -920,7 +898,7 @@ index a7b98e6..60a0ce1 100644 So, we now want to accept all the changes to `promises.cf` and `def.json`. -```bash +```command git add promises.cf def.json ``` @@ -986,13 +964,11 @@ git add update.cf Review `git status` one more time to make sure the changes are as expected. -```bash +```command git status ``` -Output: - -``` +```output On branch master Changes to be committed: (use "git restore --staged ..." to unstage) @@ -1064,13 +1040,11 @@ Changes to be committed: Make sure the policy validates and commit your changes. -```bash +```command git commit -m "Upgraded MPF from 3.18.0 to 3.21.2" ``` -Output: - -``` +```output [master a5d512c] Upgraded MPF from 3.18.0 to 3.21.2 64 files changed, 2599 insertions(+), 728 deletions(-) create mode 100644 cfe_internal/enterprise/templates/apachectl.mustache diff --git a/examples/tutorials/render-files-with-mustache-templates.markdown b/examples/tutorials/render-files-with-mustache-templates.markdown index 5fc9615db..b7f692dae 100644 --- a/examples/tutorials/render-files-with-mustache-templates.markdown +++ b/examples/tutorials/render-files-with-mustache-templates.markdown @@ -43,6 +43,7 @@ Allowed users
Create a file called `/tmp/myapp.conf.template` with the following content: ``` +[file=myapp.conf.template] {% raw %} Port {{port}} Protocol {{protocol}} @@ -59,6 +60,7 @@ Allowed users {{#users}} Create a file called `/tmp/editconfig.cf` with the following content: ```cf3 +[file=editconfig.cf] bundle agent myapp_confs { files: @@ -94,14 +96,16 @@ In this policy we tell CFEngine to ensure a file called `myapp.conf` exists. The Run CFEngine: -```console -# /var/cfengine/bin/cf-agent /tmp/editconfig.cf +```command +/var/cfengine/bin/cf-agent /tmp/editconfig.cf ``` Verify the result: -```console -# cat /tmp/myapp.conf +```command +cat /tmp/myapp.conf +``` +```output Port 3508 Protocol 2 Filepath /mypath/ diff --git a/examples/tutorials/report_inventory_remediate_sec_vulnerabilities.markdown b/examples/tutorials/report_inventory_remediate_sec_vulnerabilities.markdown index 446700e36..28c93dc83 100644 --- a/examples/tutorials/report_inventory_remediate_sec_vulnerabilities.markdown +++ b/examples/tutorials/report_inventory_remediate_sec_vulnerabilities.markdown @@ -38,6 +38,7 @@ This bundle will check if the host is vulnerable to the CVE, define a class interface in CFEngine Enterprise. ```cf3 +[file=inventory_CVE_2014_6271.cf] bundle agent inventory_CVE_2014_6271 { meta: @@ -156,6 +157,7 @@ of the affected systems. Save the following policy into `services/autorun/remediate_CVE_2014_6271.cf` ```cf3 +[file=remediate_CVE_2014_6271.cf] bundle agent remediate_CVE_2014_6271 { meta: diff --git a/examples/tutorials/reporting/command-line-reports.markdown b/examples/tutorials/reporting/command-line-reports.markdown index 506910d2f..c4cb2af2a 100644 --- a/examples/tutorials/reporting/command-line-reports.markdown +++ b/examples/tutorials/reporting/command-line-reports.markdown @@ -130,7 +130,8 @@ reports: The outcome of this promise is a file called /tmp/report.html which contains the following output: -```cf3 +```html +[file=report.html] Name of this host is: atlas
Type of this host is: linux
@@ -200,7 +201,7 @@ reports: This produces the following standard output: -```cf3 +``` R: State of otherprocs peaked at Tue Dec 1 12:12:21 2014 R: The peak measured state was q = 98: @@ -253,7 +254,7 @@ number_of_lines => "$(lines)"; This produces the following output: -```cf3 +``` R: /etc/passwd except R: at:x:25:25:Batch jobs daemon:/var/spool/atjobs:/bin/bash R: avahi:x:103:105:User for Avahi:/var/run/avahi-daemon:/bin/false @@ -365,8 +366,10 @@ log_string => "$(sys.date) $(x) promise status"; This generates three different logs with the following output: -```cf3 -atlas$ more /tmp/private_keptlog.log +```command +more /tmp/private_keptlog.log +``` +```output Sun Dec 6 11:58:16 2009 /tmp/xyz promise status Sun Dec 6 11:58:43 2009 /tmp/xyz promise status ``` @@ -443,7 +446,7 @@ depth => "$(d)"; In CFEngine Enterprise, reports of the following form are generated when these promises are kept by the agent: -```cf3 +``` Change detected File change Sat Dec 5 18:27:44 2013 group for /tmp/testfile changed 100 -> 0 Sat Dec 5 18:27:44 2013 /tmp/testfile diff --git a/examples/tutorials/write-cfengine-policy.markdown b/examples/tutorials/write-cfengine-policy.markdown index 8623e78a2..6f9e01bc2 100644 --- a/examples/tutorials/write-cfengine-policy.markdown +++ b/examples/tutorials/write-cfengine-policy.markdown @@ -63,8 +63,8 @@ you very granular control. To see a list of available classes on your host, just type the following command: -```console -# cf-promises --show-classes +```command +cf-promises --show-classes ``` ## Running policy @@ -74,6 +74,7 @@ final policy. As for classes we will use linux to define that the file `/tmp/hello-world` must exists on all hosts of type *linux*: ```cf3 +[file=my_test.cf] bundle agent my_test{ files: linux:: @@ -104,29 +105,29 @@ this as it is the same cf-agent that runs on the hosts as on the Policy Server. **Tip:** Whenever you make or modify a policy, you can use the `cf-promises` command to run a syntax check: -```console -# cf-promises -f /tmp/my-policy.cf +```command +cf-promises -f /tmp/my-policy.cf ``` Unless you get any output, the syntax is correct. Now, to run this policy, simply type: -```console -# cf-agent -Kf /tmp/my-policy.cf +```command +cf-agent -Kf /tmp/my-policy.cf ``` As you can see, the response is immediate! Running CFEngine locally like this is ideal for testing out new policies. To check that the file has been successfully created type: -```console -# ls /tmp/hello-world -l +```command +ls /tmp/hello-world -l ``` If you want to see what the agent is doing during its run, you can run the agent in verbose mode. Try: -```console -# cf-agent -Kf /tmp/my-policy.cf --verbose +```command +cf-agent -Kf /tmp/my-policy.cf --verbose ``` In a Stand Alone system, to make and run a policy remember to: @@ -161,6 +162,7 @@ Now we need to tell CFEngine that there is a new policy in town: 1. Create `/var/cfengine/masterfiles/def.json` with the following content: ```json +[file=def.json] { "inputs": [ "my-policy.cf" ] } @@ -169,8 +171,8 @@ Now we need to tell CFEngine that there is a new policy in town: On the policy server you can run the following command to make sure the syntax is correct. -```console -# cf-agent -cf /var/cfengine/masterfiles/promises.cf +```command +cf-agent -cf /var/cfengine/masterfiles/promises.cf ``` After some period of time (CFEngine runs by default every 5 minutes), log in to diff --git a/examples/tutorials/writing-and-serving-policy/authoring-policy-tools-and-workflow.markdown b/examples/tutorials/writing-and-serving-policy/authoring-policy-tools-and-workflow.markdown index 97722293c..35099330c 100644 --- a/examples/tutorials/writing-and-serving-policy/authoring-policy-tools-and-workflow.markdown +++ b/examples/tutorials/writing-and-serving-policy/authoring-policy-tools-and-workflow.markdown @@ -48,15 +48,15 @@ Method Two: Create Masterfiles Repository Using the GitHub Application #### Initialize Git Repository in Masterfiles on the Hub - -1. `> cd /var/cfengine/masterfiles` -2. `> echo cf_promises_validated >> .gitignore` -3. `> echo cf_promises_release_id >> .gitignore` -4. `> git init` -5. `> git commit -m "First commit"` -6. `> git remote add origin https://github.com/GitUserName/cfengine-masterfiles.git` -7. `> git push -u origin master` - +```bash +cd /var/cfengine/masterfiles +echo cf_promises_validated >> .gitignore +echo cf_promises_release_id >> .gitignore +git init +git commit -m "First commit" +git remote add origin https://github.com/GitUserName/cfengine-masterfiles.git +git push -u origin master +``` **Note:** `cf_promises_validated` and `cf_promises_release_id` should be explicitly excluded from VCS as shown above. They are generated files and involved in controlling policy updates. If these files are checked into the repository it can create issues with policy distribution. Using the above steps on a private repository will fail with a 403 error. There are different approaches to deal with this: @@ -85,10 +85,18 @@ B) Or, change the remote url to `https://GitUserName@password:github.com/GitUser #### Create a Remote in Masterfiles on the Hub to Masterfiles on GitHub 1. Change back to the `masterfiles` directory, if not already there: - * `> cd /var/cfengine/masterfiles` +```command +cd /var/cfengine/masterfiles +``` 2. Create the remote using the following pattern: - * `> git remote add upstream ssh://git@github.com/GitUserName/cfengine-masterfiles.git`. -3. Verify the remote was registered properly by typing `git remote -v` and pressing enter. +```command +git remote add upstream ssh://git@github.com/GitUserName/cfengine-masterfiles.git +``` + +3. Verify the remote was registered properly: +```command +git remote -v +``` * You will see the remote definition in a list alongside any other previously defined remote entries. #### Add a Promise that Pulls Changes to Masterfiles on the Hub from Masterfiles on GitHub @@ -97,6 +105,7 @@ B) Or, change the remote url to `https://GitUserName@password:github.com/GitUser 2. Add the following text to the `vcs_update.cf` file: ```cf3 +[file=vcs_update.cf] bundle agent vcs_update { commands: @@ -115,6 +124,7 @@ body contain masterfiles_contain 4. Add bundle and file information to `/var/cfengine/masterfiles/promises.cf`. Example (where `...` represents existing text in the file, omitted for clarity): ```cf3 +[file=promises.cf] body common control { diff --git a/examples/tutorials/writing-and-serving-policy/bundles-best-practices.markdown b/examples/tutorials/writing-and-serving-policy/bundles-best-practices.markdown index c3d3c4cee..b53f371cb 100644 --- a/examples/tutorials/writing-and-serving-policy/bundles-best-practices.markdown +++ b/examples/tutorials/writing-and-serving-policy/bundles-best-practices.markdown @@ -61,6 +61,7 @@ Write the promises (which may or may not be ordered) using a parameter for the d names, and then call the method passing the list of names as a parameter to reduce the amount of code. ```cf3 +[file=testbundle.cf] bundle agent testbundle { vars: diff --git a/examples/tutorials/writing-and-serving-policy/policy-style.markdown b/examples/tutorials/writing-and-serving-policy/policy-style.markdown index 3d23b0df1..d0d479bfc 100644 --- a/examples/tutorials/writing-and-serving-policy/policy-style.markdown +++ b/examples/tutorials/writing-and-serving-policy/policy-style.markdown @@ -197,7 +197,7 @@ Promises with multiple attributes should never be put on a single line. Promises over multiple lines should always have the attributes on separate lines. Examples: -``` +```cf3 bundle agent example { vars: @@ -533,7 +533,7 @@ bundle agent satellite_bootstrap_main Output the parsed policy in ```cf``` format: -```console +```command cf-promises -f /tmp/example.cf --policy-output-format cf ``` diff --git a/examples/tutorials/writing-and-serving-policy/testing-policies.markdown b/examples/tutorials/writing-and-serving-policy/testing-policies.markdown index 46ef0695f..705d68537 100644 --- a/examples/tutorials/writing-and-serving-policy/testing-policies.markdown +++ b/examples/tutorials/writing-and-serving-policy/testing-policies.markdown @@ -22,19 +22,21 @@ To test CFEngine as an ordinary user, do the following: Copy the binaries into the work directory: -``` -host$ mkdir -p ~/.cfagent/inputs -host$ mkdir -p ~/.cfagent/bin -host$ cp /var/cfengine/bin/cf-* ~/.cfagent/bin -host$ cp /var/cfengine/inputs/*.cf ~/.cfagent/inputs +```console +mkdir -p ~/.cfagent/inputs +mkdir -p ~/.cfagent/bin +cp /var/cfengine/bin/cf-* ~/.cfagent/bin +cp /var/cfengine/inputs/*.cf ~/.cfagent/inputs ``` You can test the software and play with configuration files by editing the basic directly in the `~/.cfagent/inputs` directory. For example, try the following: +```console +~/.cfagent/bin/cf-promises +~/.cfagent/bin/cf-promises --verbose +``` - host$ ~/.cfagent/bin/cf-promises - host$ ~/.cfagent/bin/cf-promises --verbose This is always the way to start checking a configuration in CFEngine 3. If a configuration does not pass this check/test, you will not be allowed to use diff --git a/getting-started/installation/general-installation/installation-coreos.markdown b/getting-started/installation/general-installation/installation-coreos.markdown index ff8dfcc87..1b7e575c5 100644 --- a/getting-started/installation/general-installation/installation-coreos.markdown +++ b/getting-started/installation/general-installation/installation-coreos.markdown @@ -33,7 +33,7 @@ Note: Install actions logged to `/var/log/CFEngine-Install.log`. Run the bootstrap command: -```commmand +```command sudo /var/cfengine/bin/cf-agent --bootstrap ``` diff --git a/web-ui/custom-actions-for-alerts.markdown b/web-ui/custom-actions-for-alerts.markdown index da7d9d5dd..214456ee6 100644 --- a/web-ui/custom-actions-for-alerts.markdown +++ b/web-ui/custom-actions-for-alerts.markdown @@ -103,7 +103,7 @@ When you get this to work as expected on the commmand line, you are ready to upl ## Example script: logging policy alert to syslog The following Custom action script will log the status and definition of a policy alert to syslog. -```shell +```bash [file=cfengine_custom_notification_policy_syslog.sh] #!/bin/bash diff --git a/web-ui/enterprise-reporting/client-initiated-reporting.markdown b/web-ui/enterprise-reporting/client-initiated-reporting.markdown index ca72ad02d..a9659a67e 100644 --- a/web-ui/enterprise-reporting/client-initiated-reporting.markdown +++ b/web-ui/enterprise-reporting/client-initiated-reporting.markdown @@ -19,7 +19,7 @@ Call collect and Client Initiated Reporting are the same, they both refer to the The easiest way to enable call collect is via augments files, modify `/var/cfengine/masterfiles/def.json` on the hub: -``` +```json [file=def.json] { "classes": { diff --git a/web-ui/hub_administration/reset-admin-creds.markdown b/web-ui/hub_administration/reset-admin-creds.markdown index 5dea742e6..232cb39e1 100644 --- a/web-ui/hub_administration/reset-admin-creds.markdown +++ b/web-ui/hub_administration/reset-admin-creds.markdown @@ -6,9 +6,9 @@ published: true The default `admin` user can be reset to defaults using the following SQL. -cfsettings-setadminpassword.sql: ```sql +[file=cfsettings-setadminpassword.sql] INSERT INTO "users" ("username", "password", "salt", "name", "email", "external", "active", "roles", "changetimestamp") SELECT 'admin', 'SHA=aa459b45ecf9816d472c2252af0b6c104f92a6faf2844547a03338e42e426f52', 'eWAbKQmxNP', 'admin', 'admin@organisation.com', false, '1', '{admin,cf_remoteagent}', now() ON CONFLICT (username, external) DO UPDATE