Menu
Amazon Simple Storage Service
API Reference (API Version 2006-03-01)

PUT Bucket logging

Description

Note

The logging implementation of PUT Bucket is a beta feature.

This implementation of the PUT operation uses the logging subresource to set the logging parameters for a bucket and to specify permissions for who can view and modify the logging parameters. To set the logging status of a bucket, you must be the bucket owner.

The bucket owner is automatically granted FULL_CONTROL to all logs. You use the Grantee request element to grant access to other people. The Permissions request element specifies the kind of access the grantee has to the logs.

To enable logging, you use LoggingEnabled and its children request elements.

To disable logging, you use an empty BucketLoggingStatus request element:

Copy
<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01" />

For more information about creating a bucket, see PUT Bucket. For more information about returning the logging status of a bucket, see GET Bucket logging.

Requests

Syntax

Copy
PUT /?logging HTTP/1.1 Host: BucketName.s3.amazonaws.com Date: date Authorization: authorization string (see Authenticating Requests (AWS Signature Version 4)) Request elements vary depending on what you're setting.

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For more information, see Common Request Headers.

Request Elements

Name Description Required
BucketLoggingStatus

Container for logging status information.

Type: Container

Children: LoggingEnabled

Ancestry: None

Yes
EmailAddress

E-mail address of the person being granted logging permissions.

Type: String

Children: None

Ancestry: BucketLoggingStatus.LoggingEnabled.TargetGrants.Grant.Grantee

No
Grant

Container for the grantee and his/her logging permissions.

Type: Container

Children: Grantee, Permission

Ancestry: BucketLoggingStatus.LoggingEnabled.TargetGrants

No
Grantee

Container for EmailAddress of the person being granted logging permissions. For more information, see Grantee Values.

Type: Container

Children: EmailAddress

Ancestry: BucketLoggingStatus.LoggingEnabled.TargetGrants.Grant

No
LoggingEnabled

Container for logging information. This element is present when you are enabling logging (and not present when you are disabling logging).

Type: Container

Children: Grant, TargetBucket, TargetPrefix

Ancestry: BucketLoggingStatus

No
Permission

Logging permissions given to the Grantee for the bucket. The bucket owner is automatically granted FULL_CONTROL to all logs delivered to the bucket. This optional element enables you grant access to others.

Type: String

Valid Values: FULL_CONTROL | READ | WRITE

Children: None

Ancestry: BucketLoggingStatus.LoggingEnabled.TargetGrants.Grant

No
TargetBucket

Specifies the bucket where you want Amazon S3 to store server access logs. You can have your logs delivered to any bucket that you own, including the same bucket that is being logged. You can also configure multiple buckets to deliver their logs to the same target bucket. In this case you should choose a different TargetPrefix for each source bucket so that the delivered log files can be distinguished by key.

Type: String

Children: None

Ancestry: BucketLoggingStatus.LoggingEnabled

No
TargetGrants

Container for granting information.

Type: Container

Children: Grant, Permission

Ancestry: BucketLoggingStatus.LoggingEnabled

No
TargetPrefix

This element lets you specify a prefix for the keys that the log files will be stored under.

Type: String

Children: None

Ancestry: BucketLoggingStatus.LoggingEnabled

No

Grantee Values

You can specify the person (grantee) to whom you're assigning access rights (using request elements) in the following ways:

  • By the person's ID:

    Copy
    <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"><ID>ID</ID><DisplayName>GranteesEmail</DisplayName> </Grantee>

    DisplayName is optional and ignored in the request.

  • By Email address:

    Copy
    <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AmazonCustomerByEmail"><EmailAddress>Grantees@email.com</EmailAddress>lt;/Grantee>

    The grantee is resolved to the CanonicalUser and, in a response to a GET Object acl request, appears as the CanonicalUser.

  • By URI:

    Copy
    <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group"><URI>http://acs.amazonaws.com/groups/global/AuthenticatedUsers</URI></Grantee>

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses. For more information, see Common Response Headers.

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

Sample Request

This request enables logging and gives the grantee of the bucket READ access to the logs.

Copy
PUT ?logging HTTP/1.1 Host: quotes.s3.amazonaws.com Content-Length: 214 Date: Wed, 25 Nov 2009 12:00:00 GMT Authorization: authorization string <?xml version="1.0" encoding="UTF-8"?> <BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01"> <LoggingEnabled> <TargetBucket>mybucketlogs</TargetBucket> <TargetPrefix>mybucket-access_log-/</TargetPrefix> <TargetGrants> <Grant> <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AmazonCustomerByEmail"> <EmailAddress>user@company.com</EmailAddress> </Grantee> <Permission>READ</Permission> </Grant> </TargetGrants> </LoggingEnabled> </BucketLoggingStatus>

Sample Response

Copy
HTTP/1.1 200 OK x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo x-amz-request-id: 236A8905248E5A01 Date: Wed, 01 Mar 2006 12:00:00 GMT

Sample Request Disabling Logging

This request disables logging on the bucket, quotes.

Copy
PUT ?logging HTTP/1.1 Host: quotes.s3.amazonaws.com Content-Length: 214 Date: Wed, 25 Nov 2009 12:00:00 GMT Authorization: authorization string <?xml version="1.0" encoding="UTF-8"?> <BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01" />

Sample Response

Copy
HTTP/1.1 200 OK x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo x-amz-request-id: 236A8905248E5A01 Date: Wed, 01 Mar 2006 12:00:00 GMT