Configuration

Client

---

Once pullconf is installed on the client system a client configuration file must be created on the server. This makes the client known to the server and pullconf can successfully connect to pullconfd.

First create a file $PULLCONF_RESOURCE_DIR/clients/$hostname.toml on the server. Here $hostname matches the output from running $ hostname --fqdn on the client.

For instance if

• the fully-qualified domain name of the client is my.example.com and
• $PULLCONF_RESOURCE_DIR uses the default value of /etc/pullconfd/resources (see table)

then the corresponding client configuration file must be created at /etc/pullconfd/resources/clients/my.example.com.toml.

Also note that a valid hostname:

• cannot be an empty string
• cannot be more than 253 characters long
• cannot start with a hyphen -
• cannot contain characters other than [\-a-zA-Z0-9\.]
• cannot have segments that exceed 63 characters: a hostname my.example.com has three distinct segments, my, example and com

Each client configuration file in $PULLCONF_RESOURCE_DIR/clients must adhere to this format in TOML:

	    
api-key = "<string>"
groups = [ "<group>", "<group>" ... ]

[variables]
...

[[resources]]
...

[[resources]]
...
	    
	  

• the api-key string corresponds to the SHA256 hash of the environment variable $PULLCONF_API_KEY on the client. It can be computed like this: $ echo -n "$PULLCONF_API_KEY" | sha256sum

  For example the SHA256 hash of the string example is 50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c.

• [Optional]: groups is an array of the names of groups that the client should be a member of and whose resources the client should inherit.
• [Optional]: [variables] is a table containing variables that can be used inside parameters of resources. See the section on variables for a thorough explanation.
• [Optional]: [[resources]] is a array-of-tables that defines various resources.

After defining at least api-key, save the file and reload the server:

$ sudo systemctl reload pullconfd.service

The next time the pullconf.timer on the client executes pullconf.service, it will successfully connect to pullconfd, because the server is now able to identify the client by means of its API key and hostname.

To get a better sense of the structure of a common client configuration file, refer to the example below.

Example of a configuration file

	    
# general settings
api-key = "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"
groups = [ "linux", "debian", "nginx", "ssh" ]

[variables]
my-ip-address = "192.168.1.55"

# some `host` resource
[[resources]]
type = "host"
ensure = "present"
ip-address = "$pullconf::my-ip-address"
hostname = "$pullconf::hostname"
aliases = [ "webserver.local" ]

# some `file` resource
[[resources]]
type = "file"
ensure = "present"
path = "/etc/logrotate.d/apt"
content = """
/var/log/apt/term.log {
  rotate 12
  monthly
  compress
  missingok
  notifempty
}

/var/log/apt/history.log {
  rotate 12
  monthly
  compress
  missingok
  notifempty
}
"""