Provided by: libnet-amazon-s3-tools-perl_0.08-1_all bug

NAME

       s3acl - Display or manipulate the ACL of AWS S3 buckets and items

SYNOPSIS

       s3acl [options] [[bucket|bucket/key] ...]

        Options:
          --access-key    AWS Access Key ID
          --secret-key    AWS Secret Access Key
          --get           Output the ACL to STDOUT
            --xml           in raw XML form instead of parsed form
          --set           Modify the ACL
            --clear                remove all grants from the ACL
            --add grant,grant,...  add grants to the ACL
            --del grant,grant,...  remove matching grants from the ACL
            --xml                  apply the XML ACL from STDIN to the item
            --acl-short cannedacl  apply the "canned" ACL to the item
        Environment:
          AWS_ACCESS_KEY_ID
          AWS_ACCESS_KEY_SECRET

OPTIONS

       --help  Print a brief help message and exits.

       --man   Prints the manual page and exits.

       --verbose
               Output what is being done as it is done.

       --access-key and --secret-key
               Specify the "AWS Access Key Identifiers" for the AWS account.  --access-key is the
               "Access Key ID", and --secret-key is the "Secret Access Key".  These are
               effectively the "username" and "password" to the AWS account, and should be kept
               confidential.

               The access keys MUST be specified, either via these command line parameters, or
               via the AWS_ACCESS_KEY_ID and AWS_ACCESS_KEY_SECRET environment variables.

               Specifying them on the command line overrides the environment variables.

       --secure
               Uses SSL/TLS HTTPS to communicate with the AWS service, instead of HTTP.

       --get   Retreive and display the ACL for each specified bucket or item.

       --xml   When used with the --get option, outputs to stdout the raw XML, instead of parsed
               format.  This raw XML is documented in the "Amazon S3 Developer Guide".

               If more than one bucket or item is specified, the XML ACL for each will be output,
               concatenated together.  This is probably not very useful.

               The raw XML output can be used as input for the --set option, like so:

                 s3acl --get --xml bucketA | s3acl --set --xml bucketB bucketC

               This does not work when specifying more than one bucket or item to the --get
               option, because the concatenation of multiple XML ACLs is not a valid XML ACL.

       --set   Instead of displaying the ACL, modify it.  An ACL can be modified by using
               --clear, --add, and --del, or by using --xml, or by using --acl-short.

       --clear Removes all of the grants from the ACL.  This includes access by the owner of the
               bucket or item.  This is done before the --add or --del options are applied, no
               matter what order options are specified on the command line.

               It is usually accompanied by the --add option to add some grants back to the now
               empty ACL.

       --del   Remove matching grants from the ACL.  This is done before the --add option is
               applied, no matter what order options are specified on the command line.

               Grants are specified in parsed form, and then joined together by commas with no
               whitespace.

               There is an extention to the parsed grant format. If the grantee is specified as
               "ANY", then it matches any and all grantees in the ACL.  If the permission is
               specified as "ANY", then it matches any permission.  Thus

                 s3acl --set --del ANY:READ mybucket

               removes all grants that give READ permission, and

                 s3acl --set --del someuserid:ANY mybucket

               removes all grants to the user someuserid

                 s3acl --set --del ANY:ANY mybucket

               does the same thing as

                 s3acl --set --clear mybucket

               Due to a limitation in the semantics of the S3 API, it is not possible to delete a
               grantee by email address, only by canonical ID.

       --add   Add the specified grants to the ACL.  Grants are specified in parsed form, and
               then joined together by commas with no whitespace.

               It is possible to add the same grant to a bucket or item more than once.  This is
               a surprising behavior of the S3 service.

       --xml   When used with --set, and instead of using <--clear>, <--del>, and --add, read a
               raw XML ACL from STDIN, and then apply it to each given bucket or item.  This will
               completely overwrite the existing ACL for each given bucket or item.

       --acl-short
               Instead of using <--clear>, <--del>, and --add, or using <--xml>, apply a "canned
               ACL" to each given bucket or item.  This will completely overwrite the existing
               ACL for each given bucket or item.

               The following canned ACLs are currently defined by S3:

               private Owner gets "FULL_CONTROL".  No one else has any access rights.  This is
                       the default for newly created buckets and items.

               public-read
                       Owner gets "FULL_CONTROL".  The anonymous principal is granted "READ"
                       access.

               public-read-write
                       Owner gets "FULL_CONTROL".

                       The anonymous principal is granted "READ" and "WRITE" access.  This is a
                       useful policy to apply to a bucket, if you intend for any anonymous user
                       to PUT objects into the bucket.

               authenticated-read
                       Owner gets "FULL_CONTROL" .  Any principal authenticated as a registered
                       Amazon S3 user is granted "READ" access.

       bucket or bucket/key
               One or more bucket names or bucket and key names, specifies an item.  As many as
               possible will be be processed.

               If just a bucket name is given, the ACL for that bucket is retreived or modified.

               If a bucket name and a key, seperated by a slash, is given, the ACL for that key
               in that bucket is retreived or modified.

               If a bucket name begins with one or more dashes, it might be mistaken for a
               command line option.  If this is the case, separate the command line options from
               the bucket or bucket/key names with two dashes, like so:

                 s3acl --get -- --bucketname/keyname

