Menu
AWS CloudTrail
User Guide (Version 1.0)

Creating a Trail with the AWS Command Line Interface

Note

The AWS Command Line Interface (AWS CLI) commands in this topic require that you have the AWS command line tools. For more information, see the AWS Command Line Interface User Guide. For help with CloudTrail commands at the AWS CLI command line, type aws cloudtrail help.

Two options for creating and updating trails

When creating or updating a trail with the AWS CLI, you have two sets of options:

  • create-trail and update-trail

  • create-subscription and update-subscription

create-trail and update-trail

The create-trail and update-trail offer the following functionality that the create-subscription and update-subscription commands do not:

  • Create a trail that receives logs across regions, or update a trail with the --is-multi-region-trail option.

  • Convert a multi-region trail to single-region trail with the --no-is-multi-region-trail option.

  • Enable or disable log file encryption with the --kms-key-id option. The option specifies an AWS KMS key that you have already created and to which you have attached a policy that allows CloudTrail to encrypt your logs. For more information, see Enabling and disabling CloudTrail log file encryption with the AWS CLI.

  • Enable or disable log file validation with the --enable-log-file-validation and --no-enable-log-file-validation options. For more information, see Validating CloudTrail Log File Integrity.

  • Specify a CloudWatch Logs log group and role so that CloudTrail can deliver events to a CloudWatch Logs log group. For more information, see Monitoring CloudTrail Log Files with Amazon CloudWatch Logs.

create-subscription and update-subscription

The create-subscription and update-subscription commands offer the following advantages:

  • You can have CloudTrail create a new S3 bucket for you. With the create-trail command, you must specify an existing bucket in which you have already applied the bucket policy for CloudTrail.

  • The create-subscription command starts logging for the trail. With the create-trail command, you must run the start-logging command.

Using create-trail

Creating a single-region trail

The following command creates a single-region trail. The specified S3 bucket must already exist and have the appropriate CloudTrail permissions applied. For more information, see Amazon S3 Bucket Policy for CloudTrail.

Copy
aws cloudtrail create-trail --name my-trail --s3-bucket-name my-bucket

For more information, see CloudTrail Trail Naming Requirements.

Sample output:

