All Products
Search
Document Center

Object Storage Service:set-acl

Last Updated:Aug 15, 2024

Access control lists (ACLs) are policies used to manage the access permissions on buckets and objects in Object Storage Service (OSS). You can configure the ACL for a bucket when you create the bucket or for an object when you upload the object. You can also modify the ACLs of existing objects and buckets at any time. This topic describes how to use the set-acl command to configure or modify the ACLs of buckets and objects.

Usage notes

  • To configure or modify the ACL of a bucket, you must have the oss:PutBucketAcl permission. To configure or modify the ACL of an object, you must have the oss:PutObjectAcl permission. To modify the ACLs of multiple objects at a time, you must have the oss:PutObjectAcl and oss:ListObjects permissions. For more information, see Attach a custom policy to a RAM user.

  • For ossutil 1.6.16 and later, you can directly use ossutil as the binary name in the command line. You do not need to update the binary name based on the operating system. For ossutil earlier than 1.6.16, you need to update the binary name based on the operating system. For more information, see ossutil command reference.

Configure or modify the ACL of a bucket

  • Command syntax

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

    The following table describes the parameters and options in the syntax.

    Parameter/Option

    Description

    bucketname

    The name of the bucket whose ACL you want to configure or modify.

    acl

    The ACL of the bucket. Valid values:

    • private (default): Only the bucket owner can perform read and write operations on the objects in the bucket. Other users cannot access the objects in the bucket.

    • public-read: Only the bucket owner can perform write operations on the objects in the bucket. Other users, including anonymous users, can perform only read operations on the objects in the bucket. This may result in unrestricted access to the data in your bucket and unexpectedly high fees. If a user uploads prohibited data or information, your legal rights may be infringed. We recommend that you do not set the ACL to public-read unless necessary.

    • public-read-write: All users, including anonymous users, can perform read and write operations on the objects in the bucket. This may result in unrestricted access to the data in your bucket and unexpectedly high fees. Exercise caution when you set the ACL to public-read-write.

    -b

    If you do not specify this option, the ACL specified in the command is the ACL of objects. To use the command to configure the bucket ACL, you must specify this option.

    --retry-times

    The number of retries after the command fails to run. Default value: 10. Valid values: 1 to 500.

  • Examples

    You can run the following command to set the ACL of a bucket named examplebucket to private:

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

Configure or modify the ACL of objects

  • 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 in the syntax.

    Parameter/Option

    Description

    bucketname

    The name of the bucket that contains the objects whose ACL you want to configure or modify.

    prefix

    The prefix in the names of resources, such as directories and objects.

    acl

    The ACL of the objects. Valid values:

    • default: The ACL of the objects is the same as that of the bucket in which the objects are stored.

    • private (default): Only the bucket owner can perform read and write operations on the objects in the bucket. Other users cannot access the objects in the bucket.

    • public-read: Only the bucket owner can perform write operations on the objects in the bucket. Other users, including anonymous users, can perform only read operations on the objects in the bucket. This may result in unrestricted access to the data in your bucket and unexpectedly high fees. If a user uploads prohibited data or information, your legal rights may be infringed. We recommend that you do not set the ACL to public-read unless necessary.

    • public-read-write: All users, including anonymous users, can perform read and write operations on the objects in the bucket. This may result in unrestricted access to the data in your bucket and unexpectedly high fees. Exercise caution when you set the ACL to public-read-write.

    -r

    If you specify this option, ossutil configures the ACL of all objects whose names contain the prefix specified by the prefix option. If you do not specify this option, ossutil configures the ACL only of the object specified by cloud_url.

    --include

    Specifies that the command applies to all objects that meet the specified conditions.

    For more information, see --include and --exclude.

    --exclude

    Specifies that the command applies to all objects that do not meet the specified conditions.

    For more information, see --include and --exclude.

    --version-id

    The version ID of the object whose ACL you want to configure or modify. This parameter applies only to objects in buckets for which versioning is enabled or suspended.

    --job

    The number of concurrent tasks that can be performed across multiple objects. Valid values: 1 to 10000. Default value: 3.

    --retry-times

    The number of retries after the command fails to run. Default value: 10. Valid values: 1 to 500.

    --encoding-type

    The method used to encode the value of the prefix parameter that follows oss://bucket_name. Valid value: url. If you do not specify this option, the prefix is not encoded.

  • Examples

    • You can run the following command to set the ACL of an object named exampleobject.txt in a bucket named examplebucket to private:

      ossutil set-acl oss://examplebucket/exampleobject.txt private
    • You can run the following command to set the ACL of the specified version (CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3****) of the exampleobject.txt object in a bucket named examplebucket to private:

      ossutil set-acl oss://examplebucket/exampleobject.txt private --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3****
    • You can run the following command to set the ACL of objects whose names contain the test prefix in a bucket named examplebucket to default:

      ossutil set-acl oss://examplebucket/test default -r
    • You can run the following command to set the ACL of objects whose names contain the .jpg extension in a bucket named examplebucket to private:

      ossutil set-acl oss://examplebucket private --include "*.jpg" -r
    • You can run the following command to set the ACL of objects whose names contain the "abc" string and do not contain the .png or .txt extension in a bucket named examplebucket to default:

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

Common options

If you use ossutil to switch to a bucket that is located in another region, add the -e option to the command to specify the endpoint of the region in which the specified bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, add the -i option to the command to specify the AccessKey ID of the specified account, and add the -k option to the command to specify the AccessKey secret of the specified account.

For example, you can run the following command to set the ACL of a bucket named testbucket to private. The testbucket bucket is located in the China (Shanghai) region and owned by another Alibaba Cloud account.

ossutil set-acl oss://testbucket private -b -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

For more information about common options, see Common options.