cfengine · nickanderson · Nov 16, 2023 · Nov 16, 2023 · Nov 17, 2023 · Nov 17, 2023
diff --git a/cheatsheet.markdown b/cheatsheet.markdown
@@ -59,7 +59,7 @@ _Most_ (`¯\_(ツ)_/¯`) special characters are _okay_. For example:
 * Link targets with `/` (forward slashes) work
    * ```[Export/import][Settings#Export/import]``` == [Export/import][Settings#Export/import]
 
-Anchors with _underscores_ are problematic, they need to be escaped.
+Anchors with _underscores_ are problematic, *may* need to be escaped.
 
 For example ```services_autorun``` in the MPF documentation the underscore needs to be escaped with a ```\```.
 
@@ -69,6 +69,16 @@ For example ```services_autorun``` in the MPF documentation the underscore needs
 
 **See also:** [`services_autorun` in the Masterfiles Policy Framework][Masterfiles Policy Framework#services\_autorun]
 
+But not always! For example
+
+```
+**See also:** [cf_lock.lmdb][CFEngine directory structure#state/cf_lock.lmdb]
+```
+
+**See also:** [cf_lock.lmdb][CFEngine directory structure#state/cf_lock.lmdb]
+
+Backticks are problematic. It seems impossible to link to anchors that contain backticks.
+
 ### Link to CFEngine keyword
 
 The documentation pre-processor will create those automatically.

diff --git a/examples/tutorials/writing-and-serving-policy/controlling-frequency.markdown b/examples/tutorials/writing-and-serving-policy/controlling-frequency.markdown
@@ -5,9 +5,55 @@ published: true
 sorting: 90
 ---
 
-When checking a series of expensive functions and verifying complex promises,
-you may want to make sure that CFEngine is not checking too frequently. One
-way of doing this is classes and class expression, another is using locks.
+By default CFEngine runs relatively frequently (every 5 minutes) but you may not
+want every promise to be evaluated each agent execution. Classes and promise
+locks are the two primary ways in which a promises frequency can be controlled.
+Classes are the canonical way of controlling if a promise is in context and
+should be evaluated. Promise locks control frequency based on the number of
+minutes since the last promise actuation.
+
+## Controlling frequency using classes
+
+Classes are the canonical way of controlling promise executions in CFEngine.
+
+Use time based classes to restrict promises to run during a specific period of time. For example, here `sshd` promises to be the latest version available, but only on Tuesdays during the first 15 minutes of the 5:00 hour.
+
+```cf3
+bundle agent __main__
+{
+  packages:
+    Tuesday.Hr05_Q1::
+    "sshd"
+      version => "latest",
+      comment => "Make sure sshd is at the latest version, but only Tuesday between 5:00 and 5:15am";
+}
+```
+
+Persistent classes can exist for a period of time, across multiple executions of
+`cf-agent`. Persistent classes can be used to avoid re-execution of a promise.
+For example, here `/tmp/heartbeat.dat` promises to update it's timestamp when
+`heartbeat_repaired` is not defined. When the file is repaired the class
+`heartbeat_repaired` is defined for 10 minutes causing the promise to be out of
+context during subsequent executions for the next 10 minutes.
+
+```cf3
+bundle agent __main__
+{
+  files:
+    !heartbeat_repaired::
+      "/tmp/heartbeat.dat"
+        create => "true",
+        touch => "true",
+        classes => persistent_results( "heartbeat", 10 );
+}
+body classes persistent_results( prefix, time )
+{
+    inherit_from => results( "namespace", "$(prefix)" );
+    persist_time => "$(time)";
+}
+```
+
+## Controlling frequency using promise locks
 
 CFEngine incorporates a series of locks which prevent it from checking
 promises too often, and which prevent it from spending too long trying to
@@ -16,19 +62,17 @@ a way that you can start several CFEngine components simultaneously without
 them interfering with each other. You can control two things about each kind
 of action in CFEngine:
 
-    ifelapsed
-
-The minimum time (in minutes) which should have passed since the last time
-that promise was verified. It will not be executed again until this amount of
-time has elapsed. Default time is 1 minute.
+* `ifelapsed` - The minimum time (in minutes) which should have passed since the
+  last time that promise was verified. It will not be executed again until this
+  amount of time has elapsed. If the value is `0` the promise has no lock and
+  will always be executed when in context. Additionally, a value of `0` disables
+  function caching. Default time is `1` minute.
 
-    expireafter
-
-The maximum amount (in minutes) of time `cf-agent` should wait for an old
-instantiation to finish before killing it and starting again. You can think
-about [`expireafter`][cf-agent#expireafter] as a timeout to use when a promise verification may
-involve an operation that could wait indefinitely. Default time is 120
-minutes.
+* `expireafter` - The maximum amount (in minutes) of time `cf-agent` should wait
+  for an old instantiation to finish before killing it and starting again. You
+  can think about [`expireafter`][cf-agent#expireafter] as a timeout to use when
+  a promise verification may involve an operation that could wait indefinitely.
+  Default time is `120` minutes.
 
 You can set these values either globally (for all actions) or for each action
 separately. If you set global and local values, the local values override the
@@ -62,3 +106,29 @@ atomic promise checks on the same objects (packages, users, files,
 etc.). Several different `cf-agent` instances can run concurrently.
 The locks ensure that promises will not be verified by two cf-agents
 at the same time or too soon after a verification.
+
+For example, here the `sshd` package promises to be at the latest version. It
+has the `if_elapsed_day` action body attached which sets `ifelapsed` to `1440`
+causing the promise lock to persist for a day effectively restricting the
+promise to run just once a day.
+
+```cf3
+bundle agent __main__
+{
+  packages:
+    "sshd"
+      version => "latest",
+      action => if_elapsed_day,
+      comment => "Make sure sshd is at the latest version, but just once a day.";
+}
+```
+
+**Note:**
+
+* Promise locks are ignored when CFEngine is run with the `--no-lock` or `-K`
+  option, e.g. a common **manual** execution of the agent, `cf-agent -KI` would
+  not respect promises that are locked from a recent execution.
+* Locks are purged based on database utilization and age in order to maintain
+  the integrity and health of the underlying lock database.
+
+**See also:** [cf_lock.lmdb][CFEngine directory structure#state/cf_lock.lmdb]
diff --git a/generator/_assets/styles/less/article.less b/generator/_assets/styles/less/article.less
@@ -110,10 +110,16 @@ article {
 
     .article_title {
       display: flex;
-      align-items: center;
+      align-items: flex-start;
+      word-wrap: break-word;
+      grid-gap: 12px;
 
       h1 {
         flex-grow: 1;
+        max-width: calc(100% - 110px);
+        @media @phone-down {
+          max-width: 100%;
+        }
       }
 
       @media @phone-down {

diff --git a/generator/_assets/styles/less/base.less b/generator/_assets/styles/less/base.less
@@ -427,7 +427,7 @@ pre {
 aside {
   grid-area: navigation;
   width: 28rem;
-  margin-left: 4rem;
+  margin-left: 2rem;
   margin-right: 5.6rem;
   @media @desktop-wide-down {
     margin-right: 1.6rem;

diff --git a/generator/_assets/styles/less/menu.less b/generator/_assets/styles/less/menu.less
@@ -69,7 +69,8 @@ aside {
       padding-top: 1rem;
       padding-bottom: 1rem;
       display: inline-block;
-      max-width: 90%;
+      max-width: 96%;
+      word-break: break-word;
     }
 
     ul {

diff --git a/generator/build/README.md b/generator/build/README.md
@@ -14,14 +14,13 @@ You will need to have the following repos checked out:
 * enterprise (used for changelog)
 * masterfiles (used to document masterfies)
 * documentation
-* documentation/generator (this repo)
 
 Usage
 -----
 
 If you have buildah installed:
 
-1. clone the above repos
+1. clone the above repos (run `clone.sh`)
 
 2. export the following env variables:
 
@@ -30,11 +29,11 @@ If you have buildah installed:
 
 	* `$PACKAGE_JOB` - where to take CFEngine HUB package from,
 	  a dir at http://buildcache.cloud.cfengine.com/packages/,
-	  usually testing-pr
+	  usually `testing-pr`
 
 	* `$PACKAGE_UPLOAD_DIRECTORY` - where to take CFEngine HUB package from,
 	  a dir at http://buildcache.cloud.cfengine.com/packages/testing-pr/,
-	  for example, jenkins-master-nightly-pipeline-943
+	  for example, `jenkins-master-nightly-pipeline-943`
 
 	* `$PACKAGE_BUILD` - RELEASE of the build to be downloaded, usually 1
 

diff --git a/generator/build/clone.sh b/generator/build/clone.sh
@@ -0,0 +1,5 @@
+#!/bin/sh
+
+for repo in core nova enterprise masterfiles documentation; do
+    git clone "[email protected]:cfengine/$repo.git"
+done
diff --git a/generator/build/install.sh b/generator/build/install.sh
@@ -70,9 +70,9 @@ gem install jekyll-asset-pipeline --version 0.1.6
 gem install closure-compiler --version 1.1.8
 gem install yui-compressor --version 0.9.6
 gem install albino --version 1.3.3
+gem install execjs --version 1.4.0
 gem install redcarpet --version 2.2.2
 gem install uglifier --version 1.3.0
-gem install execjs --version 1.4.0
 gem install sanitize --version 2.0.3
 
 cat > /tmp/jekyll-0.12.1-cfengine.patch <<EOF

diff --git a/generator/build/main.sh b/generator/build/main.sh
@@ -15,7 +15,7 @@ export PACKAGE_UPLOAD_DIRECTORY=$3
 export PACKAGE_BUILD=$4
 
 export JOB_TO_UPLOAD=$PACKAGE_JOB
-export FLAG_FILE_URL="http://buildcache.cfengine.com/packages/$PACKAGE_JOB/$PACKAGE_UPLOAD_DIRECTORY/PACKAGES_HUB_x86_64_linux_ubuntu_18/core-commitID"
+export FLAG_FILE_URL="http://buildcache.cfengine.com/packages/$PACKAGE_JOB/$PACKAGE_UPLOAD_DIRECTORY/PACKAGES_HUB_x86_64_linux_ubuntu_22/core-commitID"
 export NO_OUTPUT_DIR=1
 
 env
@@ -74,7 +74,7 @@ done
 wget -O- $FLAG_FILE_URL
 
 echo "Detecting version"
-HUB_DIR_NAME=PACKAGES_HUB_x86_64_linux_ubuntu_18
+HUB_DIR_NAME=PACKAGES_HUB_x86_64_linux_ubuntu_22
 HUB_DIR_URL="http://buildcache.cfengine.com/packages/$PACKAGE_JOB/$PACKAGE_UPLOAD_DIRECTORY/$HUB_DIR_NAME/"
 HUB_PACKAGE_NAME="$(wget $HUB_DIR_URL -O- | sed '/deb/!d;s/.*"\([^"]*\.deb\)".*/\1/')"
 
@@ -83,8 +83,9 @@ fetch_file "$HUB_DIR_URL$HUB_PACKAGE_NAME" "cfengine-nova-hub.deb" 12
 sudo apt-get -y purge cfengine-nova-hub || true
 sudo rm -rf /*/cfengine
 
-# unpack 
+# unpack
 sudo dpkg --unpack cfengine-nova-hub.deb
+rm cfengine-nova-hub.deb
 sudo cp -a /var/cfengine/share/NovaBase/masterfiles "$WRKDIR"
 sudo chmod -R a+rX "$WRKDIR"/masterfiles
 

diff --git a/overview/directory-structure.markdown b/overview/directory-structure.markdown
@@ -129,25 +129,34 @@ each run.
 
 ## Database files in /var/cfengine
 
-* bundles.lmdb
-* `cf_classes.lmdb`
+### state/cf_classes.lmdb
 
-A database of classes that have been defined on the current host,
-including their relative frequencies, scaled like a probability.
+A database of classes that have been defined on the current host, including
+their relative frequencies, scaled like a probability.
 
-* `cf_lastseen.lmdb`
+### state/cf_lastseen.lmdb
 
-A database of hosts that last contacted this host, or were contacted by
-this host, and includes the times at which they were last observed.
+A database of hosts that last contacted this host, or were contacted by this
+host, and includes the times at which they were last observed.
 
-* `cf_changes.lmdb`
+### state/cf_lock.lmdb
+
+A database of active and inactive promise locks and their expiry times. Deleting
+this database will reset all lock protections in CFEngine.
+
+**Note:** Locks are purged in order to maintain the integrity and health of the
+underlying lock database. When the lock database utilization grows to 25%
+locks 4 weeks or older are purged. At 50% locks 2 weeks or older are purged
+and at 75% locks older than 1 week are purged.
+
+### state/cf_changes.lmdb
 
 The database of hash values used in CFEngine's change management
 functions.
 
-* `nova_agent_execution.lmdb`
-* `nova_track.lmdb`
-* `performance.lmdb`
+### state/nova_agent_execution.lmdb
+### state/nova_track.lmdb
+### state/performance.lmdb
 
 A database of last, average and deviation times of jobs recorded by
 `cf-agent`. Most promises take an immeasurably short time to check, but
@@ -227,11 +236,6 @@ IP address of the policy server
 
 ## Not verified
 
-* `state/cf_lock.lmdb`
-
-A database of active and inactive locks and their expiry times. Deleting
-this database will reset all lock protections in CFEngine.
-
 * `state/history.lmdb`
 
 CFEngine Enterprise maintains this long-term trend database.