Copy
{ "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "IsMultiRegionTrail": false, "S3BucketName": "my-bucket" }

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

Start logging for the trail

After the create-trail command completes, run the start-logging command to start logging for that trail.

Note

When you create a trail with the CloudTrail console or the create-subscription command, logging is turned on automatically.

The following example starts logging for a trail:

Copy
aws cloudtrail start-logging --name my-trail

This command doesn't return an output. However, you can verify that logging has started with the get-trail-status command:

Copy
aws cloudtrail get-trail-status --name my-trail

To confirm that the trail is logging, the IsLogging element in the output shows true:

Copy
{ "LatestDeliveryTime": 1441139757.497, "LatestDeliveryAttemptTime": "2015-09-01T20:35:57Z", "LatestNotificationAttemptSucceeded": "2015-09-01T20:35:57Z", "LatestDeliveryAttemptSucceeded": "2015-09-01T20:35:57Z", "IsLogging": true, "TimeLoggingStarted": "2015-09-01T00:54:02Z", "StartLoggingTime": 1441068842.76, "LatestDigestDeliveryTime": 1441140723.629, "LatestNotificationAttemptTime": "2015-09-01T20:35:57Z", "TimeLoggingStopped": "" }

Creating a trail that applies to all regions

To create a trail that applies to all regions, use the --is-multi-region-trail option.

The following example creates a trail that delivers logs from all regions to an existing bucket named my-bucket:

Copy
aws cloudtrail create-trail --name my-trail --s3-bucket-name my-bucket --is-multi-region-trail

To confirm that your trail exists in all regions, the IsMultiRegionTrail element in the output shows true:

Copy
{ "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "IsMultiRegionTrail": true, "S3BucketName": "my-bucket" }

Note

Use the start-logging command to start logging for your trail.

Creating a trail that applies to all regions and that has log file validation enabled

To enable log file validation when using create-trail, use the --enable-log-file-validation option.

Note

For information about log file validation, see Validating CloudTrail Log File Integrity.

The following example creates a trail that delivers logs from all regions to the specified bucket. The command uses the --enable-log-file-validation option.

Copy
aws cloudtrail create-trail --name my-trail --s3-bucket-name my-bucket --is-multi-region-trail --enable-log-file-validation

To confirm that log file validation is enabled, the LogFileValidationEnabled element in the output shows true:

Copy
{ "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/my-trail", "LogFileValidationEnabled": true, "IsMultiRegionTrail": true, "S3BucketName": "my-bucket" }

Using update-trail

You can use the update-trail command to change the configuration settings for a trail.

Note

If you use the AWS CLI or one of the AWS SDKs to modify a trail, be sure that the trail's bucket policy is up-to-date. In order for your bucket to automatically receive events from a new AWS Region, the policy must contain the full service name, cloudtrail.amazonaws.com. For more information, see Amazon S3 Bucket Policy for CloudTrail.

Note

You can run the update-trail command only from the region in which the trail was created.

Converting a trail that applies to one region to apply to all regions

The following example changes an existing a trail so that it applies to all regions with the --is-multi-region-trail option:

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

To confirm that the trail now applies to all regions, the IsMultiRegionTrail element in the output shows true:

Copy
{ "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "IsMultiRegionTrail": true, "S3BucketName": "my-bucket" }

Converting a multi-region trail to a single-region trail

To change an existing multi-region trail so that it applies to only to the region in which it was created, use the --no-is-multi-region-trail option, as the following example shows.

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

To confirm that the trail now applies to a single region, the IsMultiRegionTrail element in the output shows false:

Copy
{ "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "IsMultiRegionTrail": false, "S3BucketName": "my-bucket" }

Enabling log file validation

To enable log file validation for a trail, use the --enable-log-file-validation option. Digest files are delivered to the Amazon S3 bucket for that trail.

Copy
aws cloudtrail update-trail --name my-trail --enable-log-file-validation

To confirm that log file validation is enabled, the LogFileValidationEnabled element in the output shows true:

Copy
{ "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/my-trail", "LogFileValidationEnabled": true, "IsMultiRegionTrail": false, "S3BucketName": "my-bucket" }

Disabling log file validation

To disable log file validation for a trail, use the --no-enable-log-file-validation option.

Copy
aws cloudtrail update-trail --name my-trail-name --no-enable-log-file-validation

To confirm that log file validation is disabled, the LogFileValidationEnabled element in the output shows false:

Copy
{ "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "IsMultiRegionTrail": false, "S3BucketName": "my-bucket" }

To validate log files with the AWS CLI, see Validating CloudTrail Log File Integrity with the AWS CLI.

Using create-subscription

The create-subscription command creates a trail. You can also use this command to create a new Amazon S3 bucket for log file delivery and a new Amazon SNS topic for notifications. The create-subscription command also starts logging for the trail that it creates.

The create-subscription command includes the following options:

  • --name specifies the name of the trail. This option is required. For more information, see CloudTrail Trail Naming Requirements.

  • --s3-use-bucket specifies an existing Amazon S3 bucket for log file storage.

  • --s3-new-bucket specifies the name of the new bucket created when the command executes. The name of the bucket must be globally unique. For more information, see Amazon S3 Bucket Naming Requirements.

  • --s3-prefix specifies a prefix for the log file delivery path (optional). The maximum length is 200 characters.

    Note

    If you want to use a new log file prefix for an existing bucket, add the prefix to the bucket policy first. For more information, see Changing a Prefix for an Existing Bucket.

  • --sns-new-topic specifies the name of the Amazon SNS topic to which you can subscribe for notification of log file delivery to your bucket (optional).

Note

Type aws cloudtrail create-subscription help to see the list of options.

The following example creates a trail, a new Amazon S3 bucket for log file delivery, an S3 bucket prefix, and a new SNS topic.

Copy
aws cloudtrail create-subscription --name=awscloudtrail-example --s3-new-bucket=awscloudtrail-new-bucket-example --s3-prefix=prefix-example --sns-new-topic=awscloudtrail-example-log-deliverytopic

If the command executes successfully, you see output similar to the following:

Copy
Setting up new S3 bucket awscloudtrail-new-bucket-example... Setting up new SNS topic awscloudtrail-example-log-deliverytopic... Creating/updating CloudTrail configuration... CloudTrail configuration: { "trailList": [ { "IncludeGlobalServiceEvents": true, "Name": "awscloudtrail-example", "S3KeyPrefix": "prefix-example", "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/awscloudtrail-example", "LogFileValidationEnabled": false, "IsMultiRegionTrail": false, "HasCustomEventSelectors": false, "S3BucketName": "awscloudtrail-new-bucket-example" "SnsTopicName": "awscloudtrail-example-log-deliverytopic", "HomeRegion": "us-west-2" } ], "ResponseMetadata": { "HTTPStatusCode": 200, "RequestId": "4c55c744-a0ea-4aea-b3b9-eb63dfe68383" } } Starting CloudTrail service... Logs will be delivered to awscloudtrail-new-bucket-example:prefix-example

Using update-subscription

You can update your trail by using the command update-subscription and setting the options to new values. The following example uses the --s3-use-bucket option to designate a different pre-existing Amazon S3 bucket. If you want a trail with a different name, delete the trail with the delete-trail command and then run the create-subscription command.

Copy
aws cloudtrail update-subscription --name=awscloudtrail-example --s3-use-bucket=awscloudtrail-new-bucket-example2 --s3-prefix=prefix-example

If the command executes successfully, the S3BucketName value is updated to awscloudtrail-new-bucket-example2:

Copy
CloudTrail configuration: { "trailList": [ { "IncludeGlobalServiceEvents": true, "Name": "awscloudtrail-example", "S3KeyPrefix": "prefix-example", "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/awscloudtrail-example", "LogFileValidationEnabled": false, "IsMultiRegionTrail": false, "HasCustomEventSelectors": false, "S3BucketName": "awscloudtrail-new-bucket-example2" "SnsTopicName": "awscloudtrail-example-log-deliverytopic", "HomeRegion": "us-west-2" } ] }

Note

If you specify an existing Amazon S3 bucket and that bucket was not created with CloudTrail, you need to attach the appropriate policy. See Amazon S3 Bucket Policy for CloudTrail.

Managing Trails

The CloudTrail CLI includes several other commands that help you manage your trails.

Retrieving trail settings and the status of a trail

Use the describe-trails command to retrieve trail settings:

Copy
aws cloudtrail describe-trails

If the command succeeds, you see output similar to the following:

Copy
{ "trailList": [ { "IncludeGlobalServiceEvents": true, "Name": "my-trail", "S3KeyPrefix": "my-prefix", "TrailARN": "arn:aws:cloudtrail:us-west-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "IsMultiRegionTrail": false, "HasCustomEventSelectors": false, "S3BucketName": "my-bucket" "SnsTopicName": "my-topic", "HomeRegion": "us-west-2" } ] }

Run the get-trail-status command to retrieve the status of a trail.

Copy
aws cloudtrail get-trail-status --name awscloudtrail-example

If the command succeeds, you see output similar to the following:

Copy
{ "LatestDeliveryTime": 1441139757.497, "LatestDeliveryAttemptTime": "2015-09-01T20:35:57Z", "LatestNotificationAttemptSucceeded": "2015-09-01T20:35:57Z", "LatestDeliveryAttemptSucceeded": "2015-09-01T20:35:57Z", "IsLogging": true, "TimeLoggingStarted": "2015-09-01T00:54:02Z", "StartLoggingTime": 1441068842.76, "LatestDigestDeliveryTime": 1441140723.629, "LatestNotificationAttemptTime": "2015-09-01T20:35:57Z", "TimeLoggingStopped": "" }

In addition to the fields shown in the preceding JSON code, the status contains the following fields if there are Amazon SNS or Amazon S3 errors:

  • LatestNotificationError. Contains the error emitted by Amazon SNS if a subscription to a topic fails.

  • LatestDeliveryError. Contains the error emitted by Amazon S3 if CloudTrail cannot deliver a log file to a bucket.

Configuring event selectors

To view the event selector settings for a trail, run the get-event-selectors command:

Copy
aws cloudtrail get-event-selectors --trail-name TrailName

The following example returns the default settings for an event selector for a trail.

Copy
{ "EventSelectors": [ { "IncludeManagementEvents": true, "DataResources": [], "ReadWriteType": "All" } ], "TrailARN": "arn:aws:cloudtrail:us-east-1:123456789012:trail/TrailName" }

To create an event selector, run the put-event-selectors command. When an event occurs in your account, CloudTrail evaluates the configuration for your trails. If the event matches any event selector for a trail, the trail processes and logs the event. You can configure up to 5 event selectors for a trail and up to 250 S3 objects for a trail. For more information, see Logging Data and Management Events for Trails.

The following example creates an event selector to include read-only and write-only management, and data events for two S3 objects.

Copy
aws cloudtrail put-event-selectors --trail-name TrailName --event-selectors '[{ "ReadWriteType": "All", "IncludeManagementEvents":true, "DataResources": [{ "Type": "AWS::S3::Object", "Values": ["arn:aws:s3:::mybucket/prefix", "arn:aws:s3:::mybucket2/prefix2"] }] }]'

The following example returns the event selector configured for the trail:

Copy
{ "EventSelectors": [ { "IncludeManagementEvents": true, "DataResources": [ { "Values": [ "arn:aws:s3:::mybucket/prefix", "arn:aws:s3:::mybucket2/prefix2" ], "Type": "AWS::S3::Object" } ], "ReadWriteType": "All" } ], "TrailARN": "arn:aws:cloudtrail:us-east-1:123456789012:trail/TrailName" }

Stopping and Starting Logging for a Trail

The following commands start and stop CloudTrail logging:

Copy
aws cloudtrail start-logging --name awscloudtrail-example

Copy
aws cloudtrail stop-logging --name awscloudtrail-example

Caution

Before deleting a bucket, run the stop-logging command to stop delivering events to the bucket. If you don’t stop logging, CloudTrail attempts to deliver log files to a bucket with the same name for a limited period of time.

Deleting a Trail

You can delete a trail with the following command. You can delete a trail only in the region it was created.

Copy
aws cloudtrail delete-trail --name awscloudtrail-example

When you delete a trail, you do not delete the Amazon S3 bucket or the Amazon SNS topic associated with it. Use the AWS Management Console, AWS CLI, or service API to delete these resources separately.