ENVIRONMENT VARIABLES

       AWS_ACCESS_KEY_ID and AWS_ACCESS_KEY_SECRET
               Specify the "AWS Access Key Identifiers" for the AWS account.  AWS_ACCESS_KEY_ID
               contains the "Access Key ID", and AWS_ACCESS_KEY_SECRET contains the "Secret
               Access Key".  These are effectively the "username" and "password" to the AWS
               service, and should be kept confidential.

               The access keys MUST be specified, either via these environment variables, or via
               the --access-key and --secret-key command line parameters.

               If the command line parameters are set, they override these environment variables.

CONFIGURATION FILE

       The configuration options will be read from the file "~/.s3-tools" if it exists.  The
       format is the same as the command line options with one option per line.  For example, the
       file could contain:

           --access-key <AWS access key>
           --secret-key <AWS secret key>
           --secure

       This example configuration file would specify the AWS access keys and that a secure
       connection using HTTPS should be used for all communications.

DESCRIPTION

       Retrieves and outputs the Access Control List (ACL) of buckets and of items in buckets in
       the Amazon Simple Storage Service (S3).

   Principals
       (Much of the following text is taken from the "Amazon S3 Developer Guide (API Version
       2006-03-01)".)

       Every bucket and item has an Access Control List (ACL). When a request is made, S3
       determines the principal making the request, and then checks the access control list to
       see if that principal is authorized to make the request. If the ACL contains an entry
       authorizing that principal to make this request, the request is allowed to proceed,
       otherwise an error is returned.

       A principal may be someone with an AWS S3 account who has logged in, or "authenticated".
       The principal might be the creator and owner of the bucket or item.  Or the principal
       might be some anonymous web browser out on the internet.

   ACL is sequence of grants. A grant is 1 grantee and 1 permission.
       An access control list is a sequence of grants. It may contain up to 100 grants. A grant
       is composed of one grantee, which is a description of the principal who will be allowed
       access, and one permission, which is a description of what that principal is allowed to do
       with that bucket or item.

   User Grantee
       A user grantee must be registered as an Amazon.com customer, but does not have to be
       registered as an AWS customer.

       When an ACL is read, the user grantee will be displayed in a canonical format, which
       consists of 64 hex characters.  The exception is if the grantee is the owner.  Amazon
       still stores and returns the grantee in canonical form, but this tool displays it as
       "OWNER".

   Group Grantee
       The only groups available are those pre-defined by S3.  In the current release of S3, you
       cannot create your own group.  There are currently two pre-defined groups.

       The first is represented by the string "WORLD" by this tool. All principals, whether they
       are anonymous or authenticated, are considered part of this group.

       The second is represented by the string "USERS" by this tool.  Every non-anonymous
       principal is considered part of the group. Note that permission granted by virtue of this
       grant does not trump other access control considerations. For example, if a user is
       registered with AWS, they may be part of this group, but if they have not subscribed to
       S3, they will still not be granted access.

       There is also a special pseudo group with the string "ANY".  It is used by the --del
       option to match against a ACL item to select for deletion.

       If Amazon updates S3 to define any additional groups before this tool is updated, they
       will be represented as a URI surrounded by angle brackets.

   Owner
       Every bucket and item in S3 has an owner attribute associated with it. The owner the user
       that created the bucket or item. The only way to change the owner of a bucket is to delete
       the bucket and create it again under a different user identity. The only way to change the
       owner of an item is to overwrite the item using a different identity.

       The owner of a bucket or item is subject to the access control policy of that bucket or
       item just like everybody else, with two notable exceptions: The owner of a resource always
       has the ability to read and write the ACL of that resource, no matter what the associated
       ACL says. For example, as the owner of an item, you could remove yourself from the
       associated access control list, and find that you can no longer read the item's data and
       metadata. However, by virtue of being owner, you always have the right to re-grant
       yourself permissions to it. This policy prevents the situation where an item becomes
       "stranded," with nobody able to ever modify or even delete it.

   Permissions
       The permission in a grant describes the type of access to be granted to the respective
       grantee. The following permissions are supported:

       READ    When applied to a bucket, this grants permission to list the bucket. When applied
               to an item, this grants permission to read the item data and/or metadata.

       WRITE   When applied to a bucket, this grants permission to create, overwrite, and delete
               any item in the bucket. This permission is not supported for items (it is reserved
               for future use).

       READ_ACP
               Grants permission to read the access control policy (ACL and owner) for the
               applicable bucket or item. The owner of a bucket or item always has this
               permission implicitly.

       WRITE_ACP
               Grants permission to overwrite the ACP for the applicable bucket or item. The
               owner of a bucket or item always has this permission implicitly. Note that
               granting this permission is equivalent to granting FULL_CONTROL, because the grant
               recipient can now make any whatever changes to the ACP he or she likes!

       FULL_CONTROL
               This permission is short-hand for the union of READ, WRITE, READ_ACP, and
               WRITE_ACP permissions. It does not convey additional rights, and is provided only
               for convenience.  It is probably unwise to give this permission to WORLD.

       ANY     This is not really a permission, but is used by the --del option.  It matches any
               permission to select a grant for deletion.

   Default ACL
       If no ACL is provided at the time a bucket is created or an item written then a default
       ACL is created. The default ACL for new resources consists of a single grant that gives
       the owner of the resource (i.e. the principal making the request to create the bucket or
       to write the item) FULL_CONTROL permission. Note that if you overwrite an existing item,
       the ACL for the existing item is always overwritten as well, and defaulted back to
       OWNER:FULL_CONTROL if no explicit ACL is provided.

   Raw XML ACL Format
       The XML ACL format is documented in the "Amazon S3 Developer Guide".

   Parsed ACL Format
       This tool parses the raw XML ACL format into a more readable form.

       A parsed ACL consists of several lines.  Comments are lines that begin with a hash
       character.  Lines that are not comments are grants.

       For buckets, the comments give the bucket name, and the Amazon canonical user string for
       the owner.

       For items, the comments give the bucket name, the item key, and the Amazon canonical user
       string for the owner.

       A grant is grantee string and a permission string, seperated with a colon character.  A
       grantee can be one of the strings "OWNER", "WORLD", or "USERS", or a URI wrapped in angle
       brackets, or the email address of an Amazon user, or a Amazon canonical user string, which
       is 64 hex characters.  A permission is one of the strings "READ", "WRITE", "READ_ACP",
       "WRITE_ACP", or "FULL_CONTROL".

         $ ./s3getacl example
         # bucket: example
         # owner: 5a1568e09392dad4b4ceb54f29f0a64d651a531350d6f720fbd2367eed995f08
         OWNER:FULL_CONTROL
         a00490decea9d0ad76e5ef8b450b3efa63861adccfb9197cfb42f837eb222df2:WRITE
         USERS:READ
         WORLD:READ
         $ ./s3getacl example/thingee
         # bucket: example
         # item: thingee
         # owner: 5a1568e09392dad4b4ceb54f29f0a64d651a531350d6f720fbd2367eed995f08
         OWNER:FULL_CONTROL
         $ _

