- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with krb5keytab
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
This module generates Kerberos keytabs for hosts (manages the /etc/krb5.keytab file) without the need to place a Kerberos administrator credential on the host. It has been extended to manage additional Kerberos principals and keytabs (e.g. for applications).
This module was developed for, and tested with, MIT Kerberos and OpenLDAP on CentOS 6.
This module uses custom functions to create the principal and download the keytab on the puppet master, and hiera to store the generated keytabs. The design of this process eliminates the need to call exec{} with a Kerberos administrative credential on every host.
In addition, the module stores the generated keytab file in hiera, so that it is cached for the next run. Some Kerberos implementations (notably MIT) randomize the password each time the keytab is downloaded, so without this feature a new keytab would be generated for each Puppet run. The module is currently able to store the generated key into CouchDB and into a traditional directory/file hiera implementation.
The only file on the target system that is affected is /etc/krb5.keytab, which contains the host's Kerberos principal. This keytab is used to authenticate the host itself to network services - for example, sssd uses this keytab to authenticate the host to the LDAP server.
If you choose to generate a keytab for another user and specify a different path for the keytab, then that keytab (rather than /etc/krb5.keytab) will be affected.
There are numerous assumptions and configuration parameters required to make full use of this module.
-
You need to have OpenLDAP and Kerberos running and working in your environment.
-
You need to have at least one Kerberos administrative principal created, which has (at minimum) the ability to add principals, change passwords, inquire, and list ("clia" in kadm5.acl). We suggest creating a separate principal used only for your Puppet master, e.g.:
puppetmaster@YOUR-REALM.COM
You would place a corresponding entry in the
/var/kerberos/krb5kdc/kadm5.acl
file to grant the privileges:puppetmaster@YOUR-REALM.COM clia
-
You need to have Hiera running. If you want to use the feature of this module that saves newly generated keytabs in hiera for you, then your Hiera can be backed by CouchDB (see https://github.com/crayfishx/hiera-http) or the traditional directory and file system hiera.
krb5keytab is configured with numerous parameters in Hiera and/or parameters passed to the class. Please see the "Usage" section for details.
krb5keytab is configured with numerous parameters in Hiera and/or parameters passed to the class. Parameters passed to the class take precedence over Hiera.
Hiera: krb5keytab::admin-keytab
Parameter to class: admin_keytab
The base64 encoded keytab for the administrative Kerberos principal.
- How to create a keytab file: https://kb.iu.edu/d/aumh#create
- How to base64 encode the keytab:
base64 username.keytab
Example (this is just random data encoded as BASE64):
VQPlowXZxtrKW8sZv3Ehg2T7W+y1jjxzILnOOHM/GHzykphIHXbvMmezZpupLB3wns8/YNPi4CVM
YGe1rWmCZ7hU0SmEdJNQ9/x2nd2j7YudunhVHAsA8lvE32L0TY8VbpQX4d1y0YxaJeMDksE+M17N
JVKiWeQD7o92guSzp1wapzCA08yZJXZV36Uw21U87NgZPhdbhDE/kzeFep5hrxEIXylaQW8zRCGc
LT/l8RjPCFkjXzxn3VKWsaVaaFC2FCDaEMqkFcxcX5UxatnBqcNtlbR0WTNUiAYu9UDdEz1KVGZc
L5Vxbj3dSmsMm8M2peSSoOl3FgSTUFyqJ9xoiOIPbrJz6MkId1oTW31Lal0hmqTAxZLmYCLNEb6y
yB9J5APTNEW1SPKma7rXmmOQtWZuthYsasWRbFdZKsC96h6jVHzX/pngAhxPBPjEyYUkNBeFSO9W
KIpn3f0KXiFt0+i/Y6N5ZmsODf6fzKUFMW24HogjzleqqhUYEiNdpmZKj5f3iP0Lg2PZpmNFeTzO
2tw6VebNZTCc9REw98sh8L4D0OAF5ProTItJNditAg==
Hiera: krb5keytab::admin-principal
Parameter to class: admin_principal
The principal's name of your administrative Kerberos principal.
Example:
puppetmaster@YOUR-REALM.COM
Hiera: krb5keytab::krb5-realm
Parameter to class: krb5_realm
The Kerberos realm. In other words, the (usually capitalized) portion of principal names that come after the "@" sign. This is often part of your domain name.
Example:
YOUR-REALM.COM
Hiera: krb5keytab::hiera-backend
Parameter to class: hiera_backend
The type of Hiera backend you run, so that the module can write keytabs that are generated into that Hiera backend for you. The options available are:
none
(or undefined) -- Do not store generated keytabs in Hierafile
-- Store generated keytabs into a directory structurecouchdb
-- Store generated keytabs into a CouchDB
Note that if you select none
or undefined, the code to generate a keytab will be executed each time a Puppet catalog is compiled for a node. On MIT Kerberos, this
will result in randomization of the keytab for the host every time. This is probably undesirable.
Hiera: krb5keytab::ldap-ou
Parameter to class: ldap_ou
The place in your LDAP tree where Kerberos principals for hosts should be created. (This can be overridden with each call to create a resource.)
Example:
ou=hosts,dc=your-realm,dc=com
Hiera: krb5keytab::krb5-admin-server
Parameter to class: krb5_admin_server
The fully qualified domain name of your Kerberos admin server. This is that server that will be contacted to identify, list, create, and obtain the host principals.
Example:
kerberos1.your-realm.com
The following settings are supported if you set krb5keytab::hiera-backend
= file
Hiera: krb5keytab::hiera-file-dir
Parameter to class: hiera_file_dir
The directory where files are created with the host keytabs (this must exist on the Puppet master). Within this directory, files named ${::fqdn}.yaml
will be created. Each file will have a field named "krb5-keytab" with the BASE64 encoded keytab.
Use a separate subdirectory for this from all of your other Hiera data. This module tries to preserve existing settings, but this cannot be assured.
The following settings are supported if you set krb5keytab::hiera-backend
= couchdb
.
The 'couchrest' gem is required for krb5keytab to write to a CouchDB.
Hiera: krb5keytab::hiera-couchdb-hostname
Parameter to class: hiera_couchdb_hostname
The fully qualified domain name or IP address of your CouchDB server. Defaults to 127.0.0.1.
Hiera: krb5keytab::hiera-couchdb-port
Parameter to class: hiera_couchdb_port
The port number that CouchDB is running on. Defaults to 5984.
Hiera: krb5keytab::hiera-couchdb-database
Parameter to class: hiera_couchdb_database
The database name in which to store generated keytabs. Defaults to "keytabs".
Note: Within that database, a document named after ${::fqdn} will be generated, and therein a field named "krb5-keytab" will be created and populated with the BASE64 encoded kerberos keytab.
Hiera: krb5keytab::hiera-couchdb-username
and krb5keytab::hiera-couchdb-password
Parameter to class: hiera_couchdb_username
and hiera_couchdb_password
If CouchDB has basic authentication turned on, supply the username and password to connect. This account must have the ability to create and update records in the assigned database.
This is a define that can be used to create keytabs for arbitrary principals, including host principals. You should be using this, as opposed to the old host_keytab
class.
A typical define may look like this:
krb5keytab::keytab { "ldap/${::fqdn}":
keytab => '/etc/openldap/krb5.keytab',
keytab_owner => 'root',
keytab_group => 'ldap',
keytab_mode => '0640',
}
The name of the resource should be the name of the principal.
- For a host keytab, this is:
"host/${::fqdn}@YOUR-KERBEROS-REALM.COM"
- You need to specify the full name of the principal, including the realm name (e.g.
some-dude/hostname.yourdomain.com@YOUR-REALM.COM
). If the principal does not have a@
in it, the default kerberos realm will be added -- i.e.,some-dude/hostname.yourdomain.com
will becomesome-dude/hostname.yourdomain.com@YOUR-REALM.COM
automatically. - When specifying the principal you can use
${::facter_fact_name}
which will be replaced by the appropriate facter fact.${::fqdn}
is likely to be particularly useful.
The following parameters are generally useful for this class.
- keytab - Keytab file to write -- use
/etc/krb5.keytab
for the host keytab. This defaults to NULL (i.e. do NOT write a keytab file) if the principal is not the host principal. This is useful behavior if you want to declare that a particular principal exists, but not store its keytab somewhere (Cloudera Manager, for example, requires that a principal exist, but it will pull the keytab itself). If you really want to specify this "NULL" behavior and don't trust the omission of the "keytab" parameter, you can passkeytab => 'none'
to be extra sure. - keytab_owner - Owner of keytab file -- defaults to root
- keytab_group - Group of keytab file -- defaults to root
- keytab_mode - Mode (permissions) of keytab file -- defaults to 0400
- ldap_ou - See krb5keytab::ldap-ou hiera parameter.
- hiera_key - Name of the key to create in Hiera -- defaults to 'krb5-keytab' for host keytabs, and the name of the principal for non-host keytabs. (Certain characters in the name of the principal will be replaced with underscores to avoid breaking YAML.)
Main class to generate and install a host keytab.
This class does not take parameters. The connection and credential parameters for Kerberos are stored in Hiera. The keytab is generated for ${::fqdn}
.
This class is being kept for legacy purposes but should be considered DEPRECATED. You should instead use "krb5keytab::keytab" (which is define-based).
options_hash is a hash containing the following keys:
- admin_principal - Name of the administrative principal. See krb5keytab::admin-principal hiera parameter.
- admin_keytab - The full path to a file containing the administrative keytab.
- ldap_ou - See krb5keytab::ldap-ou hiera parameter.
- admin_server - See krb5keytab::krb5-admin-server hiera parameter.
- realm - See krb5keytab::krb5-realm hiera parameter.
- fqdn - FQDN of the host whose principal is needed.
From this a host principal is built: "host/#{args['fqdn']}@#{args['realm']}"
The "kadmin" command is used to create the principal if needed, and then to retrieve the keytab.
This method returns the content of the keytab (which is binary data).
options_hash is a hash containing the following keys:
- hiera_key - Name of the key to create in Hiera (in our context, "krb5-keytab")
- fqdn - FQDN of the host whose principal is needed.
- hiera_backend - One of 'none', 'files', or 'couchdb'
- hiera_value - Value to write in Hiera (in our context, the BASE64 encoded keytab)
No return value.
Creates a temporary file with the content supplied as the argument.
Returns the path to the temporary file.
- This module was developed on CentOS 6 for OpenLDAP and Kerberos. While we believe that the underlying code will probably work with other flavors of Linux and other implementations of LDAP and Kerberos, this has not been tested.
- Only one principal per keytab file is supported at present.
If you wish to contribute, please submit a pull request. All contributions must be licensed to us under the Apache 2.0 license.
This module was originally developed at Collective, Inc. (http://www.collective.com). We gratefully acknowledge the following contributors:
- Kevin Paulisse (original design and code; expansion from class to define)
- Sarguru Nathan (builds and tests)
- Millie Kim (file backend for Hiera storage)