s3acl(1p)
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 Retrieve 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 extension 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
retrieved or modified.
If a bucket name and a key, separated by a slash, is given, the
ACL for that key in that bucket is retrieved 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, separated 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 accessible 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>.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
