Improved puppet agent docu

admin-guide/configuration/puppet_agent.md

@@ -1,33 +1,50 @@
 # Puppet Agent Configuration
-The Puppet agent software communicates with the Puppet master to enforce desired system configurations defined in hiera.
+The Puppet Agent provides the basic system configuration as defined in Hiera.
 
 ## Automatic Puppet Agent Runs
-Puppet agent is configured to run daily between 5-8 AM.
-This describes how the Puppet agent can be configured to run at different intervals and also at different times than the default.
 
-### Agent Run Frequency
-The intervals the Puppet agent runs can be configured in hiera with `puppet_client::run_frequency`
+By default the Puppet Agent runs daily somewhen between 5-8 AM.
 
-Allowed parameters
+The frequency can be changed in Hiera with the key `puppet_client::run_frequency`.
+
+Allowed parameters are
 - 'halfhourly': every 30 minutes
 - 'daily': once a day (default)
-- 'weekly': every Monday 
+- 'weekly': every Monday
 
-The daily and weekly Puppet run respect the value set for `puppet_client::exec_time`
+The actual automatic Puppet Agent run is always on the same random time. Check `systemctl list-timers pli-puppet-run.timer` for the exact time on a specific node.
 
-### Execution Time
-The actual automatic Puppet Agent run is always on the same random time. Check `systemctl list-timers pli-puppet-run.timer` for the exact time.
-For `daily` and `weekly` this time window is configured in Hiera with `puppet_client::exec_time`, the default is:
-
-`puppet_client::exec_time: '05:00 -- 08:00'`
-
-The time format used is '24-hour clock' `HH:MM -- HH:MM`
+For `daily` and `weekly` the time window is configured in Hiera with `puppet_client::exec_time`, the default is:
+```
+puppet_client::exec_time: '05:00 -- 08:00'
+```
+The time format used is '24-hour clock' `HH:MM -- HH:MM`.
 
 ## Temporarily Disable Automatic Puppet Agent Runs
 Puppet execution can be disabled for a certain amount of time with the
-``/opt/pli/libexec/pli-puppet-disable`` command.
+`/opt/pli/libexec/pli-puppet-disable` command:
 
+```
+# /opt/pli/libexec/pli-puppet-disable
+puppet currently not disabled
+# /opt/pli/libexec/pli-puppet-disable '1 week'
+# /opt/pli/libexec/pli-puppet-disable
+Puppet disabled until: Wed Nov 1 08:00:05 CET 2017
+# /opt/pli/libexec/pli-puppet-disable stop
+Stopping
+# /opt/pli/libexec/pli-puppet-disable
+puppet currently not disabled
+#
+```
 The disabling time has to be in the ``date`` format (see date(1)).
 
 ## Manual Execution of Puppet Agent
-The Puppet agent can be run manually by executing following command `puppet agent -t`
+At any time you might update the node configuration by running the Puppet Agent manually. To do so run as user `root` the following command:
+```
+puppet agent -t
+```
+
+If you just wish to see what it would change without doing the actual change on the system, run
+```
+puppet agent -t --noop
+```