fixups for ipv6 memcache_servers docs

Change-Id: I20d91c1e276014eaf210fa9eb43788bc17f4e8df

doc/manpages/proxy-server.conf.5

@@ -384,7 +384,8 @@ Sets the maximum number of connections to each memcached server per worker.
 If not set in the configuration file, the value for memcache_servers will be
 read from /etc/swift/memcache.conf (see memcache.conf-sample) or lacking that
 file, it will default to 127.0.0.1:11211. You can specify multiple servers
-separated with commas, as in: 10.1.2.3:11211,10.1.2.4:11211.
+separated with commas, as in: 10.1.2.3:11211,10.1.2.4:11211.  (IPv6
+addresses must follow rfc3986 section-3.2.2, i.e. [::1]:11211)
 .IP \fBmemcache_serialization_support\fR
 This sets how memcache values are serialized and deserialized:
 .RE

doc/source/deployment_guide.rst

@@ -1278,7 +1278,8 @@ object_chunk_size             65536            Chunk size to read from
 client_chunk_size             65536            Chunk size to read from
                                                clients
 memcache_servers              127.0.0.1:11211  Comma separated list of
-                                               memcached servers ip:port
+                                               memcached servers
+                                               ip:port or [ipv6addr]:port
 memcache_max_connections      2                Max number of connections to
                                                each memcached server per
                                                worker

etc/memcache.conf-sample

@@ -2,6 +2,7 @@
 # You can use this single conf file instead of having memcache_servers set in
 # several other conf files under [filter:cache] for example. You can specify
 # multiple servers separated with commas, as in: 10.1.2.3:11211,10.1.2.4:11211
+# (IPv6 addresses must follow rfc3986 section-3.2.2, i.e. [::1]:11211)
 # memcache_servers = 127.0.0.1:11211
 #
 # Sets how memcache values are serialized and deserialized:

etc/proxy-server.conf-sample

@@ -388,7 +388,8 @@ use = egg:swift#memcache
 # If not set here, the value for memcache_servers will be read from
 # memcache.conf (see memcache.conf-sample) or lacking that file, it will
 # default to the value below. You can specify multiple servers separated with
-# commas, as in: 10.1.2.3:11211,10.1.2.4:11211
+# commas, as in: 10.1.2.3:11211,10.1.2.4:11211 (IPv6 addresses must
+# follow rfc3986 section-3.2.2, i.e. [::1]:11211)
 # memcache_servers = 127.0.0.1:11211
 #
 # Sets how memcache values are serialized and deserialized:

swift/common/memcached.py

@@ -108,15 +108,16 @@ class MemcacheConnPool(Pool):
     The *server* parameter can be a hostname, an IPv4 address, or an IPv6
     address with an optional port. If an IPv6 address is specified it **must**
     be enclosed in [], like *[::1]* or *[::1]:11211*. This follows the accepted
-    prescription for IPv6 host literals:
-    https://tools.ietf.org/html/rfc3986#section-3.2.2.
+    prescription for `IPv6 host literals`_.
 
-    Examples:
+    Examples::
 
-        * memcache.local:11211
-        * 127.0.0.1:11211
-        * [::1]:11211
-        * [::1]
+        memcache.local:11211
+        127.0.0.1:11211
+        [::1]:11211
+        [::1]
+
+    .. _IPv6 host literals: https://tools.ietf.org/html/rfc3986#section-3.2.2
     """
     IPV6_RE = re.compile("^\[(?P<address>.*)\](:(?P<port>[0-9]+))?$")