AWS Documentation » Amazon CloudFront » API Reference » Actions on Download Distributions » PUT Distribution Config	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

PUT Distribution Config

Topics

Description

This action updates the configuration for a download distribution. To update a download distribution using the CloudFront API, perform the following steps.

For information about updating a distribution using the CloudFront console, go to Listing, Viewing, and Updating CloudFront Distributions in the Amazon CloudFront Developer Guide. For information about updating a streaming distribution using the CloudFront API, see PUT Streaming Distribution Config.

To update a download distribution using the CloudFront API

Submit a GET Distribution Config request to get the current configuration and the Etag header for the distribution. For more information, see GET Distribution Config.
Update the XML document that was returned in the response to your GET Distribution Config request with the desired changes. You cannot change the value of CallerReference. If you try to change this value, CloudFront returns an IllegalUpdate error.
Important
The new configuration replaces the existing configuration; they are not merged. When you add, delete, or replace values in an element that allows multiple values (for example, CNAME), you must specify all of the values that you want to appear in the updated distribution. In addition, you must update the corresponding Quantity element.
Submit a PUT Distribution Config request to update the configuration for your distribution:
- In the request body, include the XML document that you updated in Step 2. The request body must include an XML document with a DistributionConfig element.
- Set the value of the HTTP If-Match header to the value of the ETag header that CloudFront returned when you submitted the GET Distribution Config request in Step 1.
Review the response to the PUT Distribution Config request to confirm that the configuration was successfully updated.
Optional: Submit a GET Distribution request to confirm that your changes have propagated. When propagation is complete, the value of Status is Deployed. For more information, see GET Distribution.

Important

Beginning with the 2012-05-05 version of the CloudFront API, we made substantial changes to the format of the XML document that you include in the request body when you create or update a download distribution or a streaming distribution, and when you invalidate objects. With previous versions of the API, we discovered that it was too easy to accidentally delete one or more values for an element that accepts multiple values, for example, CNAMEs and trusted signers. Our changes for the 2012-05-05 release are intended to prevent these accidental deletions and to notify you when there's a mismatch between the number of values you say you're specifying in the Quantity element and the number of values you're actually specifying.

Requests

Syntax

PUT /2012-07-01/distribution/distribution ID/config HTTP/1.1
Host: cloudfront.amazonaws.com
If-Match: value from ETag header in previous GET response
Authorization: AWS authentication string
Other required headers			

