Update OpenFact

- add missing facts-group in facter config
- switch examples from legacy to structured facts
- add information on writing facts on windows
- timeout der fact
- hint on Facter::Execution.exec deprecation
- add information on logging

Signed-off-by: Martin Alfke <ma@betadots.de>

Author: tuxmea

docs/_openfact_5x/configuring_openfact.md

@@ -4,14 +4,14 @@ toc_levels: 1
 title: "Configuring OpenFact with facter.conf"
 ---
 
-The `facter.conf` file is a configuration file that allows you to cache and block fact groups, and manage how OpenFact interacts with your system. There are three sections: `facts`, `global` and `cli`.
+The `facter.conf` file is a configuration file that allows you to cache and block fact groups, and manage how OpenFact interacts with your system. There are three sections: `facts`, `global`, `cli` and `facts-group`.
 All sections are optional and can be listed in any order within the file.
 
 When you run OpenFact from the Ruby API, only the `facts` section and limited `global` settings are loaded.
 
 Example facter.conf file:
 
-~~~yaml
+~~~hocon
 facts : {
     blocklist : [ "file system", "EC2" ],
     ttls : [
@@ -32,6 +32,9 @@ cli : {
     verbose   : false,
     log-level : "warn"
 }
+fact-groups : {
+ custom-group-name : ["os.name", "networking.ip"],
+}
 ~~~
 
 ## Location
@@ -79,14 +82,29 @@ file system
 
 If you want to block any of these groups, add the group name to the `facts` section of `facter.conf`, with the `blocklist` setting.
 
-~~~yaml
+~~~hocon
 facts : {
     blocklist : [ "file system" ],
 }
 ~~~
 
 Here, the "file system" group has been added, so the `mountpoints`, `filesystems`, and `partitions` facts will all be prevented from loading.
 
+Within the `blocklist` and `ttls` settings, one can specify fact names:
+
+~~~hocon
+facts : {
+   blocklist : [ "disks", "memory.swap" ],
+}
+~~~
+
+~~~hocon
+ttls : [
+   { "mountpoints" : 30 days },
+   { "memory.swap" : 6 hours },
+]
+~~~~
+
 ### `global`
 
 The `global` section of `facter.conf` contains settings to control how OpenFact interacts with its external elements on your system.
@@ -111,3 +129,14 @@ The `cli` section of `facter.conf` contains settings that affect OpenFact’s co
 | `trace` | If true, OpenFact prints stacktraces from errors arising in your custom facts. | `false` |
 | `verbose` | If true, OpenFact outputs its most detailed messages. | `false` |
 | `log-level` | Sets the minimum level of message severity that gets logged. Valid options: “none”, “fatal”, “error”, “warn”, “info”, “debug”, “trace”. | “warn” |
+
+### `facts-groups`
+
+If you have a need to define your own group of facts beacuse you want to manage a larger set of facts within `blocklist` or `ttls` you can make use of the `facts-groups` setting.
+Please note that you can not specify external facts here. Structured facts can be provided using the dot notation.
+
+~~~hocon
+fact-groups : {
+ custom-group-name : ["os.name", "networking.ip"],
+}
+~~~

docs/_openfact_5x/custom_facts.md

@@ -7,6 +7,8 @@ title: "Custom facts walkthrough"
 [Adding plug-ins to a module]: /openvox/latest/plugins_in_modules.html
 [Facts overview]: ./fact_overview.html
 [openvoxdb]: /openvoxdb/latest
+[Win32 API]: https://docs.microsoft.com/en-us/windows/win32/api/
+[Fiddle]: https://github.com/ruby/fiddle
 
 You can add custom facts by adding snippets of Ruby code to the OpenVox server. OpenVox then uses [Plugins in Modules][] to distribute the facts to all agents.
 
@@ -99,7 +101,7 @@ OpenVox gets information about a system from OpenFact, and the most simple way f
 get that information is by executing shell commands. You can then parse and manipulate the
 output from those commands using standard Ruby code.
 
-> **Note:** However, it is important to also ceck if any of the OpenVox agent bundled Ruby Libraries can be used.
+> **Note:** However, it is important to also check if any of the OpenVox agent bundled Ruby Libraries can be used.
 
 The OpenFact API gives you a few ways to
 execute shell commands:
@@ -134,13 +136,13 @@ To get the output of `uname --hardware-platform` to single out a specific type o
 
 ## Accessing other facts
 
-You can write a custom fact that uses other facts by accessing `Facter.value(:somefact)`.
+You can write a custom fact that uses other facts by accessing `Facter.value(:somefact)`. When accessing parts of a structured fact, one must append the key name: `Facter.value(:os)['family']`.
 If the fact fails to resolve or is not present, OpenFact returns `nil`.
 
 For example:
 
 ``` ruby
-Facter.add(:osfamily) do
+Facter.add(:my_osfamily) do
   setcode do
     distid = Facter.value(:os)['family']
     case distid
@@ -163,6 +165,7 @@ Facts have a few properties that you can use to customize how they are evaluated
 
 One of the more commonly used properties is the `confine` statement, which
 restricts the fact to only run on systems that matches another given fact.
+However, this should be done cautiously to avoid introducing cyclic dependencies between facts.
 
 An example of the confine statement would be something like the following:
 
@@ -183,7 +186,37 @@ available on the given system. Since this is only available on Linux systems,
 we use the `confine` statement to ensure that this fact isn't needlessly run on
 systems that don't support this type of enumeration.
 
-> **Note:** More information on other ways to confine. e.g. files present can be found a the [Facts overview]
+In our next example the application has different config paths for different OS.
+
+RedHat - /etc/sysconfig/application
+Debian - /etc/default/application
+
+Example with access to another fact:
+
+```ruby
+Facter.add(:betadots_application_version) do
+  confine do
+    app_cfg_file = case Facter.value('os')['family']
+                   when 'RedHat'
+                     '/etc/sysconfig/application'
+                   when 'Debian'
+                     '/etc/default/application'
+                   else
+                     'notexisting'
+                   end
+
+    File.exist?(app_cfg_file)
+  end
+
+  setcode do
+    Facter::Core::Execution.execute('/opt/app/bin/app config')
+  end
+end
+```
+
+The example retrieves the os fact and uses the family key to compare the OS, then applies logic to determine which application config path to check for.
+
+> **Note:** More information on other ways to confine can be found in the [Facts overview]
 
 ### Custom facts precedence
 
@@ -237,7 +270,21 @@ end
 ### Custom facts execution timeouts
 
 Although this version of OpenFact does not support overall timeouts on resolutions, you can pass a timeout
-to `Facter::Core::Execution#execute`:
+to `Facter::Core::Execution#execute` or specify the timeout per fact.
+
+Timeout for the whole fact:
+
+```ruby
+Facter.add('<name>', {timeout: 5}) do
+  ...
+end
+```
+
+Timeout per execute method
+
+```ruby
+Facter::Core::Execution::execute('<cmd>', options = {:timeout => 5})
+```
 
 ``` ruby
 Facter.add(:sleep) do
@@ -252,6 +299,37 @@ Facter.add(:sleep) do
 end
 ```
 
+For example, if an application returns its configuration via /opt/app/bin/app config and this commands is sometimes running very long, you can set a timeout:
+
+```ruby
+Facter.add(:application_config) do
+  confine do
+    File.exist?('/opt/app/bin/app')
+  end
+
+  setcode do
+    Facter::Core::Execution.execute('/opt/app/bin/app config', {:timeout => 5})
+  end
+end
+```
+
+> Please note that Facter::Core::Execution::exec has been deprecated in favor of Facter::Core::Execution::execute. This is important when migrating from older versions of Facter.
+
+### Logging
+
+It's often useful to include logging within custom facts to help with troubleshooting and development. You can log messages using Puppet's built-in logging mechanism:
+
+```ruby
+Facter.add(:application_version) do
+  setcode do
+    Facter.debug("Custom fact 'application_version' running")
+    ...
+  end
+end
+```
+
+Logging levels include `debug`, `info`, `warn`, `error`, and `fatal`.
+
 ## Structured custom facts
 
 Structured facts take the form of either a hash or an array. To create a structured fact, return a hash or an array from the `setcode` statement.
@@ -304,6 +382,30 @@ If the `chunk` blocks all return arrays or hashes, you can omit the `aggregate`
 
 For more examples of aggregate resolutions, see the [aggregate resolutions](./fact_overview.html#writing-facts-with-aggregate-resolutions) section of the [Fact overview] page.
 
+## Windows Facts
+
+Windows-based systems support custom facts just like Linux or other Unix-like systems.
+The main difference is that many Windows-specific tasks (such as checking installed software or reading from the registry) may require platform-specific Ruby code.
+
+Within the Facter::Core::Execution.execute usually powershell commands are used.
+
+Here's an example of a Windows custom fact that retrieves the version of Internet Explorer:
+
+```ruby
+Facter.add(:internet_explorer_version) do
+  confine kernel: 'windows'
+
+  setcode do
+    Facter::Core::Execution.execute('reg query "HKLM\Software\Microsoft\Internet Explorer" /v svcVersion')
+  end
+end
+```
+
+In this example, we use the `reg query` command to check the Internet Explorer version in the Windows registry.
+
+Please note that the [Win32 API] calls are deprecated since ruby 1.9.
+Please consider using [Fiddle] or other Ruby-based libraries for interacting with the system.
+
 ## Viewing fact values
 
 [OpenVox-DB]: /openvoxdb/latest

docs/_openfact_5x/fact_overview.md

@@ -79,7 +79,7 @@ Simple facts are typically made up of the following parts:
     * Can take either a string or a block.
     * If given a string, OpenFact executes it as a shell command. If the command succeeds, the output of the command is the value of the fact. If the command fails, the next suitable resolution is evaluated.
     * If given a block, the block's return value is the value of the fact unless the block returns `nil`. If `nil` is returned, the next suitable resolution is evalutated.
-    * Can execute shell commands within a `setcode` block, using the `Facter::Core::Execution.exec` function.
+    * Can execute shell commands within a `setcode` block, using the `Facter::Core::Execution.execute` function.
     * If multiple `setcode` statements are evaluated for a single resolution, only the last `setcode` block is used.
 
 ## Writing structured facts
@@ -92,10 +92,9 @@ Structured facts can have [simple](#main-components-of-simple-resolutions) or [a
 ``` ruby
 Facter.add(:interfaces_array) do
   setcode do
-   interfaces = Facter.value(:interfaces)
-   # the 'interfaces' fact returns a single comma-delimited string, e.g., "lo0,eth0,eth1"
-   # this splits the value into an array of interface names
-   interfaces.split(',')
+    interfaces = Facter.value(:networking)['interfaces'].keys
+    # the 'networking' fact provdes a list of interface hashes with the interface name as key.
+    # using the keys functon on the hash provoides an array of interface names.
   end
 end
 ```
@@ -108,7 +107,7 @@ Facter.add(:interfaces_hash) do
     interfaces_hash = {}
 
     Facter.value(:interfaces_array).each do |interface|
-      ipaddress = Facter.value("ipaddress_#{interface}")
+      ipaddress = Facter.value(:networking)['interfaces'][interface]['ip']
       if ipaddress
         interfaces_hash[interface] = ipaddress
       end
@@ -119,6 +118,50 @@ Facter.add(:interfaces_hash) do
 end
 ```
 
+### Example: Provide OpenVox Agent certificate extensions as hash
+
+```ruby
+Facter.add(:cert_extension) do
+  setcode do
+    require 'openssl'
+    require 'puppet'
+    require 'puppet/ssl/oids'
+
+    # set variables
+    extension_hash = {}
+    certdir = Puppet.settings[:certdir]
+    certname = Puppet.settings[:certname]
+    certificate_file = "#{certdir}/#{certname}.pem"
+
+    # get puppet ssl oids
+    oids = {}
+    Puppet::SSL::Oids::PUPPET_OIDS.each do |o|
+      oids[o[0]] = o[1]
+    end
+
+    # read the certificate
+    cert = OpenSSL::X509::Certificate.new File.read certificate_file
+
+    # cert extensions differs if we run via agent (numeric) or via facter (names)
+    # in either way we want to remove pp_preshared_key from the list
+    cert.extensions.each do |extension|
+      case extension.oid.to_s
+      when %r{^1\.3\.6\.1\.4\.1\.34380\.1\.1}
+        short_name = oids[extension.oid]
+        value = extension.value[2..-1]
+        extension_hash[short_name] = value unless short_name == 'pp_preshared_key'
+      when %r{^pp_}
+        short_name = extension.oid
+        value = extension.value[2..-1]
+        extension_hash[short_name] = value unless short_name == 'pp_preshared_key'
+      end
+    end
+
+    extension_hash
+  end
+end
+```
+
 ## Writing facts with aggregate resolutions
 
 Aggregate resolutions allow you to split up the resolution of a fact into separate chunks.By default, OpenFact merges hashes with hashes or arrays with arrays, resulting in a [structured fact](#writing-structured-facts).
@@ -212,11 +255,11 @@ The fact's output is organized by network interface into hashes, each containing
 ``` ruby
 Facter.add(:total_free_memory_mb, :type => :aggregate) do
   chunk(:physical_memory) do
-    Facter.value(:memoryfree_mb)
+    Facter.value(:memory)['system']['available_bytes']
   end
 
   chunk(:virtual_memory) do
-    Facter.value(:swapfree_mb)
+    Facter.value(:memory)['swap']['available_bytes']
   end
 
   aggregate do |chunks|

docs/_openfact_5x/release_notes.md

@@ -16,5 +16,4 @@ Please check the [GitHub OpenFact release page](https://github.com/OpenVoxProjec
 
 Released February 20, 2026
 
-Please check the [GitHub OpenFact release page](https://github.com/OpenVoxProject/openfact/releases/tag/5.6.0) for details on new features or bug fixes
-.
+Please check the [GitHub OpenFact release page](https://github.com/OpenVoxProject/openfact/releases/tag/5.6.0) for details on new features or bug fixes.