Merge "Document an example for deleting content from AFS"

doc/source/afs.rst

@@ -152,6 +152,54 @@ superuser::
   bos adduser -server afs01.ord.openstack.org -user $USERNAME.admin
   pts adduser -user $USERNAME.admin -group system:administrators
 
+Deleting Files
+~~~~~~~~~~~~~~
+
+.. note::
+  This is a basic example of write operations for AFS-hosted
+  content, so applies more generally to manually adding or changing
+  files as well. As we semi-regularly get requests to delete
+  subtrees of documentation, this serves as a good demonstration.
+
+First, as a prerequisite, make sure you've followed the `Client
+Configuration`_ and `Adding a Superuser`_ steps for yourself and
+that you know the password for your ``$USERNAME/admin`` kerberos
+principal. Safely authenticate your superuser's principal in a new
+PAG as follows::
+
+  pagsh -c /bin/bash
+  export KRB5CCNAME=FILE:`mktemp`
+  kinit $USERNAME/admin
+  aklog
+
+If this is a potentially destructive change (perhaps you're worried
+you might mistype a deletion and remove more content than you
+intended) you can first create a copy-on-write backup snapshot like
+so::
+
+  vos backup docs
+
+When deleting files, note that you should use the read-write
+``/afs/.openstack.org`` path rather than the read-only
+``/afs/openstack.org`` path, but normal Unix file manipulation
+commands work as expected (do _not_ use ``sudo`` for this)::
+
+  rm -rf /afs/.openstack.org/docs/project-install-guide/baremetal/draft
+
+If you don't want to have to wait for a volume release to happen (so
+that your changes to the read-write filesystem are reflected
+immediately in the read-only filesystem), you can release it now
+too::
+
+  vos release docs -verbose
+
+Now you can clean up your session, destroy your ticket and exit the
+temporary PAG thusly::
+
+  unlog
+  kdestroy
+  exit
+
 Creating a Volume
 ~~~~~~~~~~~~~~~~~