<?xml version="1.0" encoding="UTF-8"?>
<DistributionConfig xmlns="http://cloudfront.amazonaws.com/doc/2012-07-01/">
   <CallerReference>unique description for this
      distribution config</CallerReference>
   <Aliases>
      <Quantity>number of CNAME aliases</Quantity>
      <!-- Optional. Omit when Quantity = 0. -->
      <Items>
         <CNAME>CNAME alias</CNAME>
      </Items>
   </Aliases>
   <DefaultRootObject>URL for default root object</DefaultRootObject>
   <Origins>
      <Quantity>number of origins</Quantity>
      <Items>
         <Origin>
            <Id>unique identifier for this origin</Id>
            <DomainName>domain name of origin</DomainName>
            <!-- Include the S3OriginConfig element only if 
               you use an Amazon S3 origin for your distribution. -->
            <S3OriginConfig>
               <OriginAccessIdentity>origin-access-identity/
                  cloudfront/ID</OriginAccessIdentity>
            </S3OriginConfig>
            <!-- Include the CustomOriginConfig element only if 
               you use a custom origin for your distribution. -->
            <CustomOriginConfig>
               <HTTPPort>HTTP port that the custom origin 
                  listens on</HTTPPort>
               <HTTPSPort>HTTPS port that the custom origin 
                  listens on</HTTPSPort>
               <OriginProtocolPolicy>http-only | 
                  match-viewer</OriginProtocolPolicy>
            </CustomOriginConfig>
         </Origin>
      </Items>
   </Origins>
   <DefaultCacheBehavior>
      <TargetOriginId>ID of the origin that the default cache behavior 
         applies to</TargetOriginId>
      <ForwardedValues>
         <QueryString>true | false</QueryString>
         <Cookies>
            <Forward>all | whitelist | none</Forward>
            <!-- Required when Forward = whitelist, 
               omitted otherwise. -->
            <WhitelistedNames>
               <Quantity>number of cookie names to 
                  forward to origin</Quantity>
               <Items>
                  <Name>name of a cookie to forward to 
                     the origin</Name>
               </Items>
            </WhitelistedNames>
         </Cookies>
      </ForwardedValues>
      <TrustedSigners>
         <Enabled>true | false</Enabled>
         <Quantity>number of trusted signers</Quantity>
         <!-- Optional. Omit when Quantity = 0. -->
         <Items>
            <AwsAccountNumber>self | AWS account that can create 
               signed URLs</AwsAccountNumber>
         </Items>
      </TrustedSigners>
      <ViewerProtocolPolicy>allow-all | 
         https-only</ViewerProtocolPolicy>
      <MinTTL>minimum TTL in seconds</MinTTL>
   </DefaultCacheBehavior>
   <CacheBehaviors>
      <Quantity>number of cache behaviors</Quantity>
      <!-- Optional. Omit when Quantity = 0. -->
      <Items>
         <CacheBehavior>
            <PathPattern>pattern that specifies files that this 
               cache behavior applies to</PathPattern>
            <TargetOriginId>ID of the origin that this cache behavior 
               applies to</TargetOriginId>
            <ForwardedValues>
               <QueryString>true | false</QueryString>
               <Cookies>
                  <Forward>all | whitelist | none</Forward>
                  <!-- Required when Forward = whitelist, 
                     omitted otherwise. -->
                  <WhitelistedNames>
                     <Quantity>number of cookie names to forward 
                        to origin</Quantity>
                     <Items>
                        <Name>name of a cookie to forward to 
                           the origin</Name>
                     </Items>
                  </WhitelistedNames>
               </Cookies>
            </ForwardedValues>
            <TrustedSigners>
               <Enabled>true | false</Enabled>
               <Quantity>number of trusted signers</Quantity>
               <!-- Optional. Omit when Quantity = 0. -->
               <Items>
                  <AwsAccountNumber>self | AWS account that can create 
                     signed URLs</AwsAccountNumber>
               </Items>
            </TrustedSigners>
            <ViewerProtocolPolicy>allow-all | 
               https-only</ViewerProtocolPolicy>
            <MinTTL>minimum TTL in seconds for files 
               specified by PathPattern</MinTTL>
         </CacheBehavior>
      </Items>
   </CacheBehaviors>
   <Comment>comment about the distribution</Comment>
   <Logging>
      <Enabled>true | false</Enabled>
      <IncludeCookies>true | false</IncludeCookies>
      <Bucket>Amazon S3 bucket to save logs in</Bucket>
      <Prefix>prefix for log filenames</Prefix>
   </Logging>
   <PriceClass>maximum price class for the distribution</PriceClass>
   <Enabled>true | false</Enabled>
</DistributionConfig>

Headers

The following table lists the special request header the action uses in addition to the common request headers all actions use. For more information, see Common REST Headers.

Name Description Required

Name	Description	Required
`If-Match`	The value of the `ETag` header you received when retrieving the distribution's configuration, for example, `E2QWRUHEXAMPLE` Type: String	Yes

If-Match

The value of the ETag header you received when retrieving the distribution's configuration, for example, E2QWRUHEXAMPLE

Type: String

Yes

Request Elements

Name Description

Name	Description
`DistributionConfig`	The distribution's configuration information. For more information, see DistributionConfig Complex Type. Type: `DistributionConfig` complex type

DistributionConfig

The distribution's configuration information. For more information, see DistributionConfig Complex Type.

Type: DistributionConfig complex type

Responses

Syntax

200 OK
ETag: Updated ETag value, which can be used to do another PUT or to do a DELETE
x-amz-request-id: Request ID

