PUT Bucket logging
Description
Note | |
---|---|
The logging implementation of PUT Bucket is a beta feature. |
This implementation of the PUT
operation uses the logging
sub-resource 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:
<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01" />
For more information about creating a bucket, see
Requests
Syntax
PUT /?logging HTTP/1.1 Host:BucketName
.s3.amazonaws.com Date:date
Authorization:signatureValue
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 only uses request headers 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 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 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) that you're assigning access rights to (using request elements) in the following ways:
-
By the person's ID:
<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 E-mail address:
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AmazonCustomerByEmail"> <EmailAddress>
[email protected]
</EmailAddress> </Grantee>The grantee is resolved to the
CanonicalUser
and in a response to aGET Object acl
request appears as theCanonicalUser
. -
By URI:
<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.
PUT ?logging HTTP/1.1 Host: quotes.s3.amazonaws.com Content-Length: 214 Date: Wed, 25 Nov 2009 12:00:00 GMT Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE= <?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>[email protected]</EmailAddress> </Grantee> <Permission>READ</Permission> </Grant> </TargetGrants> </LoggingEnabled> </BucketLoggingStatus>
Sample Response
HTTP/1.1 200 OK x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo x-amz-request-id: 236A8905248E5A01 Date: Wed, 01 Mar 2009 12:00:00 GMT
Sample Request Disabling Logging
This request disables logging on the bucket, quotes
.
PUT ?logging HTTP/1.1 Host: quotes.s3.amazonaws.com Content-Length: 214 Date: Wed, 25 Nov 2009 12:00:00 GMT Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE= <?xml version="1.0" encoding="UTF-8"?> <BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01" />
Sample Response
HTTP/1.1 200 OK x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo x-amz-request-id: 236A8905248E5A01 Date: Wed, 01 Mar 2009 12:00:00 GMT