Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Creating a trail for an organization with the Amazon CLI

You can create an organization trail by using the Amazon CLI. The Amazon CLI is regularly updated with additional functionality and commands. To help ensure success, be sure that you have installed or updated to a recent Amazon CLI version before you begin.

Create or update an Amazon S3 bucket to use to store the log files for an organization trail

You must specify an Amazon S3 bucket to receive the log files for an organization trail. This bucket must have a policy that allows CloudTrail to put the log files for the organization into the bucket.

The following is an example policy for an Amazon S3 bucket named amzn-s3-demo-bucket, which is owned by the organization's management account. Replace amzn-s3-demo-bucket, region, managementAccountID, trailName, and o-organizationID with the values for your organization

This bucket policy contains three statements.

The example policy includes an aws:SourceArn condition key for the Amazon S3 bucket policy. The IAM global condition key aws:SourceArn helps ensure that CloudTrail writes to the S3 bucket only for a specific trail or trails. In an organization trail, the value of aws:SourceArn must be a trail ARN that is owned by the management account, and uses the management account ID.

JSON

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AWSCloudTrailAclCheck20150319",
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "cloudtrail.amazonaws.com"
                ]
            },
            "Action": "s3:GetBucketAcl",
            "Resource": "arn:aws:s3:::amzn-s3-demo-bucket",
            "Condition": {
                "StringEquals": {
                    "aws:SourceArn": "arn:aws:cloudtrail:region:managementAccountID:trail/trailName"
                }
            }
        },
        {
            "Sid": "AWSCloudTrailWrite20150319",
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "cloudtrail.amazonaws.com"
                ]
            },
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/AWSLogs/managementAccountID/*",
            "Condition": {
                "StringEquals": {
                    "s3:x-amz-acl": "bucket-owner-full-control",
                    "aws:SourceArn": "arn:aws:cloudtrail:region:managementAccountID:trail/trailName"
                }
            }
        },
        {
            "Sid": "AWSCloudTrailOrganizationWrite20150319",
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "cloudtrail.amazonaws.com"
                ]
            },
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/AWSLogs/o-organizationID/*",
            "Condition": {
                "StringEquals": {
                    "s3:x-amz-acl": "bucket-owner-full-control",
                    "aws:SourceArn": "arn:aws:cloudtrail:region:managementAccountID:trail/trailName"
                }
            }
        }
    ]
}

This example policy does not allow any users from member accounts to access the log files created for the organization. By default, organization log files are accessible only to the management account. For information about how to allow read access to the Amazon S3 bucket for IAM users in member accounts, see Sharing CloudTrail log files between Amazon accounts.

Enabling CloudTrail as a trusted service in Amazon Organizations

Before you can create an organization trail, you must first enable all features in Organizations. For more information, see Enabling All Features in Your Organization, or run the following command using a profile with sufficient permissions in the management account:

aws organizations enable-all-features

After you enable all features, you must configure Organizations to trust CloudTrail as a trusted service. .

To create the trusted service relationship between Amazon Organizations and CloudTrail, open a terminal or command line and use a profile in the management account. Run the aws organizations enable-aws-service-access command, as demonstrated in the following example.

aws organizations enable-aws-service-access --service-principal cloudtrail.amazonaws.com

Using create-trail

Creating an organization trail that applies to all Regions

To create an organization trail that applies to all Regions, add the --is-organization-trail and --is-multi-region-trail options.

The following example creates an organization trail that delivers logs from all Regions to an existing bucket named amzn-s3-demo-bucket:

aws cloudtrail create-trail --name my-trail --s3-bucket-name amzn-s3-demo-bucket --is-organization-trail --is-multi-region-trail

To confirm that your trail exists in all Regions, the IsOrganizationTrail and IsMultiRegionTrail parameters in the output are both set to true:

{
    "IncludeGlobalServiceEvents": true, 
    "Name": "my-trail", 
    "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", 
    "LogFileValidationEnabled": false, 
    "IsMultiRegionTrail": true, 
    "IsOrganizationTrail": true,
    "S3BucketName": "amzn-s3-demo-bucket"
}

Creating an organization trail as a single-Region trail

The following command creates an organization trail that only logs events in a single Amazon Web Services Region, also known as a single-Region trail. The Amazon Region where events are logged is the Region specified in the configuration profile for the Amazon CLI.

aws cloudtrail create-trail --name my-trail --s3-bucket-name amzn-s3-demo-bucket --is-organization-trail

For more information, see Naming requirements for CloudTrail resources, S3 buckets, and KMS keys.

Sample output:

{
    "IncludeGlobalServiceEvents": true, 
    "Name": "my-trail", 
    "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", 
    "LogFileValidationEnabled": false,
    "IsMultiRegionTrail": false,
    "IsOrganizationTrail": true,
    "S3BucketName": "amzn-s3-demo-bucket"
}

By default, the create-trail command creates a single-Region trail that does not enable log file validation.

Running update-trail to update an organization trail

You can run the update-trail command to change the configuration settings for an organization trail, or to apply an existing trail for a single Amazon account to an entire organization. Remember that you can run the update-trail command only from the Region in which the trail was created.

Applying an existing trail to an organization

To change an existing trail so that it also applies to an organization instead of a single Amazon account, add the --is-organization-trail option, as shown in the following example.

aws cloudtrail update-trail --name my-trail --is-organization-trail

To confirm that the trail now applies to the organization, the IsOrganizationTrail parameter in the output has a value of true.

{
    "IncludeGlobalServiceEvents": true, 
    "Name": "my-trail", 
    "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", 
    "LogFileValidationEnabled": false, 
    "IsMultiRegionTrail": true, 
    "IsOrganizationTrail": true, 
    "S3BucketName": "amzn-s3-demo-bucket"
}

In the preceding example, the trail was configured as a multi-Region trail ("IsMultiRegionTrail": true). A trail that applied only to a single Region would show "IsMultiRegionTrail": false in the output.

Converting a single-Region organization trail to a multi-Region organization trail

To convert an existing single-Region organization trail to a multi-Region organization trail, add the --is-multi-region-trail option as shown in the following example.

aws cloudtrail update-trail --name my-trail --is-multi-region-trail

To confirm that the trail is now a multi-Region, check that the IsMultiRegionTrail parameter in the output has a value of true.

{
    "IncludeGlobalServiceEvents": true, 
    "Name": "my-trail", 
    "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", 
    "LogFileValidationEnabled": false, 
    "IsMultiRegionTrail": true, 
    "IsOrganizationTrail": true,
    "S3BucketName": "amzn-s3-demo-bucket"
}