<?xml version="1.0" encoding="UTF-8"?>
<Distribution xmlns="http://cloudfront.amazonaws.com/doc/2012-07-01/">
   <Id>ID for the distribution</Id>
   <Status>Deployed | InProgress</Status>
   <LastModifiedTime>creation date and time in 
      ISO 8601 format</LastModifiedTime>
   <InProgressInvalidationBatches>number of invalidation batches being 
      processed for this distribution</InProgressInvalidationBatches>
   <DomainName>CloudFront domain name assigned to the 
      distribution</DomainName>
   <ActiveTrustedSigners>
      <Enabled>true | false</Enabled>
      <Quantity>number of unique trusted signers from 
         all cache behaviors</Quantity>
      <Items>
         <Signer>
            <AwsAccountNumber>self | AWS account number</AwsAccountNumber>
            <KeyPairIds>
               <Quantity>number of active key pairs for 
                  AwsAccountNumber</Quantity>
               <Items>
                  <KeyPairId>active key pair associated with 
                     AwsAccountNumber</KeyPairId>
               </Items>
            </KeyPairIds>
         </Signer>
      </Items>
   </ActiveTrustedSigners>
   <DistributionConfig>
      <CallerReference>unique description for this
         distribution config</CallerReference>
      <Aliases>
         <Quantity>number of CNAME aliases</Quantity>
         <!-- Optional. Omitted when Quantity = 0. -->
         <Items>
            <CNAME>CNAME alias</CNAME>
         </Items>
      </Aliases>
      <DefaultRootObject>URL for default root object</DefaultRootObject>
      <Origins>
         <Quantity>number of origins</Quantity>
         <Items>
            <Origin>
               <Id>unique identifier for this origin</Id>
               <DomainName>domain name of origin</DomainName>
               <!-- CloudFront returns the S3OriginConfig element 
                  only if you use an Amazon S3 origin. --> 
               <S3OriginConfig>
                  <OriginAccessIdentity>origin-access-identity/
                     cloudfront/ID</OriginAccessIdentity>
               </S3OriginConfig>
               <!-- CloudFront returns the CustomOriginConfig element 
                  only if you use a custom origin. -->
               <CustomOriginConfig>
                  <HTTPPort>HTTP port that the custom origin 
                     listens on</HTTPPort>
                  <HTTPSPort>HTTPS port that the custom origin 
                     listens on</HTTPSPort>
                  <OriginProtocolPolicy>http-only | 
                     match-viewer</OriginProtocolPolicy>
               </CustomOriginConfig>
            </Origin>
         </Items>
      </Origins>
      <DefaultCacheBehavior>
         <TargetOriginId>ID of the origin that the default cache behavior 
            applies to</TargetOriginId>
         <ForwardedValues>
            <QueryString>true | false</QueryString>
            <Cookies>
               <Forward>all | whitelist | none</Forward>
               <!-- Required when Forward = whitelist, omitted otherwise. -->
               <WhitelistedNames>
                  <Quantity>number of cookie names to 
                     forward to origin</Quantity>
                  <Items>
                     <Name>name of a cookie to forward to the origin</Name>
                  </Items>
               </WhitelistedNames>
            </Cookies>
         </ForwardedValues>
         <TrustedSigners>
            <Enabled>true | false</Enabled>
            <Quantity>number of trusted signers</Quantity>
            <!-- Optional. Omitted when Quantity = 0. -->
            <Items>
               <AwsAccountNumber>self | AWS account that can create 
                  signed URLs</AwsAccountNumber>
            </Items>
         </TrustedSigners>
         <ViewerProtocolPolicy>allow-all | 
            https-only</ViewerProtocolPolicy>
         <MinTTL>minimum TTL in seconds</MinTTL>
      </DefaultCacheBehavior>
      <CacheBehaviors>
         <Quantity>number of cache behaviors</Quantity>
         <!-- Optional. Omitted when Quantity = 0. -->
         <Items>
            <CacheBehavior>
               <PathPattern>pattern that specifies files that this 
                  cache behavior applies to</PathPattern>
               <TargetOriginId>ID of the origin that this cache behavior 
                  applies to</TargetOriginId>
               <ForwardedValues>
                  <QueryString>true | false</QueryString>
                  <Cookies>
                     <Forward>all | whitelist | none</Forward>
                     <!-- Required when Forward = whitelist, 
                        omitted otherwise. -->
                     <WhitelistedNames>
                        <Quantity>number of cookie names to 
                           forward to origin</Quantity>
                        <Items>
                           <Name>name of a cookie to forward to 
                              the origin</Name>
                        </Items>
                     </WhitelistedNames>
                  </Cookies>
               </ForwardedValues>
               <TrustedSigners>
                  <Enabled>true | false</Enabled>
                  <Quantity>number of trusted signers</Quantity>
                  <!-- Optional. Omitted when Quantity = 0. -->
                  <Items>
                     <AwsAccountNumber>self | AWS account that can create 
                        signed URLs</AwsAccountNumber>
                  </Items>
               </TrustedSigners>
               <ViewerProtocolPolicy>allow-all | 
                  https-only</ViewerProtocolPolicy>
               <MinTTL>minimum TTL in seconds for files 
                  specified by PathPattern</MinTTL>
            </CacheBehavior>
         </Items>
      </CacheBehaviors>
      <Comment>comment about the distribution</Comment>
      <Logging>
         <Enabled>true | false</Enabled>
         <IncludeCookies>true | false</IncludeCookies>
         <Bucket>Amazon S3 bucket to save logs in</Bucket>
         <Prefix>prefix for log filenames</Prefix>
      </Logging>
      <PriceClass>maximum price class for the distribution</PriceClass>
      <Enabled>true | false</Enabled>
   </DistributionConfig>
