AWS CloudTrail
User Guide (Version 1.0)

Managing Trails With the AWS CLI

The AWS CLI includes several other commands that help you manage your trails. These commands add tags to trails, get trail status, start and stop logging for trails, and delete a trail. You must run these commands from the same AWS Region where the trail was created (its Home Region). When using the AWS CLI, remember that your commands run in the AWS Region configured for your profile. If you want to run the commands in a different Region, either change the default Region for your profile, or use the --region parameter with the command.

Add one or more tags to a trail

To add one or more tags to an existing trail, use the add-tags command.

The following example adds a tag with the name Owner and the value of Mary to a trail with the ARN of arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail in the US East (Ohio) Region.

aws cloudtrail add-tags --resource-id arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail --tags-list Key=Owner,Value=Mary --region us-east-2

If successful, this command returns nothing.

List tags for one or more trails

To view the tags associated with one or more existing trails, use the list-tags command.

The following example lists the tags for Trail1 and Trail2.

aws cloudtrail list-tags --resource-id-list arn:aws:cloudtrail:us-east-2:123456789012:trail/Trail1 arn:aws:cloudtrail:us-east-2:123456789012:trail/Trail2

If successful, this command returns output similar to the following.

{ "ResourceTagList": [ { "ResourceId": "arn:aws:cloudtrail:us-east-2:123456789012:trail/Trail1", "TagsList": [ { "Value": "Alice", "Key": "Name" }, { "Value": "Ohio", "Key": "Location" } ] }, { "ResourceId": "arn:aws:cloudtrail:us-east-2:123456789012:trail/Trail2", "TagsList": [ { "Value": "Bob", "Key": "Name" } ] } ] }

Remove one or more tags from a trail

To remove one or more tags from an existing trail, use the remove-tags command.

The following example removes tags with the names Location and Name from a trail with the ARN of arn:aws:cloudtrail:us-east-2:123456789012:trail/Trail1 in the US East (Ohio) Region.

aws cloudtrail remove-tags --resource-id arn:aws:cloudtrail:us-east-2:123456789012:trail/Trail1 --tags-list Key=Name Key=Location --region us-east-2

If successful, this command returns nothing.

Retrieving trail settings and the status of a trail

Use the describe-trails command to retrieve information about trails in an AWS Region. The following example returns information about trails configured in the US East (Ohio) Region.

aws cloudtrail describe-trails --region us-east-2

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

{ "trailList": [ { "Name": "my-trail", "S3BucketName": "my-bucket", "S3KeyPrefix": "my-prefix", "IncludeGlobalServiceEvents": true, "IsMultiRegionTrail": true, "HomeRegion": "us-east-2" "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "HasCustomEventSelectors": false, "SnsTopicName": "my-topic", "IsOrganizationTrail": false, }, { "Name": "my-special-trail", "S3BucketName": "another-bucket", "S3KeyPrefix": "example-prefix", "IncludeGlobalServiceEvents": false, "IsMultiRegionTrail": false, "HomeRegion": "us-east-2", "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-special-trail", "LogFileValidationEnabled": false, "HasCustomEventSelectors": true, "IsOrganizationTrail": false }, { "Name": "my-org-trail", "S3BucketName": "my-bucket", "S3KeyPrefix": "my-prefix", "IncludeGlobalServiceEvents": true, "IsMultiRegionTrail": true, "HomeRegion": "us-east-1" "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-org-trail", "LogFileValidationEnabled": false, "HasCustomEventSelectors": false, "SnsTopicName": "my-topic", "IsOrganizationTrail": true } ] }

Use the get-trail command to retrieve settings information about a specific trail. The following example returns settings information for a trail named my-trail.

aws cloudtrail get-trail - -name my-trail

If successful, this command returns output similar to the following.

{ "Trail": { "Name": "my-trail", "S3BucketName": "my-bucket", "S3KeyPrefix": "my-prefix", "IncludeGlobalServiceEvents": true, "IsMultiRegionTrail": true, "HomeRegion": "us-east-2" "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "HasCustomEventSelectors": false, "SnsTopicName": "my-topic", "IsOrganizationTrail": false, } }

Run the get-trail-status command to retrieve the status of a trail. You must either run this command from the AWS Region where it was created (the Home Region), or you must specify that Region by using the --region parameter.

Note

If the trail is an organization trail and you are a member account in the organization in AWS Organizations, you must provide the full ARN of that trail, and not just the name.

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

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

{ "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. You must either run this command from the AWS Region where it was created (the Home Region), or you must specify that Region by using the --region parameter.

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

Note

If the trail is an organization trail and you are a member account in the organization in AWS Organizations, you must provide the full ARN of that trail, and not just the name.

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

{ "EventSelectors": [ { "IncludeManagementEvents": true, "DataResources": [], "ReadWriteType": "All" } ], "TrailARN": "arn:aws:cloudtrail:us-east-2: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 data resources for a trail. For more information, see Logging Data and Management Events for Trails.

Example: A trail with specific event selectors

The following example creates an event selector for a trail named TrailName to include read-only and write-only management events, data events for two Amazon S3 bucket/prefix combinations, and data events for a single AWS Lambda function named hello-world-python-function.

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"]},{"Type": "AWS::Lambda::Function","Values": ["arn:aws:lambda:us-west-2:999999999999:function:hello-world-python-function"]}]}]'

The example returns the event selector configured for the trail.

{ "EventSelectors": [ { "IncludeManagementEvents": true, "DataResources": [ { "Values": [ "arn:aws:s3:::mybucket/prefix", "arn:aws:s3:::mybucket2/prefix2" ], "Type": "AWS::S3::Object" }, { "Values": [ "arn:aws:lambda:us-west-2:123456789012:function:hello-world-python-function" ], "Type": "AWS::Lambda::Function" }, ], "ReadWriteType": "All" } ], "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName" }

Example: A trail that logs all events

The following example creates an event selector for a trail named TrailName2 that includes all events, including read-only and write-only management events, and all data events for all Amazon S3 buckets and AWS Lambda functions in the AWS account.

Note

If the trail applies only to one Region, only events in that Region are logged, even though the event selector parameters specify all Amazon S3 buckets and Lambda functions. Event selectors apply only to the Regions where the trail is created.

aws cloudtrail put-event-selectors --trail-name TrailName2 --event-selectors '[{"ReadWriteType": "All","IncludeManagementEvents": true,"DataResources": [{"Type":"AWS::S3::Object", "Values": ["arn:aws:s3:::"]},{"Type": "AWS::Lambda::Function","Values": ["arn:aws:lambda"]}]}]'

The example returns the event selectors configured for the trail.

{ "EventSelectors": [ { "IncludeManagementEvents": true, "DataResources": [ { "Values": [ "arn:aws:s3:::" ], "Type": "AWS::S3::Object" }, { "Values": [ "arn:aws:lambda" ], "Type": "AWS::Lambda::Function" }, ], "ReadWriteType": "All" } ], "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName2" }

Stopping and starting logging for a trail

The following commands start and stop CloudTrail logging.

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

Note

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 (the Home Region).

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.