Ian Wienand 882b730fdf Update to openstackdocstheme

This modernises the openstack-infra documentation by switching to
openstackdocstheme.  Update dependencies as required.

To remove non-relevant stuff from conf.py, I have just taken the demo
file from openstackdocstheme and lightly modified it.

It seems later sphinx has included it's own ":file:" role which now
conflicts.  Change it it ":cgit_file:" in our documentation.  Remove
the custom header template which no longer applies.  Add the
post-2.0-pbr sphinx-based warning-as-error, which fixes the original
problem that I actually noticed that errors could slip through the
gate tests :)

Change-Id: Ic7bec57b971bb4c75fc839e7269d1f69a576b85c

2018-06-25 11:19:43 +10:00

5.0 KiB

Raw Blame History

title: Kerberos

Kerberos

Kerberos is a computer network authentication protocol which works on the basis of 'tickets' to allow nodes communicating over a non-secure network to prove their identity to one another in a secure manner. It is the basis for authentication to AFS.

At a Glance

Hosts

kdc*.openstack.org

Puppet

Projects

http://web.mit.edu/kerberos

Bugs

Resources

OpenStack Realm

OpenStack runs a Kerberos Realm called OPENSTACK.ORG. The realm contains a Key Distribution Center or KDC which is spread across a master and a slave, as well as an admin server which only runs on the master. Most of the configuration is in puppet, but initial setup and the management of user accounts, known as principals, are manual tasks.

Realm Creation

On the first KDC host, the admin needs to run krb5_newrealm by hand. Then admin principals and host principles need to be set up.

Set up host principals for slave propogation:

# execute kadmin.local then run these commands
addprinc -randkey host/kdc01.openstack.org
addprinc -randkey host/kdc04.openstack.org
ktadd host/kdc01.openstack.org
ktadd host/kdc04.openstack.org

Copy the file /etc/krb5.keytab to the second kdc host.

The puppet config sets up slave propagation scripts and cron jobs to run them.

Adding A User Principal

First, ensure the user has an entry in puppet so they have a unix shell account on our hosts. SSH access is not necessary, but keeping track of usernames and uids with account entries is necessary.

Then, add the user to Kerberos using kadmin (while authenticated as a kerberos admin) or kadmin.local on the kdc:

kadmin: addprinc $USERNAME@OPENSTACK.ORG

Where $USERNAME is the lower-case username of their unix account in puppet. OPENSTACK.ORG should be capitalized.

If you are adding an admin principal, use username/admin@OPENSTACK.ORG. Admins should additionally have regular user principals.

Adding A Service Principal

A service principal is one that corresponds to an application rather than a person. There is no difference in their implementation, only in conventions around how they are created and used. Service principals are created without passwords and keytab files are used instead for authentication. The program k5start can use keytab files to automatically obtain kerberos credentials (and AFS if needed).

Add the service principal to Kerberos using kadmin (while authenticated as a kerberos admin) or kadmin.local on the kdc:

kadmin: addprinc -randkey service/$NAME@OPENSTACK.ORG

Where $NAME is the lower-case name of the service. OPENSTACK.ORG should be capitalized.

Then save the principal's keytab:

kadmin: ktadd -k /path/to/$NAME.keytab service/$NAME@OPENSTACK.ORG

Resetting A User Principal's Password

If you've forgotten your user password (it happens!) then from a shell on one of the KDCs, execute sudo kadmin.local and use the cpw $USERNAME@OPENSTACK.ORG command and enter your new password twice as prompted. If you need to reset your admin principal, use cpw $USERNAME/admin@OPENSTACK.ORG instead.

No Service Outage Server Maintenance

Should you need perform maintenance on the kerberos server that requires taking kerberos processes offline you can do this by performing your updates on a single server at a time.

kdc01.openstack.org is our primary server and kdc04.openstack.org is the hot standby. Perform your maintenance on kdc04.openstack.org first. Then once that is done we can prepare for taking down the primary. On kdc01.openstack.org run:

root@kdc01:~# /usr/local/bin/run-kprop.sh

You should see:

Database propagation to kdc04.openstack.org: SUCCEEDED

Once this is done the standby server is ready and we can take kdc01 offline. When kdc01 is back online rerun run-kprop.sh to ensure everything is working again.

DNS Entries

Kerberos uses the following DNS entries:

_kpasswd._udp.openstack.org.         300 IN SRV 0 0 464 kdc01.openstack.org.
_kerberos-adm._tcp.openstack.org.    300 IN SRV 0 0 749 kdc01.openstack.org.
_kerberos-master._udp.openstack.org. 300 IN SRV 0 0 88 kdc01.openstack.org.
_kerberos._udp.openstack.org.        300 IN SRV 0 0 88 kdc04.openstack.org.
_kerberos._udp.openstack.org.        300 IN SRV 0 0 88 kdc01.openstack.org.
_kerberos.openstack.org.             300 IN TXT "OPENSTACK.ORG"

Be sure to update them if kdc servers change. We also maintain a CNAME for convenience which points to the master kdc:

kdc.openstack.org. 300 IN CNAME kdc01.openstack.org.

5.0 KiB Raw Blame History