</Distribution>

Headers

Name Description

Name	Description
`ETag`	The current version of the configuration, for example, `E2QWRUHEXAMPLE`. For information about using the `ETag` header value, see Description. Type: String

ETag

The current version of the configuration, for example, E2QWRUHEXAMPLE. For information about using the ETag header value, see Description.

Type: String

Elements

Name Description

Name	Description
`Distribution`	The distribution's information. For more information, see Distribution Complex Type. Type: `Distribution` datatype

Distribution

The distribution's information. For more information, see Distribution Complex Type.

Type: Distribution datatype

Special Errors

The following table lists the special errors returned in addition to the common errors all actions return. For more information, see Errors.

Error	Description	HTTP Status Code
`CNAMEAlreadyExists`	One or more of the CNAMEs you provided are already associated with a different distribution.	409
`IllegalUpdate`	Origin and CallerReference cannot be updated.	400
`InvalidIfMatchVersion`	The If-Match version is missing or not valid for the distribution.	400
`InvalidOriginAccessIdentity`	The origin access identity is not valid or doesn't exist.	400
`InvalidRequiredProtocol`	This operation requires the HTTPS protocol. Ensure that you specify the HTTPS protocol in your request, or omit the `RequiredProtocols` element from your distribution configuration.	400
`MissingBody`	This operation requires a body. Ensure that the body is present and the Content-Type header is set.	400
`NoSuchDistribution`	The specified distribution does not exist.	404
`PreconditionFailed`	The precondition given in one or more of the request-header fields evaluated to `false`.	412
`TooManyDistributionCNAMEs`	Your request contains more CNAMEs than are allowed per distribution.	400
`TooManyTrustedSigners`	Your request contains more trusted signers than are allowed per distribution.	400
`TrustedSignerDoesNotExist`	One or more of your trusted signers do not exist.	400

Examples

The following example request updates the configuration for the EDFDVBD6EXAMPLE distribution.

Sample Request

PUT /2012-07-01/distribution/EDFDVBD6EXAMPLE/config HTTP/1.1
Host: cloudfront.amazonaws.com
Authorization: AWS authentication string
Date: Thu, 17 May 2012 19:37:58 GMT
If-Match: E2QWRUHEXAMPLE
Other required headers

