Client

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

Configuration files are parsed by pullconfd according to these rules:

• only files in $PULLCONF_RESOURCE_DIR are parsed.
• this directory may contain subdirectories that can be nested up to ten levels.
• in this directory files and subdirectories starting with a dot are ignored, only files ending with a .yaml or .yml extension are parsed. This enables the usage of git or other version control software.
• files may contain one or more StrictYAML documents. Every document is expected to define either a client or a group.

For example one straightforward way to manage configuration files in a small environment is to create one file per client in a subdirectory such as $PULLCONF_RESOURCE_DIR/clients. The files in this directory could be named after the clients they define. Thus a client with the hostname blechkiste.local would be defined in the file $PULLCONF_RESOURCE_DIR/clients/blechkiste.local.yaml.

The following structure defines a client inside a StrictYAML document:

---
# Tells pullconfd to parse this document as a client.
type: client

# A hostname such as "blechkiste.local".
name: <...>

# The sha256 hash of the client API key.
api_key: <...>

# A list of groups that the client is assigned to.
groups: [...]

# A hash of variables that can be used inside resource definitions.
variables: {...}

# A list of resources.
resources: [...]

• name:

  Client hostnames must adhere to these rules:

  • 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

• api_key:

  The API key corresponds to the sha256 hash of the environment variable $PULLCONF_API_KEY that is provided to pullconf. See client installation for more information.

• groups:

  Optional: A list of group names. By assigning the client to a group it inherits all resources from that group. Every group names in this array must match an existing group.

• variables:

  Optional: A hash of variables that are relevant in the context of this client. See the section on variables on details how to use variables inside resource definitions.

• resources:

  Optional: A list of resources. Resources inherited from groups will be merged with resources listed here and then evaluated in the context of this client (using the variables above).

After defining at least the bare minimum (type, name and api_key) the file can be saved and the server reloaded:

sudo systemctl reload pullconfd.service

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

Multiple documents per file

As mentioned earlier the StrictYAML parser parses every YAML document inside a configuration file. Thus it is also possible to define multiple clients in a single file using documents.

---

type: client
name: blechkiste
api_key: 20b5094257d70c8d126cf278510b6443d5139e86e18be1389b90a28d526c8236
<...>

---

type: client
name: blechbuechse
api_key: e858777f14b11e7c2eb6f60032fbb6b943a54a2011b5ad43b3ad6f0c6557d2bb
<...>

---

type: client
<...>

Example

The following is a simple and short example of a client configuration file.

# $PULLCONF_RESOURCE_DIR/clients/blechkiste.local.yaml
---
type: client
name: blechkiste.local
api_key: 50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c

groups:
  - linux
  - debian
  - nginx
  - ssh

variables:
  ip_address: 192.168.1.55
  logrotate-dir: /etc/logrotate.d

resources:
  - type: host
    parameters:
	  ensure: present
	  ip_address: ${pullconf::ip_address}
	  hostname: ${pullconf::hostname}
	  aliases:
	    - webserver
	    - webserver.local

  - type: file
    parameters:
	  ensure: present
	  path: ${pullconf::logrotate-dir}/apt
	  content:
	    value: |
          /var/log/apt/term.log {
            rotate 12
            monthly
            compress
            missingok
            notifempty
          }

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