Merge "Update README."

README.md

@@ -4,6 +4,14 @@ Swift3
 Swift3 Middleware for OpenStack Swift, allowing access to OpenStack
 swift via the Amazon S3 API.
 
+Features
+-------
+ - Support AWS Signature Version 2 (Version 4 is not ready)
+ - Support Services APIs (GET)
+ - Support Bucket APIs (GET/PUT/DELETE/HEAD)
+ - Support Object APIs (GET/PUT/DELETE/HEAD)
+ - Support Multipart Upload (required **SLO** middleware support)
+ - Support S3 ACL (**under development**)
 
 Install
 -------
@@ -25,6 +33,12 @@ If you use tempauth:
         [pipeline:main]
         pipeline = catch_errors cache swift3 tempauth proxy-server
 
+    To support Multipart Upload::
+
+        [pipeline:main]
+        pipeline = catch_errors cache swift3 tempauth slo proxy-server
+
+
 If you use keystone:
 
     Was::
@@ -37,6 +51,11 @@ If you use keystone:
         [pipeline:main]
         pipeline = catch_errors cache swift3 s3token authtoken keystoneauth proxy-server
 
+    To support Multipart Upload::
+
+        [pipeline:main]
+        pipeline = catch_errors cache swift3 s3token authtoken keystoneauth slo proxy-server
+
 Note that swift3 explicitly checks that keystoneauth is in the pipeline.  You must use this name
 in the pipeline statement and in [filter:keystoneauth] section header.
 
@@ -52,3 +71,77 @@ You also need to add the following if you use keystone (adjust port, host, proto
     auth_port = 35357
     auth_host = 127.0.0.1
     auth_protocol = http
+
+
+4) Swift3 config options:
+
+ You can find a proxy config example in `swift3/etc/proxy-server.conf-sample`.
+
+    # Swift has no concept of the S3's resource owner; the resources
+    # (i.e. containers and objects) created via the Swift API have no owner
+    # information. This option specifies how the swift3 middleware handles them
+    # with the S3 API.  If this option is 'false', such kinds of resources will be
+    # invisible and no users can access them with the S3 API.  If set to 'true',
+    # the resource without owner is belong to everyone and everyone can access it
+    # with the S3 API.  If you care about S3 compatibility, set 'false' here.  This
+    # option makes sense only when the s3_acl option is set to 'true' and your
+    # Swift cluster has the resources created via the Swift API.
+    allow_no_owner = false
+
+    # Set a region name of your Swift cluster.  Note that Swift3 doesn't choose a
+    # region of the newly created bucket actually.  This value is used only for the
+    # GET Bucket location API.
+    location = US
+
+    # Set the default maximum number of objects returned in the GET Bucket
+    # response.
+    max_bucket_listing = 1000
+
+    # Set the maximum number of objects we can delete with the Multi-Object Delete
+    # operation.
+    max_multi_delete_objects = 1000
+
+    # If set to 'true', Swift3 uses its own metadata for ACL
+    # (e.g. X-Container-Sysmeta-Swift3-Acl) to achieve the best S3 compatibility.
+    # If set to 'false', Swift3 tries to use Swift ACL (e.g. X-Container-Read)
+    # instead of S3 ACL as far as possible.  If you want to keep backward
+    # compatibility with Swift3 1.7 or earlier, set false here
+    # If set to 'false' after set to 'true' and put some container/object,
+    # all users will be able to access container/object.
+    # Note that s3_acl doesn't keep the acl consistency between S3 API and Swift
+    # API. (e.g. when set s3acl to true and PUT acl, we won't get the acl
+    # information via Swift API at all and the acl won't be applied against to
+    # Swift API even if it is for a bucket currently supported.)
+    # Note that s3_acl currently supports only keystone and tempauth.
+    # DON'T USE THIS for production before enough testing for your use cases.
+    # This stuff is still under development and it might cause something
+    # you don't expect.
+    s3_acl = false
+
+    # Specify a host name of your Swift cluster.  This enables virtual-hosted style
+    # requests.
+    storage_domain =
+
+
+Functional and Unit Tests
+-------------------------
+We provide functional/unit tests to make swift3 middleware more stable.
+
+    For Ubuntu 12.04
+    $ sudo apt-get install python-dev python-pip libffi-dev libssl-dev libxml2-dev libxslt1-dev
+    $ sudo pip install tox
+
+    # Run unit tests with Python 2.7
+    $ tox -e py27
+
+    # Run functional tests with tempauth
+    $ tox -e tempauth
+
+    # Run functional tests with s3token, keystoneauth and keystone
+    $ tox -e keystone
+
+    # Run all tests
+    $ tox
+
+    # For developer, please run unit tests and syntax check tests before summit path
+    $ tox -e pylint -e pep8 -e py27