Display or manipulate the acl of aws s3 buckets and items
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
Print a brief help message and exits.
Prints the manual page and exits.
Output what is being done as it is done.
Specify the \*(L"\s-1AWS\s0 Access Key Identifiers\*(R" for the \s-1AWS\s0 account. --access-key is the \*(L"Access Key \s-1ID\s0\*(R", and --secret-key is the \*(L"Secret Access Key\*(R". These are effectively the \*(L"username\*(R" and \*(L"password\*(R" to the \s-1AWS\s0 account, and should be kept confidential. The access keys \s-1MUST\s0 be specified, either via these command line parameters, or via the \s-1AWS_ACCESS_KEY_ID\s0 and \s-1AWS_ACCESS_KEY_SECRET\s0 environment variables. Specifying them on the command line overrides the environment variables.
Uses \s-1SSL/TLS\s0 \s-1HTTPS\s0 to communicate with the \s-1AWS\s0 service, instead of \s-1HTTP\s0.
Retreive and display the \s-1ACL\s0 for each specified bucket or item.
When used with the --get option, outputs to stdout the raw \s-1XML\s0, instead of parsed format. This raw \s-1XML\s0 is documented in the \*(L"Amazon S3 Developer Guide\*(R". If more than one bucket or item is specified, the \s-1XML\s0 \s-1ACL\s0 for each will be output, concatenated together. This is probably not very useful. The raw \s-1XML\s0 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 \s-1XML\s0 ACLs is not a valid \s-1XML\s0 \s-1ACL\s0.
Instead of displaying the \s-1ACL\s0, modify it. An \s-1ACL\s0 can be modified by using --clear, --add, and --del, or by using --xml, or by using --acl-short.
Removes all of the grants from the \s-1ACL\s0. 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 \s-1ACL\s0.
Remove matching grants from the \s-1ACL\s0. 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 \*(L"\s-1ANY\s0\*(R", then it matches any and all grantees in the \s-1ACL\s0. If the permission is specified as \*(L"\s-1ANY\s0\*(R", then it matches any permission. Thus s3acl --set --del ANY:READ mybucket removes all grants that give \s-1READ\s0 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 \s-1API\s0, it is not possible to delete a grantee by email address, only by canonical \s-1ID\s0.
Add the specified grants to the \s-1ACL\s0. 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.
When used with --set, and instead of using <--clear>, <--del>, and --add, read a raw \s-1XML\s0 \s-1ACL\s0 from \s-1STDIN\s0, and then apply it to each given bucket or item. This will completely overwrite the existing \s-1ACL\s0 for each given bucket or item.
Instead of using <--clear>, <--del>, and --add, or using <--xml>, apply a \*(L"canned \s-1ACL\s0\*(R" to each given bucket or item. This will completely overwrite the existing \s-1ACL\s0 for each given bucket or item. The following canned ACLs are currently defined by S3:
Owner gets \*(C`FULL_CONTROL\*(C'. No one else has any access rights. This is the default for newly created buckets and items.
Owner gets \*(C`FULL_CONTROL\*(C'. The anonymous principal is granted \*(C`READ\*(C' access.
Owner gets \*(C`FULL_CONTROL\*(C'. The anonymous principal is granted \*(C`READ\*(C' and \*(C`WRITE\*(C' access. This is a useful policy to apply to a bucket, if you intend for any anonymous user to \s-1PUT\s0 objects into the bucket.
Owner gets \*(C`FULL_CONTROL\*(C' . Any principal authenticated as a registered Amazon S3 user is granted \*(C`READ\*(C' access.
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 \s-1ACL\s0 for that bucket is retreived or modified. If a bucket name and a key, seperated by a slash, is given, the \s-1ACL\s0 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
Specify the \*(L"\s-1AWS\s0 Access Key Identifiers\*(R" for the \s-1AWS\s0 account. \s-1AWS_ACCESS_KEY_ID\s0 contains the \*(L"Access Key \s-1ID\s0\*(R", and \s-1AWS_ACCESS_KEY_SECRET\s0 contains the \*(L"Secret Access Key\*(R". These are effectively the \*(L"username\*(R" and \*(L"password\*(R" to the \s-1AWS\s0 service, and should be kept confidential. The access keys \s-1MUST\s0 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.
The configuration options will be read from the file \*(C`~/.s3-tools\*(C' 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 \s-1AWS\s0 access keys and that a secure connection using \s-1HTTPS\s0 should be used for all communications.
Retrieves and outputs the Access Control List (\s-1ACL\s0) of buckets and of items in buckets in the Amazon Simple Storage Service (S3).
(Much of the following text is taken from the \*(L"Amazon S3 Developer Guide (\s-1API\s0 Version 2006-03-01)\*(R".)
Every bucket and item has an Access Control List (\s-1ACL\s0). 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 \s-1ACL\s0 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 \s-1AWS\s0 S3 account who has logged in, or \*(L"authenticated\*(R". 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.
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.
A user grantee must be registered as an Amazon.com customer, but does not have to be registered as an \s-1AWS\s0 customer.
When an \s-1ACL\s0 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 \*(L"\s-1OWNER\s0\*(R".
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 \*(L"\s-1WORLD\s0\*(R" by this tool. All principals, whether they are anonymous or authenticated, are considered part of this group.
The second is represented by the string \*(L"\s-1USERS\s0\*(R" 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 \s-1AWS\s0, 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 \*(L"\s-1ANY\s0\*(R". It is used by the --del option to match against a \s-1ACL\s0 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 \s-1URI\s0 surrounded by angle brackets.
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 \s-1ACL\s0 of that resource, no matter what the associated \s-1ACL\s0 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 \*(L"stranded,\*(R" with nobody able to ever modify or even delete it.
The permission in a grant describes the type of access to be granted to the respective grantee. The following permissions are supported:
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.
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).
Grants permission to read the access control policy (\s-1ACL\s0 and owner) for the applicable bucket or item. The owner of a bucket or item always has this permission implicitly.
Grants permission to overwrite the \s-1ACP\s0 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 \s-1FULL_CONTROL\s0, because the grant recipient can now make any whatever changes to the \s-1ACP\s0 he or she likes!
This permission is short-hand for the union of \s-1READ\s0, \s-1WRITE\s0, \s-1READ_ACP\s0, and \s-1WRITE_ACP\s0 permissions. It does not convey additional rights, and is provided only for convenience. It is probably unwise to give this permission to \s-1WORLD\s0.
This is not really a permission, but is used by the --del option. It matches any permission to select a grant for deletion.
If no \s-1ACL\s0 is provided at the time a bucket is created or an item written then a default \s-1ACL\s0 is created. The default \s-1ACL\s0 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) \s-1FULL_CONTROL\s0 permission. Note that if you overwrite an existing item, the \s-1ACL\s0 for the existing item is always overwritten as well, and defaulted back to \s-1OWNER:FULL_CONTROL\s0 if no explicit \s-1ACL\s0 is provided.
The \s-1XML\s0 \s-1ACL\s0 format is documented in the \*(L"Amazon S3 Developer Guide\*(R".
This tool parses the raw \s-1XML\s0 \s-1ACL\s0 format into a more readable form.
A parsed \s-1ACL\s0 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 \*(L"\s-1OWNER\s0\*(R", \*(L"\s-1WORLD\s0\*(R", or \*(L"\s-1USERS\s0\*(R", or a \s-1URI\s0 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 \*(L"\s-1READ\s0\*(R", \*(L"\s-1WRITE\s0\*(R", \*(L"\s-1READ_ACP\s0\*(R", \*(L"\s-1WRITE_ACP\s0\*(R", or \*(L"\s-1FULL_CONTROL\s0\*(R".
$ ./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 $ _
Report bugs to Mark Atwood [email protected].
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 \*(L"\s-1AWS\s0 Access Key Identifiers\*(R". This tool should support that.
It might be useful to be able to specify the \*(L"\s-1AWS\s0 Access Key Identifiers\*(R" in the user's \*(C`~/.netrc\*(C' file. This tool should support that.
Errors and warnings are very \*(L"Perl-ish\*(R", 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 \s-1API\s0, it is not possible to delete a grantee by email address, only by canonical \s-1ID\s0.
Written by Mark Atwood [email protected].
Many thanks to Wotan \s-1LLC\s0 <http://wotanllc.com>, for supporting the development of these S3 tools.
Many thanks to the Amazon \s-1AWS\s0 engineers for developing S3.
These tools use the Net::Amazon:S3 Perl module.
The Amazon Simple Storage Service (S3) is documented at <http://aws.amazon.com/s3>.