Doc fixes and updates

doc/source/auth.rst

@@ -4,7 +4,7 @@
 Developer's Authorization
 *************************
 
-.. _auth-server:
+.. _auth_server:
 
 Auth Server
 ===========

doc/source/overview_auth.rst

@@ -6,9 +6,9 @@ The Auth System
 Developer Auth
 --------------
 
-The auth system for Swift is based on the auth system from the existing
+The auth system for Swift is loosely based on the auth system from the existing
-Rackspace architecture -- actually from a few existing auth systems --
+Rackspace architecture -- actually from a few existing auth systems -- and is
-and is therefore a bit disjointed. The distilled points about it are:
+therefore a bit disjointed. The distilled points about it are:
 
 * The authentication/authorization part is outside Swift itself
 * The user of Swift passes in an auth token with each request
@@ -23,13 +23,16 @@ of something unique, some use "something else" but the salient point is that
 the token is a string which can be sent as-is back to the auth system for
 validation.
 
-An auth call is given the auth token and the Swift account hash. For a valid
+Swift will make calls to the external auth system, giving the auth token to be
-token, the auth system responds with a session TTL and overall expiration in
+validated. For a valid token, the auth system responds with an overall
-seconds from now. Swift does not honor the session TTL but will cache the
+expiration in seconds from now. Swift will cache the token up to the expiration
-token up to the expiration time. Tokens can be purged through a call to the
+time. The included devauth also has the concept of admin and non-admin users
-auth system.
+within an account. Admin users can do anything within the account. Non-admin
+users can only perform operations per container based on the container's
+X-Container-Read and X-Container-Write ACLs. For more information on ACLs, see
+:mod:`swift.common.middleware.acl`
 
-The user starts a session by sending a ReST request to that auth system
+The user starts a session by sending a ReST request to the external auth system
 to receive the auth token and a URL to the Swift system.
 
 --------------
@@ -40,8 +43,10 @@ Auth is written as wsgi middleware, so implementing your own auth is as easy
 as writing new wsgi middleware, and plugging it in to the proxy server.
 
 The current middleware is implemented in the DevAuthMiddleware class in
-swift/common/auth.py, and should be a good starting place for implemeting
+swift/common/middleware/auth.py, and should be a good starting place for
-your own auth.
+implementing your own auth.
+
+Also, see :doc:`development_auth`.
 
 ------------------
 History and Future

swift/auth/server.py

@@ -65,11 +65,12 @@ class AuthController(object):
       the token.
     * The Swift cluster completes the user's request.
 
-    Another use case is creating a new account:
+    Another use case is creating a new user:
 
-    * The developer makes a ReST call to create a new account.
+    * The developer makes a ReST call to create a new user.
-    * The auth server makes ReST calls to the Swift cluster's account servers
+    * If the account for the user does not yet exist, the auth server makes
-      to create a new account on its end.
+      ReST calls to the Swift cluster's account servers to create a new account
+      on its end.
     * The auth server records the information in its database.
 
     A last use case is recreating existing accounts; this is really only useful
@@ -261,6 +262,9 @@ class AuthController(object):
         cluster while still supporting old accounts going to the Swift clusters
         they were created on.
 
+        Currently, updating a user's information (password, admin access) must
+        be done by directly updating the sqlite database.
+
         :param account: The name for the new account
         :param user: The name for the new user
         :param password: The password for the new account
@@ -334,7 +338,7 @@ class AuthController(object):
 
     def handle_token(self, request):
         """
-        Hanles ReST request from Swift to validate tokens
+        Handles ReST requests from Swift to validate tokens
 
         Valid URL paths:
             * GET /token/<token>

swift/common/client.py

@@ -626,12 +626,12 @@ def put_object(url, token, container, name, contents, content_length=None,
 
 def post_object(url, token, container, name, headers, http_conn=None):
     """
-    Change object metadata
+    Update object metadata
 
     :param url: storage URL
     :param token: auth token
     :param container: container name that the object is in
-    :param name: object name to change
+    :param name: name of the object to update
     :param headers: additional headers to include in the request
     :param http_conn: HTTP connection object (If None, it will create the
                       conn object)