diff --git a/doc/source/afs.rst b/doc/source/afs.rst
index 29df44d26e..c43dca6f81 100644
--- a/doc/source/afs.rst
+++ b/doc/source/afs.rst
@@ -223,6 +223,27 @@ temporary PAG thusly::
 Creating a Volume
 ~~~~~~~~~~~~~~~~~
 
+..
+   See following for background on the issues
+   http://eavesdrop.openstack.org/irclogs/%23opendev/%23opendev.2020-06-10.log.html#t2020-06-10T22:13:43
+   https://review.opendev.org/#/c/735061/
+
+.. warning::
+
+   You should *not* run these operations on the fileservers where the
+   volumes or replicas are to be created (``afs01`` or ``afs02``).
+   openafs ```vos`` will resolve the ipv4 address of the fileserver
+   host from the command-line.  If you are using the tool on the
+   fileserver, Debuntu's use of ``127.0.1.1`` for localhost and having
+   the hostname in ``/etc/hosts`` can thus result in the ``vos`` tool
+   not correctly filtering the loopback address and setting the server
+   address for the volume as ``127.0.1.1`` -- making it effectively
+   inaccessible.  A similar problem can occur for NAT servers, if we
+   were to use them.  Running on an external host means the lookups
+   shouldn't return local addresses and avoids this issue.  The other
+   option is to specify the fileservers as the IP address, rather than
+   the hostname, to avoid any lookup issues.
+
 Select a fileserver for the read-write copy of the volume according to
 which region you wish to locate it after ensuring it has sufficient
 free space.  Then run::
@@ -372,8 +393,9 @@ 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.opendev.org``).  Firstly ``kinit`` and
-  ``aklog`` to get tokens.
+  commands on ``mirror-update.opendev.org``).  See the note above
+  about *not* doing this on the actual fileservers.  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