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
-Rackspace architecture -- actually from a few existing auth systems --
-and is therefore a bit disjointed. The distilled points about it are:
+The auth system for Swift is loosely based on the auth system from the existing
+Rackspace architecture -- actually from a few existing auth systems -- and is
+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
-token, the auth system responds with a session TTL and overall expiration in
-seconds from now. Swift does not honor the session TTL but will cache the
-token up to the expiration time. Tokens can be purged through a call to the
-auth system.
+Swift will make calls to the external auth system, giving the auth token to be
+validated. For a valid token, the auth system responds with an overall
+expiration in seconds from now. Swift will cache the token up to the expiration
+time. The included devauth also has the concept of admin and non-admin users
+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
-your own auth.
+swift/common/middleware/auth.py, and should be a good starting place for
+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 auth server makes ReST calls to the Swift cluster's account servers
-      to create a new account on its end.
+    * The developer makes a ReST call to create a new user.
+    * If the account for the user does not yet exist, the auth server makes
+      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)