acl - Get, set, or change bucket and/or object ACLs
gsutil acl set [-f] [-r] [-a] file-or-canned_acl_name url... gsutil acl get url gsutil acl ch [-f] [-r] -u|-g|-d|-p <grant>... url...
where each <grant> is one of the following forms:
-u <id|email>:<perm> -g <id|email|domain|All|AllAuth>:<perm> -p <viewers|editors|owners>-<project number> -d <id|email|domain|All|AllAuth|<viewers|editors|owners>-<project number>>
The acl command has three sub-commands:
The "acl get" command gets the ACL text for a bucket or object, which you can save and edit for the acl set command.
The "acl set" command allows you to set an Access Control List on one or more buckets and objects. The simplest way to use it is to specify one of the canned ACLs, e.g.,:
gsutil acl set private gs://bucket
If you want to make an object or bucket publicly readable or writable, it is recommended to use "acl ch", to avoid accidentally removing OWNER permissions. See gsutil help acl ch" for details.
See "gsutil help acls" for a list of all canned ACLs.
If you want to define more fine-grained control over your data, you can retrieve an ACL using the "acl get" command, save the output to a file, edit the file, and then use the "acl set" command to set that ACL on the buckets and/or objects. For example:
gsutil acl get gs://bucket/file.txt > acl.txt
Make changes to acl.txt such as adding an additional grant, then:
gsutil acl set acl.txt gs://cats/file.txt
Note that you can set an ACL on multiple buckets or objects at once, for example:
gsutil acl set acl.txt gs://bucket/*.jpg
If you have a large number of ACLs to update you might want to use the gsutil -m option, to perform a parallel (multi-threaded/multi-processing) update:
gsutil -m acl set acl.txt gs://bucket/*.jpg
Note that multi-threading/multi-processing is only done when the named URLs refer to objects, which happens either if you name specific objects or if you enumerate objects by using an object wildcard or specifying the acl -r flag.
The "set" sub-command has the following options
-R, -r Performs "acl set" request recursively, to all objects under the specified URL. -a Performs "acl set" request on all object versions. -f Normally gsutil stops at the first error. The -f option causes it to continue when it encounters errors. If some of the ACLs couldn't be set, gsutil's exit status will be non-zero even if this flag is set. This option is implicitly set when running "gsutil -m acl...".
The "acl ch" (or "acl change") command updates access control lists, similar in spirit to the Linux chmod command. You can specify multiple access grant additions and deletions in a single command run; all changes will be made atomically to each object in turn. For example, if the command requests deleting one grant and adding a different grant, the ACLs being updated will never be left in an intermediate state where one grant has been deleted but the second grant not yet added. Each change specifies a user or group grant to add or delete, and for grant additions, one of R, W, O (for the permission to be granted). A more formal description is provided in a later section; below we provide examples.
Examples for "ch" sub-command:
Grant anyone on the internet READ access to the object example-object:
gsutil acl ch -u AllUsers:R gs://example-bucket/example-object
NOTE: By default, publicly readable objects are served with a Cache-Control header allowing such objects to be cached for 3600 seconds. If you need to ensure that updates become visible immediately, you should set a Cache-Control header of "Cache-Control:private, max-age=0, no-transform" on such objects. For help doing this, see gsutil help setmeta.
Grant anyone on the internet WRITE access to the bucket example-bucket (WARNING: this is not recommended as you will be responsible for the content):
gsutil acl ch -u AllUsers:W gs://example-bucket
Grant the user firstname.lastname@example.org WRITE access to the bucket example-bucket:
gsutil acl ch -u email@example.com:WRITE gs://example-bucket
Grant the group firstname.lastname@example.org OWNER access to all jpg files in the top level of example-bucket:
gsutil acl ch -g email@example.com:O gs://example-bucket/*.jpg
Grant the owners of project example-project WRITE access to the bucket example-bucket:
gsutil acl ch -p owners-example-project:W gs://example-bucket
NOTE: You can replace 'owners' with 'viewers' or 'editors' to grant access to a project's viewers/editors respectively.
Remove access to the bucket example-bucket for the owners of project number 12345:
gsutil acl ch -d owners-12345 gs://example-bucket
Note that removing a project requires you to reference the project by its number (which you can see with the acl get command) as opposed to its project ID string.
Grant the user with the specified canonical ID READ access to all objects in example-bucket that begin with folder/:
gsutil acl ch -r \\ -u 84fac329bceSAMPLE777d5d22b8SAMPLE785ac2SAMPLE2dfcf7c4adf34da46:R \\ gs://example-bucket/folder/
Grant the service account firstname.lastname@example.org WRITE access to the bucket example-bucket:
gsutil acl ch -u email@example.com:W gs://example-bucket
Grant all users from the Google Apps domain my-domain.org READ access to the bucket gcs.my-domain.org:
gsutil acl ch -g my-domain.org:R gs://gcs.my-domain.org
Remove any current access by firstname.lastname@example.org from the bucket example-bucket:
gsutil acl ch -d email@example.com gs://example-bucket
If you have a large number of objects to update, enabling multi-threading with the gsutil -m flag can significantly improve performance. The following command adds OWNER for firstname.lastname@example.org using multi-threading:
gsutil -m acl ch -r -u email@example.com:O gs://example-bucket
Grant READ access to everyone from my-domain.org and to all authenticated users, and grant OWNER to firstname.lastname@example.org, for the buckets my-bucket and my-other-bucket, with multi-threading enabled:
gsutil -m acl ch -r -g my-domain.org:R -g AllAuth:R \\ -u email@example.com:O gs://my-bucket/ gs://my-other-bucket
You may specify the following roles with either their shorthand or their full name:
R: READ W: WRITE O: OWNER
There are four different entity types: Users, Groups, All Authenticated Users, and All Users.
Users are added with -u and a plain ID or email address, as in "-u firstname.lastname@example.org:r". Note: Service Accounts are considered to be users.
Groups are like users, but specified with the -g flag, as in "-g email@example.com:fc". Groups may also be specified as a full domain, as in "-g my-company.com:r".
AllAuthenticatedUsers and AllUsers are specified directly, as in "-g AllUsers:R" or "-g AllAuthenticatedUsers:O". These are case insensitive, and may be shortened to "all" and "allauth", respectively.
Removing roles is specified with the -d flag and an ID, email address, domain, or one of AllUsers or AllAuthenticatedUsers.
Many entities' roles can be specified on the same command line, allowing bundled changes to be executed in a single run. This will reduce the number of requests made to the server.
The "ch" sub-command has the following options
-d Remove all roles associated with the matching entity. -f Normally gsutil stops at the first error. The -f option causes it to continue when it encounters errors. With this option the gsutil exit status will be 0 even if some ACLs couldn't be changed. -g Add or modify a group entity's role. -p Add or modify a project viewers/editors/owners role. -R, -r Performs acl ch request recursively, to all objects under the specified URL. -u Add or modify a user entity's role.