Configuring Facter with facter.conf

The facter.conf file is a configuration file that allows you to cache and block fact groups and facts, and manage how Facter interacts with your system. There are four sections: facts, global, cli and fact-groups. All sections are optional and can be listed in any order within the file.

When you run Facter from the Ruby API, only the facts section and limited global settings are loaded.

Example facter.conf file:

facts : {
    blocklist : [ "file system", "EC2", "os.architecture" ],
    ttls : [
        { "timezone" : 30 days },
    ]
}
global : {
    external-dir     : [ "path1", "path2" ],
    custom-dir       : [ "custom/path" ],
    no-exernal-facts : false,
    no-custom-facts  : false,
    no-ruby          : false
}
cli : {
    debug     : false,
    trace     : true,
    verbose   : false,
    log-level : "warn"
}
fact-groups : {
 custom-group-name : ["os.name", "ssh"],
}

Note: The facter.conf file is in hocon format. Use // or # for comments.

Location

Facter does not create the facter.conf file automatically, so you must create it manually, or use a module to manage it. Facter loads the file by default from /etc/puppetlabs/facter/facter.conf on *nix systems and C:\ProgramData\PuppetLabs\facter\etc\facter.conf on Windows. Or you can specify a different default with the --config command line option:

facter --config path/to/my/config/file/facter.conf

`facts`

This section of facter.conf contains settings that affect fact groups. A fact group contains one or more individual facts. When you block or cache a fact group, all the facts from that group are affected. You can cache any type of fact, including custom and external.

The settings in this section are:

blocklist — Prevents all facts within the listed groups from being resolved when Facter runs. Use the --list-block-group command line option to list valid groups.
ttls — Caches the key-value pairs of groups and their duration to be cached. Use the --list-cache-group command line option to list valid groups.
- Cached facts are stored as JSON in /opt/puppetlabs/facter/cache/cached_facts on *nix and C:\ProgramData\PuppetLabs\facter\cache\cached_facts on Windows.

Caching and blocking facts is useful when Facter is taking a long time and slowing down your code. When a system has a lot of something — for example, mount points or disks — Facter can take a long time to collect the facts from each one. When this is a problem, you can speed up Facter’s collection by either blocking facts you’re uninterested in (blocklist), or caching ones you don’t need retrieved frequently (ttls).

To see a list of valid group names, from the command line, run facter --list-block-groups or facter --list-cache-groups. The output shows the fact group at the top level, with all facts in that group nested below:

$ facter --list-block-groups
EC2
  - ec2_metadata
  - ec2_userdata
file system
  - mountpoints
  - filesystems
  - partitions

If you want to block any of these groups, add the group name to the facts section of facter.conf, with the blocklist setting:

facts : {
    blocklist : [ "file system" ],
}

Here, the file system group has been added, so the mountpoints, filesystems, and partitions facts are now prevented from loading.

You can also specify fact names with the blocklist and ttls settings. For example:

facts : {
   blocklist : [ "my_external_fact.txt", "my_executable_fact.sh" ],
}

ttls : [
   { "timezone" : 30 days },
   { "networking.hostname" : 6 hours },
]

`global`

The global section of facter.conf contains settings to control how Facter interacts with its external elements on your system.


Setting	Effect	Default
`external-dir`	A list of directories to search for external facts.
`custom-dir`	A list of directories to search for custom facts.
`no-external`*	If `true`, prevents Facter from searching for external facts.	`false`
`no-custom`*	If `true`, prevents Facter from searching for custom facts.	`false`
`no-ruby`*	If `true`, prevents Facter from loading its Ruby functionality.	`false`

*Not available when you run Facter from the Ruby API.

`cli`

The cli section of facter.conf contains settings that affect Facter’s command line output. All of these settings are ignored when you run Facter from the Ruby API.


Setting	Effect	Default
`debug`	If `true`, Facter outputs debug messages.	`false`
`trace`	If `true`, Facter prints stacktraces from errors arising in your custom facts.	`false`
`verbose`	If `true`, Facter 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"`

`fact-groups`

The fact-groups group lets you define your own custom groups in facter.conf. A group can contain any type of fact, except external facts. For aggregated facts, you can specify the root fact using the dot notation. You can use these defined groups for blocking (blocklist) or caching (ttls).

fact-groups : {
 custom-group-name : ["networking.hostname", "ssh"],
}