<?xml version="1.0" encoding="UTF-8"?>
<DistributionConfig xmlns="http://cloudfront.amazonaws.com/doc/2012-07-01/">
   <CallerReference>example.com2012-04-11-5:09pm</CallerReference>
   <Aliases>
      <Quantity>1</Quantity>
      <Items>
         <CNAME>www.example.com</CNAME>
      </Items>
   </Aliases>
   <DefaultRootObject>index.html</DefaultRootObject>
   <Origins>
      <Quantity>2</Quantity>
      <Items>
         <Origin>
            <Id>example-Amazon S3-origin</Id>
            <DomainName>myawsbucket.s3.amazonaws.com</DomainName>
            <S3OriginConfig>
               <OriginAccessIdentity>origin-access-identity/cloudfront/E74FTE3AEXAMPLE</OriginAccessIdentity>
            </S3OriginConfig>
         </Origin>
         <Origin>
            <Id>example-custom-origin</Id>
            <DomainName>example.com</DomainName>
            <CustomOriginConfig>
               <HTTPPort>80</HTTPPort>
               <HTTPSPort>443</HTTPSPort>
               <OriginProtocolPolicy>match-viewer</OriginProtocolPolicy>
            </CustomOriginConfig>
         </Origin>
      </Items>
   </Origins>
   <DefaultCacheBehavior>
      <TargetOriginId>example-Amazon S3-origin</TargetOriginId>
      <ForwardedValues>
         <QueryString>true</QueryString>
         <Cookies>
            <Forward>whitelist</Forward>
            <WhitelistedNames>
               <Quantity>1</Quantity>
               <Items>
                  <Name>example-cookie</Name>
               </Items>
            </WhitelistedNames>
         </Cookies>
      </ForwardedValues>
      <TrustedSigners>
         <Enabled>true</Enabled>
         <Quantity>3</Quantity>
         <Items>
            <AwsAccountNumber>self</AwsAccountNumber>
            <AwsAccountNumber>111122223333</AwsAccountNumber>
            <AwsAccountNumber>444455556666</AwsAccountNumber>
         </Items>
      </TrustedSigners>
      <ViewerProtocolPolicy>https-only</ViewerProtocolPolicy>
      <MinTTL>0</MinTTL>
   </DefaultCacheBehavior>
   <CacheBehaviors>
      <Quantity>1</Quantity>
      <Items>
         <CacheBehavior>
            <PathPattern>*.jpg</PathPattern>
            <TargetOriginId>example-custom-origin</TargetOriginId>
            <ForwardedValues>
               <QueryString>false</QueryString>
               <Cookies>
                  <Forward>all</Forward>
               </Cookies>
            </ForwardedValues>
            <TrustedSigners>
               <Enabled>true</Enabled>
               <Quantity>2</Quantity>
               <Items>
                  <AwsAccountNumber>self</AwsAccountNumber>
                  <AwsAccountNumber>111122223333</AwsAccountNumber>
               </Items>
            </TrustedSigners>
            <ViewerProtocolPolicy>allow-all</ViewerProtocolPolicy>
            <MinTTL>86400</MinTTL>
         </CacheBehavior>
      </Items>
   </CacheBehaviors>
   <Comment>example comment</Comment>
   <Logging>
      <Enabled>true</Enabled>
      <IncludeCookies>true</IncludeCookies>
      <Bucket>myawslogbucket.s3.amazonaws.com</Bucket>
      <Prefix>example.com.</Prefix>
   </Logging>
   <PriceClass>PriceClass_All</PriceClass>
   <Enabled>true</Enabled>
</DistributionConfig>

Sample Response

200 OK
ETag: E9LHASXEXAMPLE
x-amz-request-id: request_id
			
