set-acl (Set or modify ACLs)

Usage notes

• To set or modify a bucket ACL, you must have the oss:PutBucketAcl permission. To set or modify an object ACL, you must have the oss:PutObjectAcl permission. To modify the ACLs of multiple objects in a batch, you must have the oss:PutObjectAcl and oss:ListObjects permissions. For more information, see Grant custom permissions to a RAM user.

• Starting with ossutil v1.6.16, you can use ossutil directly as the binary name in the command line. You do not need to rename the binary based on your operating system. If you use a version of ossutil earlier than 1.6.16, you must rename the binary based on your operating system. For more information, see ossutil command reference.

• Take note of the following items when you run the command in OSS on CloudBox:

  1. Replace the endpoints in the configuration file with the endpoints of CloudBox. For more information, see CloudBox endpoints.

  2. Add --sign-version, --region, and --cloudbox-id options to the sample command in this topic. For more information about the options, see Common options.

Set or modify a bucket ACL

• Command syntax

  ossutil set-acl oss://bucketname acl -b [--retry-times <value>]

  The following table describes the parameters and options.

  Configuration item	Description
  bucketname	The name of the bucket whose ACL you want to set or modify.
  acl	The ACL of the bucket. Valid values: private (default): Only the bucket owner can read and write objects in the bucket. Other users cannot access the objects in the bucket. public-read: Only the bucket owner can write to objects in the bucket. Other users, including anonymous users, can only read the objects. This may result in data leaks and unexpectedly high fees. If a user uploads prohibited data or information, your legal rights may be infringed. Do not set the ACL to public-read unless necessary. public-read-write: All users, including anonymous users, can read and write objects in the bucket. This may result in data leaks and unexpectedly high fees. Exercise caution when you set the ACL to public-read-write.
  -b	By default, this command sets the ACL for an object. To set the ACL for a bucket, you must include this option.
  --retry-times	The number of retries if an error occurs. Default value: 10. Value range: 1 to 500.

• Example

  Set the ACL of the examplebucket bucket to private.

  ossutil set-acl oss://examplebucket private -b   

Set or modify an object ACL

• Command syntax

  ossutil set-acl oss://bucketname[/prefix] acl
  [-r]
  [--include <value>] 
  [--exclude <value>]
  [--version-id <value>]
  [--job <value>] 
  [--retry-times <value>]
  [--encoding-type <value>]

  The following table describes the parameters and options.

  Configuration item	Description
  bucketname	The name of the bucket.
  prefix	The resource in the bucket, such as a folder or file.
  acl	The ACL of the object. Valid values: default: The object inherits the ACL of the bucket. private (default): Only the bucket owner can read and write the object. Other users cannot access the object. public-read: Only the bucket owner can write to the object. Other users, including anonymous users, can only read the object. This may result in data leaks and unexpectedly high fees. If a user uploads prohibited data or information, your legal rights may be infringed. Do not set the ACL to public-read unless necessary. public-read-write: All users, including anonymous users, can read and write the object. This may result in data leaks and unexpectedly high fees. Exercise caution when you set the ACL to public-read-write.
  -r	Recursively sets the ACL for all objects that match the specified prefix. If you do not include this option, ossutil sets the ACL only for the single object specified in the cloud URL.
  --include	Includes only objects that match the specified conditions. For more information, see --include and --exclude options.
  --exclude	No objects meet the specified conditions. For more information, see --include and --exclude options.
  --version-id	The ID of the object version. This option applies only to objects in buckets that have versioning enabled or suspended.
  --job	The number of concurrent tasks for batch operations. Default value: 3. Value range: 1 to 10000.
  --retry-times	The number of retries if an error occurs. Default value: 10. Value range: 1 to 500.
  --encoding-type	The encoding type of the prefix that follows oss://bucket_name. Set the value to url. If you do not specify this option, the prefix is not encoded.

• Examples

  • Set the ACL of the exampleobject.txt object in the examplebucket bucket to private.

    ossutil set-acl oss://examplebucket/exampleobject.txt private

  • Set the ACL of a specific version (CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3****) of the exampleobject.txt object in the examplebucket bucket to private.

    ossutil set-acl oss://examplebucket/exampleobject.txt private --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3****

  • Set the ACL to default for all objects that have the test prefix in the examplebucket bucket.

    ossutil set-acl oss://examplebucket/test default -r

  • Set the ACL to private for all objects that have the .jpg extension in the examplebucket bucket.

    ossutil set-acl oss://examplebucket private --include "*.jpg" -r

  • Set the ACL to default for all objects that contain abc in their names but do not have the .png or .txt extension in the examplebucket bucket.

    ossutil set-acl oss://examplebucket default --include "*abc*" --exclude "*.png" --exclude "*.txt" -r

Common options

If you use ossutil to access a bucket in a different region, add the -e option to specify the Endpoint of the bucket's region. If you use ossutil to access a bucket that belongs to a different Alibaba Cloud account, add the -i option to specify the AccessKey ID and the -k option to specify the AccessKey secret of the account.

ossutil set-acl oss://testbucket private -b -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret

For more information about other common options for this command, see Common options.