PUT Bucket logging
Description
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. All logs are saved to buckets in
the
same AWS Region as the source bucket. 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 server access logging, see Server Access Logging in the Amazon Simple Storage Service Developer Guide.
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
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: Ancestry: None |
Yes |
EmailAddress
|
Email address of the person being granted logging permissions. Type: String Children: None Ancestry:
|
No |
Grant
|
Container for the grantee and his/her logging permissions. Type: Container Children: Ancestry: |
No |
Grantee
|
Container for Type: Container Children: Ancestry: |
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: Ancestry: |
No |
Permission
|
Logging permissions given to the Type: String Valid Values: FULL_CONTROL | READ | WRITE Children: None Ancestry: |
No |
TargetBucket
|
Specifies the bucket where you want Amazon S3 to store server access logs, which is
the
target bucket. The bucket that's being logged is the source
bucket. The target bucket can be any bucket that you own that is
in the same Region as the source bucket, including the source
bucket itself. You can also configure multiple buckets to
deliver their logs to the same target bucket. In this case, you
should choose a different Type: String Children: None Ancestry:
|
No |
TargetGrants
|
Container for granting information. Type: Container Children: Ancestry: |
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: |
Yes, if the TargetBucket element is specified.
|
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:
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"><ID><replaceable>ID</replaceable></ID><DisplayName><replaceable>GranteesEmail</replaceable></DisplayName> </Grantee>
DisplayName
is optional and ignored in the request. -
By Email address:
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AmazonCustomerByEmail"><EmailAddress><replaceable>Grantees@email.com</replaceable></EmailAddress>lt;/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><replaceable>http://acs.amazonaws.com/groups/global/AuthenticatedUsers</replaceable></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:
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
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
.
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
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