S3ACL(1p)

📦

version 0.08 · 2 versions

0.08 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
0.08 · ubuntu jammy

, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 S3ACL(1p) — s3acl 💖

User Contributed Perl Documentation · the s3acl girlie is here to talk about your bucket ACLs

✨ NAME ✨

s3acl — display or manipulate the ACL of AWS S3 buckets and items 🪣🔐

🌸 SYNOPSIS 🌸

okay so basically, here's the vibe:

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 — prints a lil brief help message and dips out. 🫶
--man — prints the whole manual page and then dips out. the full lore, no cap.
--verbose — tells you what's being done as it's being done. like a live commentary track for your bucket operations. 🎙️
--access-key and --secret-key — bestie, these are your "AWS Access Key Identifiers" for the AWS account. --access-key is the "Access Key ID", and --secret-key is the "Secret Access Key". they are literally the "username" and "password" to your AWS account, so keep them 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. command line wins, periodt.

--secure — uses SSL/TLS HTTPS to talk to the AWS service, instead of HTTP. 🔐✨ the glow-up your traffic deserves.
--get — retrieve and display the ACL for each specified bucket or item. the read-only main character behavior. 👑
--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. so don't do that, bestie, it will NOT slay. 😭

--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. pick your fighter. 💅
--clear — removes all of the grants from the ACL. and yes, all of them — 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. (because a fully empty ACL is giving "I burned the whole house down" energy 🔥)

--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. no spaces, we are not doing that today.

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. canonical ID or nothing, sorry babe. 🙈

--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. not a bug in us, bestie, that's just S3 being S3. 😭

--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. completely overwrite!! 🔥
--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

the -- is the "nothing to see here, this is a name not a flag" barrier. 🛡️

🌈 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. no keys, no service, that's the rule. 🔑

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

🎀 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 ✨

Bestie, this tool pulls the Access Control List (that's the ACL 💅) for buckets and for items inside buckets over in Amazon Simple Storage Service — aka S3 — and prints it out for you. Slay.

🫶 Principals 🫶

Okay so ngl, a big chunk of the text below is lifted straight from the "Amazon S3 Developer Guide (API Version 2006-03-01)". Credit where it's due, periodt.

Every bucket and every item has an Access Control List (ACL). When a request comes in, S3 figures out who the principal making the request is, then checks the ACL to see if that principal is authorized to make the request. If the ACL has an entry authorizing that principal for this request, the request goes through. If not? Error. That's it, that's the whole vibe check. 💀

A principal can be someone with an AWS S3 account who has logged in — i.e. "authenticated". Or the principal might be the creator and owner of the bucket or item. Or, like, it could literally just be some anonymous web browser out there on the internet. Main character energy from anywhere. 🌈

📜 ACL is sequence of grants. A grant is 1 grantee and 1 permission.

An access control list is a sequence of grants. It can hold up to 100 grants. A grant is made of one grantee — a description of the principal who's getting access — and one permission — a description of what that principal is allowed to do with that bucket or item. Two things, one grant. No cap.

👑 User Grantee 👑

A user grantee has to be registered as an Amazon.com customer, but lowkey does not have to be registered as an AWS customer.

When an ACL gets read, the user grantee shows up in a canonical format, which is 64 hex characters. The one exception? If the grantee is the owner. Amazon still stores and returns that grantee in canonical form, but this tool displays it as "OWNER". Cute little special case, we love her. 💖

🌸 Group Grantee 🌸

The only groups available are the ones pre-defined by S3. In the current release of S3 you cannot create your own group. As of right now there are two pre-defined groups.

The first one this tool represents with the string "WORLD". All principals — anonymous or authenticated — are considered part of this group.

The second one this tool represents with the string "USERS". Every non-anonymous principal is considered part of this group. Heads up though: permission granted by virtue of this grant does not trump other access control considerations. Example time: if a user is registered with AWS they may be part of this group, but if they haven't subscribed to S3, they still won't be granted access. Rules are rules. 🙈

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

And if Amazon updates S3 to define any additional groups before this tool gets updated, they'll be represented as a URI surrounded by angle brackets.

💜 Owner 💜

Every bucket and item in S3 has an owner attribute attached to it. The owner is 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. No shortcuts, bestie.

The owner of a bucket or item is subject to that bucket's or item's access control policy 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.

So picture this: as the owner of an item, you could remove yourself from the associated access control list and then discover you can no longer read the item's data and metadata. 😭 But by virtue of being owner, you always have the right to re-grant yourself permissions to it. This policy exists to prevent the situation where an item becomes "stranded," with nobody able to ever modify or even delete it. Protective queen behavior fr fr. 🫶

🔥 Permissions 🔥

The permission in a grant describes the type of access being granted to the respective grantee. These are the supported permissions:

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. And bestie, 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 is 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.

And note: 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. Reset button, activated. 🔄

🦋 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. Obsessed.

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 a 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 an 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
$ _

Look at her go. 💅

💀 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. (It doesn't yet, bestie. 😭)

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. F in the chat. 💀

👑 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>.

And that's the whole page, bestie — every last crumb. ✨

This little icon was generated by perl v5.34.0 back on 2022-06-16, and it's filed under S3ACL(1p). Go forth and ACL responsibly, mwah 💖💅

📦 where this page comes from

debian bookworm: libnet-amazon-s3-tools-perl 0.08-3 · LGPL-2.1-or-later
debian trixie: libnet-amazon-s3-tools-perl 0.08-3 · LGPL-2.1-or-later
ubuntu noble: libnet-amazon-s3-tools-perl 0.08-3 · LGPL-2.1-or-later
ubuntu resolute: libnet-amazon-s3-tools-perl 0.08-3 · LGPL-2.1-or-later
ubuntu stonking: libnet-amazon-s3-tools-perl 0.08-3 · LGPL-2.1-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms