Func Authentication
Func uses an X.509 public key infrastructure (PKI) to authenticate the minions to the overlord daemon. These SSL certificates are also used to encrypt and verify all communications.
The certmaster daemon running on the overlord creates a Certificate Authority (CA) when it is first started. This serves as the root of the PKI. As each minion starts it will generate a key pair and a Certificate Signing Request (CSR) which contains its public key. The CSR is uploaded to the overlord. By default, you must use the certmaster-ca tool on the overlord to sign the public key of each minion with the CA. The certmaster may also be configured to automatically sign the CSR as well. The newly created certificate is then retrieved by the minion.
After the minion has its certificate signed by the overlord's CA you can start issuing commands to that host.
Keys are stored in /etc/pki/func for both sides. Certmaster stores certs and csrs in /var/lib/func (and do not need to be protected against unauthorized read access).
Note that the InstallationAndSetupGuide has some instructions for setting Linux ACLs on /etc/pki/func to allow usage of the "func" command line (and Python modules) by non-root users. That is recommended reading.
For more info see Func SSL Details
Func Access Control Lists
In addition to the above, you can edit files on the minion to control what commands various overlord servers can run on them. By default, they can run any plugin installed.
After the certificate is determined to be valid then the common name and hash of the peer certificate are checked in the ACL list. These are normally stored in the /etc/func/minion-acl.d/ directory. Each file should have a .acl extension.
The acl files are of the format:
common_name-certificate_hash = list of methods that can be run
These allow wildcards so, for example:
# Allow the reboot, restart_process, and yum.update commands on all FI hosts. *.fedoraproject.org* = reboot, restart_process, yumcmd.update
Allowed methods can also use wildcards:
# Allow all the Yum methods on FI hosts *.fedoraproject.org* = yumcmd.*
The certificate hash can be generated from the certificate (CERT) of the peer by running the following OpenSSL command:
openssl x509 -noout -in /path/to/hostname.cert -hash
In certmaster version after 0.19, you can also find the certificate hash with certmaster-ca:
certmaster-ca --list-cert-hash
This will output an 8 byte hexadecimal number that you'll need to convert to decimal for the acl file.
On the CLI you can convert hex to decimal using echo $((0x###)) style commands:
# openssl x509 -noout -in sso.fedoraproject.org -hash
e1e9abba
# HEXHASH=$(openssl x509 -noout -in sso.fedoraproject.org -hash)
# echo $((0x${HEXHASH}))
3790187450
Which you could then use in an ACL like this:
# Allow this SSO host to run all Yum methods and all Nagios methods sso.fedorahosted.org-3790187450 = yumcmd.*, nagios.*
Note: On 32bit systems sometimes the hash wraps around the INT_MAX value and becomes negative. For example a hash of 4087767591 on a 64bit system becomes -207188705 on a 32bit minion. Acl's would then need to accomodate both hashes if you have 32bit minions.
Troubleshooting
Some information on troubleshooting certificate registration can be found here. Basically func prefers to have sane DNS and that is the most frequent cause of certificate related problems.