BUGS

       Report bugs to Mark Atwood mark@fallenpegasus.com.

       Occasionally the S3 service will randomly fail for no externally apparent reason.  When
       that happens, this tool should retry, with a delay and a backoff.

       Access to the S3 service can be authenticated with a X.509 certificate, instead of via the
       "AWS Access Key Identifiers".  This tool should support that.

       It might be useful to be able to specify the "AWS Access Key Identifiers" in the user's
       "~/.netrc" file.  This tool should support that.

       Errors and warnings are very "Perl-ish", and can be confusing.

       Trying to access a bucket or item that does not exist or is not accessable by the user
       generates less than helpful error messages.

       Net::Amazon::S3 already uses XML::LibXML and XML::LibXML::XPathContext, so this tool
       should use those instead of using XML::Writer, to have fewer module dependences.

       It is possible to add the same grant to a bucket or item more than once.  This is a
       surprising behavior of the S3 service.  Both identical grants will be removed by using the
       --del option.

       Due to a limitation in the semantics of the S3 API, it is not possible to delete a grantee
       by email address, only by canonical ID.

AUTHOR

       Written by Mark Atwood mark@fallenpegasus.com.

       Many thanks to Wotan LLC <http://wotanllc.com>, for supporting the development of these S3
       tools.

       Many thanks to the Amazon AWS engineers for developing S3.

SEE ALSO

       These tools use the Net::Amazon:S3 Perl module.

       The Amazon Simple Storage Service (S3) is documented at <http://aws.amazon.com/s3>.