From a84488f4a9b939c33600483832729b5c484149bd Mon Sep 17 00:00:00 2001 From: Ian Wienand Date: Tue, 4 Apr 2017 09:22:08 +1000 Subject: [PATCH] Updates to adding mirror documentation Add some more details and enhance some formatting around adding new mirror volumes. Change-Id: I1c8c9432fe0f96bd6be659bdc6facebaf35eb915 --- doc/source/afs.rst | 46 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 37 insertions(+), 9 deletions(-) diff --git a/doc/source/afs.rst b/doc/source/afs.rst index 8599d555d5..9a507ccc53 100644 --- a/doc/source/afs.rst +++ b/doc/source/afs.rst @@ -76,6 +76,7 @@ site with a read-only volume is online, it will be available. Client Configuration -------------------- +.. _afs_client: To use OpenAFS on a Debian or Ubuntu machine:: @@ -214,6 +215,11 @@ system from a region-wide outage. In order to establish a new mirror, do the following: +* The following commands need to be run authenticated on a host with + kerberos and AFS setup (see `afs_client`_; admins can run the + commands on ``mirror-update.openstack.org``). Firstly ``kinit`` and + ``aklog`` to get tokens. + * Create the mirror volume. See `Creating a Volume`_ for details. The volume should be named ``mirror.foo``, where `foo` is descriptive of the contents of the mirror. Example:: @@ -247,9 +253,9 @@ point is composed of read-only volumes:: /mirror [mirror] /bar [mirror.bar] -In order to mount the mirror.foo volume under ``mirror`` we need to -modify the read-write version of the ``mirror`` volume. To make this -easy, the read-write version of the cell root is mounted at +In order to mount the ``mirror.foo`` volume under ``mirror`` we need +to modify the read-write version of the ``mirror`` volume. To make +this easy, the read-write version of the cell root is mounted at ``/afs/.openstack.org``. Folllowing the same logic from earlier, traversing to paths below that mount point will generally prefer read-write volumes. @@ -271,7 +277,25 @@ read-write volumes. kadmin: addprinc -randkey service/foo-mirror@OPENSTACK.ORG kadmin: ktadd -k /path/to/foo.keytab service/foo-mirror@OPENSTACK.ORG -* Add the service principal's keytab to hiera. +* Add the service principal's keytab to hiera. Copy the binary key to + ``puppetmaster.openstack.org`` and then use ``hieraedit`` to update + the files + + .. code-block:: console + + root@puppetmaster:~# /opt/system-config/production/tools/hieraedit.py \ + --yaml /etc/puppet/hieradata/production/fqdn/mirror-update.openstack.org.yaml \ + -f /path/to/foo.keytab KEYNAME + + (don't forget to ``git commit`` and save the change; you can remove + the copies of the binary key too). The key will be base64 encoded + in the heira database. If you need to examine it for some reason + you can use ``base64``:: + + cat /path/to/foo.keytab | base64 + +* Add the new key to ``mirror-update.openstack.org`` in + ``manifests/site.pp`` for the mirror scripts to use during update. * Create an AFS user for the service principal:: @@ -309,17 +333,21 @@ membership if our needs change. Because the initial replication may take more time than we allocate in our mirror update cron jobs, manually perform the first mirror update: -* In screen, obtain the lock on mirror-update.openstack.org:: +* In screen, obtain the lock on ``mirror-update.openstack.org``:: flock -n /var/run/foo-mirror/mirror.lock bash Leave that running while you perform the rest of the steps. -* Also in screen on mirror-update, run the initial mirror sync. +* Also in screen on ``mirror-update``, run the initial mirror sync. + If using one of the mirror update scripts (from ``/usr/local/bin``) + be aware that they generally run the update process under + ``timeout`` with shorter periods than may be required for the + initial full sync. -* Log into afs01.dfw.openstack.org and run screen. Within that - session, periodically during the sync, and once again after it is - complete, run:: +* Log into ``afs01.dfw.openstack.org`` and run ``screen``. Within + that session, periodically during the sync, and once again after it + is complete, run:: vos release mirror.foo -localauth