<?xml version="1.0" encoding="UTF-8"?>
<Distribution xmlns="http://cloudfront.amazonaws.com/doc/2012-07-01/">
   <Id>EDFDVBD6EXAMPLE</Id>
   <Status>Deployed</Status>
   <LastModifiedTime>2012-05-19T19:37:58Z</LastModifiedTime>
   <InProgressInvalidationBatches>1</InProgressInvalidationBatches>
   <DomainName>d111111abcdef8.cloudfront.net</DomainName>
   <ActiveTrustedSigners>
      <Quantity>3</Quantity>
      <Items>
         <Signer>
            <AwsAccountNumber>self</AwsAccountNumber>
            <KeyPairIds>
               <Quantity>1</Quantity>
               <Items>
                  <KeyPairId>APKA9ONS7QCOWEXAMPLE</KeyPairId>
               </Items>
            </KeyPairIds>
         </Signer>
         <Signer>
            <AwsAccountNumber>111122223333</AwsAccountNumber>
            <KeyPairIds>
               <Quantity>2</Quantity>
               <KeyPairId>APKAI72T5DYBXEXAMPLE</KeyPairId>
               <KeyPairId>APKAU72D8DYNXEXAMPLE</KeyPairId>
            </KeyPairIds>
         </Signer>
         <Signer>
            <AwsAccountNumber>444455556666</AwsAccountNumber>
            <KeyPairIds>
               <Quantity>0</Quantity>
            </KeyPairIds>
         </Signer>
      </Items>
   </ActiveTrustedSigners>
   <DistributionConfig>
      <CallerReference>example.com2012-04-11-5:09pm</CallerReference>
      <Aliases>
         <Quantity>1</Quantity>
         <Items>
            <CNAME>www.example.com</CNAME>
         </Items>
      </Aliases>
      <DefaultRootObject>index.html</DefaultRootObject>
      <Origins>
         <Quantity>2</Quantity>
         <Items>
            <Origin>
               <Id>example-Amazon S3-origin</Id>
               <DomainName>myawsbucket.s3.amazonaws.com</DomainName>
               <S3OriginConfig>
                  <OriginAccessIdentity>origin-access-identity/cloudfront/E74FTE3AEXAMPLE</OriginAccessIdentity>
               </S3OriginConfig>
            </Origin>
            <Origin>
               <Id>example-custom-origin</Id>
               <DomainName>example.com</DomainName>
               <CustomOriginConfig>
                  <HTTPPort>80</HTTPPort>
                  <HTTPSPort>443</HTTPSPort>
                  <OriginProtocolPolicy>match-viewer</OriginProtocolPolicy>
               </CustomOriginConfig>
            </Origin>
         </Items>
      </Origins>
      <DefaultCacheBehavior>
         <TargetOriginId>example-Amazon S3-origin</TargetOriginId>
         <ForwardedValues>
            <QueryString>true</QueryString>
            <Cookies>
               <Forward>whitelist</Forward>
               <WhitelistedNames>
                  <Quantity>1</Quantity>
                  <Items>
                     <Name>example-cookie</Name>
                  </Items>
               </WhitelistedNames>
            </Cookies>
         </ForwardedValues>
         <TrustedSigners>
            <Enabled>true</Enabled>
            <Quantity>3</Quantity>
            <Items>
               <AwsAccountNumber>self</AwsAccountNumber>
               <AwsAccountNumber>111122223333</AwsAccountNumber>
               <AwsAccountNumber>444455556666</AwsAccountNumber>
            </Items>
         </TrustedSigners>
         <ViewerProtocolPolicy>https-only</ViewerProtocolPolicy>
         <MinTTL>0</MinTTL>
      </DefaultCacheBehavior>
      <CacheBehaviors>
         <Quantity>1</Quantity>
         <Items>
            <CacheBehavior>
               <PathPattern>*.jpg</PathPattern>
               <TargetOriginId>example-custom-origin</TargetOriginId>
               <ForwardedValues>
                  <QueryString>false</QueryString>
                  <Cookies>
                     <Forward>all</Forward>
                  </Cookies>
               </ForwardedValues>
               <TrustedSigners>
                  <Enabled>true</Enabled>
                  <Quantity>2</Quantity>
                  <Items>
                     <AwsAccountNumber>self</AwsAccountNumber>
                     <AwsAccountNumber>111122223333</AwsAccountNumber>
                  </Items>
               </TrustedSigners>
               <ViewerProtocolPolicy>allow-all</ViewerProtocolPolicy>
               <MinTTL>86400</MinTTL>
            </CacheBehavior>
         </Items>
      </CacheBehaviors>
      <Comment>example comment</Comment>
      <Logging>
         <Enabled>true</Enabled>
         <IncludeCookies>true</IncludeCookies>
         <Bucket>myawslogbucket.s3.amazonaws.com</Bucket>
         <Prefix>example.com.</Prefix>
      </Logging>
      <PriceClass>PriceClass_All</PriceClass>
      <Enabled>true</Enabled>
   </DistributionConfig>
</Distribution>

Related Actions

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...