# Working with CloudTrail trails *Trails* capture a record of AWS activities, delivering and storing these events in an Amazon S3 bucket, with optional delivery to [CloudWatch Logs](send-cloudtrail-events-to-cloudwatch-logs.md) and [Amazon EventBridge](cloudtrail-aws-service-specific-topics.md#cloudtrail-aws-service-specific-topics-eventbridge). You can deliver one copy of your ongoing management events to your S3 bucket at no charge from CloudTrail by creating a trail, however, there are Amazon S3 storage charges. For more information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). For information about Amazon S3 pricing, see [Amazon S3 Pricing](https://aws.amazon.com/s3/pricing/). You can create both multi-Region and single-Region trails for your AWS account. **Multi-Region trails** When you create a multi-Region trail, CloudTrail records events in all AWS Regions that are [enabled](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-enable-standalone) in your AWS account and delivers the CloudTrail event log files to an S3 bucket that you specify. As a best practice, we recommend creating a multi-Region trail because it captures activity in all enabled Regions. All trails created using the CloudTrail console are multi-Region trails. You can convert a single-Region trail to a multi-Region trail by using the AWS CLI. For more information, see [Understanding multi-Region trails and opt-in Regions](cloudtrail-multi-region-trails.md), [Creating a trail with the console](cloudtrail-create-a-trail-using-the-console-first-time.md#creating-a-trail-in-the-console), and [Converting a single-Region trail to a multi-Region trail](cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-update-trail.md#cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-examples-convert). **Single-Region trails** When you create a single-Region trail, CloudTrail records the events in that Region only. It then delivers the CloudTrail event log files to an Amazon S3 bucket that you specify. You can only create a single-Region trail by using the AWS CLI. If you create additional single trails, you can have those trails deliver CloudTrail event log files to the same S3 bucket or to separate buckets. This is the default option when you create a trail using the AWS CLI or the CloudTrail API. For more information, see [Creating, updating, and managing trails with the AWS CLI](cloudtrail-create-and-update-a-trail-by-using-the-aws-cli.md). **Note** For both types of trails, you can specify an Amazon S3 bucket from any Region. If you have created an organization in AWS Organizations, you can create an *organization trail* that logs all events for all AWS accounts in that organization. Organization trails can apply to all AWS Regions, or the current Region. Organization trails must be created using the management account or delegated administrator account, and when specified as applying to an organization, are automatically applied to all member accounts in the organization. Member accounts can see the organization trail, but cannot modify or delete it. By default, member accounts do not have access to the log files for an organization trail in the Amazon S3 bucket. For more information, see [Creating a trail for an organization](creating-trail-organization.md). **Topics** + [ # Creating a trail for your AWS account ](cloudtrail-create-and-update-a-trail.md) + [ # Creating a trail for an organization ](creating-trail-organization.md) + [ # Understanding multi-Region trails and opt-in Regions ](cloudtrail-multi-region-trails.md) + [ # Copying trail events to CloudTrail Lake ](cloudtrail-copy-trail-to-lake.md) + [ # Getting and viewing your CloudTrail log files ](get-and-view-cloudtrail-log-files.md) + [ # Configuring Amazon SNS notifications for CloudTrail ](configure-sns-notifications-for-cloudtrail.md) + [ # Using AWS CloudTrail with interface VPC endpoints ](cloudtrail-and-interface-VPC.md) + [ # Naming requirements for CloudTrail resources, S3 buckets, and KMS keys ](cloudtrail-trail-naming-requirements.md) + [ # AWS account closure and trails ](cloudtrail-account-closure.md) # Creating a trail for your AWS account When you create a trail, you enable ongoing delivery of events as log files to an Amazon S3 bucket that you specify. Creating a trail has many benefits, including: + A record of events that extends past 90 days. + The option to automatically monitor and alarm on specified events by sending log events to Amazon CloudWatch Logs. + The option to query logs and analyze AWS service activity with Amazon Athena. Beginning on April 12, 2019, you can view trails only in the AWS Regions where they log events. If you create a [multi-Region](cloudtrail-multi-region-trails.md) trail, it appears in the console in all AWS Regions that are [enabled](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-enable-standalone) in your account. If you create a trail that only logs events in a single Region, you can view and manage it only in that Region. As a best practice, we recommend creating a multi-Region trail because it captures activity in all enabled Regions. All trails created using the CloudTrail console are multi-Region trails. To create a single-Region trail, you must use the AWS CLI. If you use AWS Organizations, you can create a trail that will log events for all AWS accounts in the organization. A trail with the same name will be created in each member account, and events from each trail will be delivered to the Amazon S3 bucket that you specify. **Note** Only the management account or delegated administrator account for an organization can create a trail for the organization. Creating a trail for an organization automatically enables integration between CloudTrail and Organizations. For more information, see [Creating a trail for an organization](creating-trail-organization.md). If you misconfigure your trail (for example, the S3 bucket is unreachable), CloudTrail will attempt to redeliver the log files to your S3 bucket for 30 days, and these attempted-to-deliver events will be subject to standard CloudTrail charges. To avoid charges on a misconfigured trail, you need to delete the trail. **Topics** + [ # Creating and updating a trail with the console ](cloudtrail-create-and-update-a-trail-by-using-the-console.md) + [ # Creating, updating, and managing trails with the AWS CLI ](cloudtrail-create-and-update-a-trail-by-using-the-aws-cli.md) + [ # Creating multiple trails ](create-multiple-trails.md) # Creating and updating a trail with the console You can use the CloudTrail console to create, update, or delete your trails. Trails created using the console are multi-Region. To create a trail that logs events in only one AWS Region, [use the AWS CLI](cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-create-trail.md#cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-examples-single). You can create up to five trails for each Region. After you create a trail, CloudTrail automatically starts logging API calls and related events in your account to the Amazon S3 bucket that you specify. You can change the following settings for your trail using the CloudTrail console: + You can change the S3 bucket location and specify a prefix. + The management account for an AWS Organizations organization can convert an account-level trail to an organization trail, or can convert an organization trail to an account-level trail. + You can enable or disable KMS key encryption. + You can enable or disable [log file validation](cloudtrail-log-file-validation-intro.md). Log file validation allows you to determine whether a log file was modified, deleted, or unchanged after CloudTrail delivered it. By default, log file validation is enabled. + You can configure a trail to send notifications to an Amazon SNS topic. + You can configure a trail to send events to a CloudWatch Logs log group. Both the log group and IAM role must exist in your own account. + You can update settings for management events, data events, network activity events, and Insights events. + You can add or remove tags. You can add up to 50 tag key pairs to help you identify your trails. Using the CloudTrail console to create or update a trail provides the following advantages. + If this is your first time creating a trail, using the CloudTrail console allows you to view the available feature and options. + If you are configuring a trail to log data events, using the CloudTrail console allows you to view the available data types. For more information, see [Logging data events](logging-data-events-with-cloudtrail.md). + If you are configuring a trail to network activity events, using the CloudTrail console allows you to view the available event sources. For more information, see [Logging network activity events](logging-network-events-with-cloudtrail.md). For information specific to creating a trail for an organization in AWS Organizations, see [Creating a trail for an organization](creating-trail-organization.md). **Topics** + [ # Creating a trail with the CloudTrail console ](cloudtrail-create-a-trail-using-the-console-first-time.md) + [ # Updating a trail with the CloudTrail console ](cloudtrail-update-a-trail-console.md) + [ # Deleting a trail with the CloudTrail console ](cloudtrail-delete-trails-console.md) + [ # Turning off logging for a trail ](cloudtrail-turning-off-logging.md) # Creating a trail with the CloudTrail console A trail can be applied to all AWS Regions that are [enabled](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-enable-standalone) in your AWS account, or can be applied to a single Region. A trail that applies to all AWS Regions that are enabled in your AWS account is referred to as a *multi-Region trail*. As a best practice, we recommend creating a multi-Region trail because it captures activity in all enabled Regions. All trails created using the CloudTrail console are multi-Region trails. You can only create a single-Region trail using the AWS CLI or [https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_CreateTrail.html](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_CreateTrail.html) API operation. **Note** After you create a trail, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see [AWS service integrations with CloudTrail logs](cloudtrail-aws-service-specific-topics.md#cloudtrail-aws-service-specific-topics-integrations). **Topics** + [ ## Creating a trail with the console ](#creating-a-trail-in-the-console) + [ ## Next steps ](#cloudtrail-create-a-trail-using-the-console-first-time-next-steps) ## Creating a trail with the console Use the following procedure to create a multi-Region trail. To log events in a single Region (not recommended), [use the AWS CLI](cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-create-trail.md#cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-examples-single). **To create a CloudTrail trail with the AWS Management Console** 1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/). 1. On the CloudTrail service home page, the **Trails** page, or the **Trails** section of the **Dashboard** page, choose **Create trail**. 1. On the **Create Trail** page, for **Trail name**, type a name for your trail. For more information, see [Naming requirements for CloudTrail resources, S3 buckets, and KMS keys](cloudtrail-trail-naming-requirements.md). 1. If this is an AWS Organizations organization trail, you can enable the trail for all accounts in your organization. To see this option, you must sign in to the console with a user or role in the management or delegated administrator account. To successfully create an organization trail, be sure that the user or role has [sufficient permissions](creating-an-organizational-trail-prepare.md#org_trail_permissions). For more information, see [Creating a trail for an organization](creating-trail-organization.md). 1. For **Storage location**, choose **Create new S3 bucket** to create a bucket. When you create a bucket, CloudTrail creates and applies the required bucket policies. If you choose to create a new S3 bucket, your IAM policy needs to include permission for the `s3:PutEncryptionConfiguration` action because by default server-side encryption is enabled for the bucket. **Note** If you chose **Use existing S3 bucket**, specify a bucket in **Trail log bucket name**, or choose **Browse** to choose a bucket in your own account. If you want to use a bucket in another account, you'll need to specify the bucket name. The bucket policy must grant CloudTrail permission to write to it. For information about manually editing the bucket policy, see [Amazon S3 bucket policy for CloudTrail](create-s3-bucket-policy-for-cloudtrail.md). To make it easier to find your logs, create a new folder (also known as a *prefix*) in an existing bucket to store your CloudTrail logs. Enter the prefix in **Prefix**. 1. For **Log file SSE-KMS encryption**, choose **Enabled** if you want to encrypt your log files and digest files using SSE-KMS encryption instead of SSE-S3 encryption. The default is **Enabled**. If you don't enable SSE-KMS encryption, your log files and digest files are encrypted using SSE-S3 encryption. For more information about SSE-KMS encryption, see [Using server-side encryption with AWS Key Management Service (SSE-KMS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html). For more information about SSE-S3 encryption, see [Using Server-Side Encryption with Amazon S3-Managed Encryption Keys (SSE-S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html). If you enable SSE-KMS encryption, choose a **New** or **Existing** AWS KMS key. In **AWS KMS Alias**, specify an alias, in the format `alias/`*MyAliasName*. For more information, see [Updating a resource to use your KMS key with the console](create-kms-key-policy-for-cloudtrail-update-trail.md). CloudTrail also supports AWS KMS multi-Region keys. For more information about multi-Region keys, see [Using multi-Region keys](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) in the *AWS Key Management Service Developer Guide*. **Note** You can also type the ARN of a key from another account. For more information, see [Updating a resource to use your KMS key with the console](create-kms-key-policy-for-cloudtrail-update-trail.md). The key policy must allow CloudTrail to use the key to encrypt your log files and digest files, and allow the users you specify to read log files or digest files in unencrypted form. For information about manually editing the key policy, see [Configure AWS KMS key policies for CloudTrail](create-kms-key-policy-for-cloudtrail.md). 1. In **Additional settings**, configure the following. 1. For **Log file validation**, choose **Enabled** to have log digests delivered to your S3 bucket. You can use the digest files to verify that your log files did not change after CloudTrail delivered them. For more information, see [Validating CloudTrail log file integrity](cloudtrail-log-file-validation-intro.md). 1. For **SNS notification delivery**, choose **Enabled** to be notified each time a log is delivered to your bucket. CloudTrail stores multiple events in a log file. SNS notifications are sent for every log file, not for every event. For more information, see [Configuring Amazon SNS notifications for CloudTrail](configure-sns-notifications-for-cloudtrail.md). If you enable SNS notifications, for **Create a new SNS topic**, choose **New** to create a topic, or choose **Existing** to use an existing topic. If you are creating a multi-Region trail, SNS notifications for log file deliveries from all enabled Regions are sent to the single SNS topic that you create. If you choose **New**, CloudTrail specifies a name for the new topic for you, or you can type a name. If you choose **Existing**, choose an SNS topic from the drop-down list. You can also enter the ARN of a topic from another Region or from an account with appropriate permissions. For more information, see [Amazon SNS topic policy for CloudTrail](cloudtrail-permissions-for-sns-notifications.md). If you create a topic, you must subscribe to the topic to be notified of log file delivery. You can subscribe from the Amazon SNS console. Due to the frequency of notifications, we recommend that you configure the subscription to use an Amazon SQS queue to handle notifications programmatically. For more information, see [Getting started with Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html) in the *Amazon Simple Notification Service Developer Guide*. 1. Optionally, configure CloudTrail to send log files to CloudWatch Logs by choosing **Enabled** in **CloudWatch Logs**. For more information, see [Sending events to CloudWatch Logs](send-cloudtrail-events-to-cloudwatch-logs.md). 1. If you enable integration with CloudWatch Logs, choose **New** to create a new log group, or **Existing** to use an existing one. If you choose **New**, CloudTrail specifies a name for the new log group for you, or you can type a name. 1. If you choose **Existing**, choose a log group from the drop-down list. 1. Choose **New** to create a new IAM role for permissions to send logs to CloudWatch Logs. Choose **Existing** to choose an existing IAM role from the drop-down list. The policy statement for the new or existing role is displayed when you expand **Policy document**. For more information about this role, see [Role policy document for CloudTrail to use CloudWatch Logs for monitoring](cloudtrail-required-policy-for-cloudwatch-logs.md). **Note** When you configure a trail, you can choose an S3 bucket and SNS topic that belong to another account. However, if you want CloudTrail to deliver events to a CloudWatch Logs log group, you must choose a log group that exists in your current account. Only the management account can configure a CloudWatch Logs log group for an organization trail using the console. The delegated administrator can configure a CloudWatch Logs log group using the AWS CLI or CloudTrail `CreateTrail` or `UpdateTrail` API operations. 1. For **Tags**, you can add up to 50 tag key pairs to help you identify, sort, and control access to your trail. Tags can help you identify both your CloudTrail trails and the Amazon S3 buckets that contain CloudTrail log files. You can then use resource groups for your CloudTrail resources. For more information, see [AWS Resource Groups](https://docs.aws.amazon.com/ARG/latest/userguide/resource-groups.html) and [Tags](cloudtrail-concepts.md#cloudtrail-concepts-tags). 1. On the **Choose log events** page, choose the event types that you want to log. For **Management events**, do the following. 1. For **API activity**, choose if you want your trail to log **Read** events, **Write** events, or both. For more information, see [Management events](logging-management-events-with-cloudtrail.md#logging-management-events). 1. Choose **Exclude AWS KMS events** to filter AWS Key Management Service (AWS KMS) events out of your trail. The default setting is to include all AWS KMS events. The option to log or exclude AWS KMS events is available only if you log management events on your trail. If you choose not to log management events, AWS KMS events are not logged, and you cannot change AWS KMS event logging settings. AWS KMS actions such as `Encrypt`, `Decrypt`, and `GenerateDataKey` typically generate a large volume (more than 99%) of events. These actions are now logged as **Read** events. Low-volume, relevant AWS KMS actions such as `Disable`, `Delete`, and `ScheduleKey` (which typically account for less than 0.5% of AWS KMS event volume) are logged as **Write** events. To exclude high-volume events like `Encrypt`, `Decrypt`, and `GenerateDataKey`, but still log relevant events such as `Disable`, `Delete` and `ScheduleKey`, choose to log **Write** management events, and clear the check box for **Exclude AWS KMS events**. 1. Choose **Exclude Amazon RDS Data API events** to filter Amazon Relational Database Service Data API events out of your trail. The default setting is to include all Amazon RDS Data API events. For more information about Amazon RDS Data API events, see [Logging Data API calls with AWS CloudTrail](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/logging-using-cloudtrail-data-api.html) in the *Amazon RDS User Guide for Aurora*. 1. To log data events, choose **Data events**. Additional charges apply for logging data events. For more information, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). 1. **Important** Steps 12-16 are for configuring data events using advanced event selectors, which is the default. Advanced event selectors let you configure more [resource types](logging-data-events-with-cloudtrail.md#logging-data-events) and offer fine-grained control over which data events your trail captures. If you opted to use basic event selectors, complete the steps in [Configure data event settings using basic event selectors](#trail-data-events-basic-selectors), then return to step 17 of this procedure. For **Resource type**, choose the resource type on which you want to log data events. For more information about available resource types, see [Data events](logging-data-events-with-cloudtrail.md#logging-data-events). 1. Choose a log selector template. You can choose a predefined template, or choose **Custom** to define your own event collection conditions. You can choose from the following predefined templates: + **Log all events** – Choose this template to log all events. + **Log only read events** – Choose this template to log only read events. Read-only events are events that do not change the state of a resource, such as `Get*` or `Describe*` events. + **Log only write events** – Choose this template to log only write events. Write events add, change, or delete resources, attributes, or artifacts, such as `Put*`, `Delete*`, or `Write*` events. + **Log only AWS Management Console events** – Choose this template to log only events originating from the AWS Management Console. + **Exclude AWS service initiated events** – Choose this template to exclude AWS service events, which have an `eventType` of `AwsServiceEvent`, and events initiated with AWS service-linked roles (SLRs). **Note** Choosing a predefined template for S3 buckets enables data event logging for all buckets currently in your AWS account and any buckets you create after you finish creating the trail. It also enables logging of data event activity performed by any IAM identity in your AWS account, even if that activity is performed on a bucket that belongs to another AWS account. If the trail applies only to one Region, choosing a predefined template that logs all S3 buckets enables data event logging for all buckets in the same Region as your trail and any buckets you create later in that Region. It will not log data events for Amazon S3 buckets in other Regions in your AWS account. If you are creating a multi-Region trail choosing a predefined template for Lambda functions enables data event logging for all functions currently in your AWS account, and any Lambda functions you might create in any Region after you finish creating the trail. If you are creating a trail for a single Region (done by using the AWS CLI), this selection enables data event logging for all functions currently in that Region in your AWS account, and any Lambda functions you might create in that Region after you finish creating the trail. It does not enable data event logging for Lambda functions created in other Regions. Logging data events for all functions also enables logging of data event activity performed by any IAM identity in your AWS account, even if that activity is performed on a function that belongs to another AWS account. 1. (Optional) In **Selector name**, enter a name to identify your selector. The selector name is a descriptive name for an advanced event selector, such as "Log data events for only two S3 buckets". The selector name is listed as `Name` in the advanced event selector and is viewable if you expand the **JSON view**. 1. If you selected **Custom**, in **Advanced event selectors** build an expression based on the values of advanced event selector fields. **Note** Selectors don't support the use of wildcards like `*` . To match multiple values with a single condition, you may use `StartsWith`, `EndsWith`, `NotStartsWith`, or `NotEndsWith` to explicitly match the beginning or end of the event field. 1. Choose from the following fields. + **`readOnly`** - `readOnly` can be set to **equals** a value of `true` or `false`. Read-only data events are events that do not change the state of a resource, such as `Get*` or `Describe*` events. Write events add, change, or delete resources, attributes, or artifacts, such as `Put*`, `Delete*`, or `Write*` events. To log both `read` and `write` events, don't add a `readOnly` selector. + **`eventName`** - `eventName` can use any operator. You can use it to include or exclude any data event logged to CloudTrail, such as `PutBucket`, `GetItem`, or `GetSnapshotBlock`. + **`eventSource`** – The event source to include or exclude. This field can use any operator. + **eventType** – The event type to include or exclude. For example, you can set this field to **not equals** `AwsServiceEvent` to exclude [AWS service events](non-api-aws-service-events.md). For a list of event types, see [`eventType`](cloudtrail-event-reference-record-contents.md#ct-event-type) in [CloudTrail record contents for management, data, and network activity events](cloudtrail-event-reference-record-contents.md). + **sessionCredentialFromConsole** – Include or exclude events originating from an AWS Management Console session. This field can be set to **equals** or **not equals** with a value of `true`. + **userIdentity.arn** – Include or exclude events for actions taken by specific IAM identities. For more information, see [CloudTrail userIdentity element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html). + **`resources.ARN`** - You can use any operator with `resources.ARN`, but if you use **equals** or **does not equal**, the value must exactly match the ARN of a valid resource of the type you've specified in the template as the value of `resources.type`. **Note** You can't use the `resources.ARN` field to filter resource types that do not have ARNs. For more information about the ARN formats of data event resources, see [Actions, resources, and condition keys for AWS services](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html) in the *Service Authorization Reference*. 1. For each field, choose **\$1 Condition** to add as many conditions as you need, up to a maximum of 500 specified values for all conditions. For example, to exclude data events for two S3 buckets from data events that are logged on your event data store, you can set the field to **resources.ARN**, set the operator for **does not start with**, and then paste in an S3 bucket ARN for which you do not want to log events. To add the second S3 bucket, choose **\$1 Condition**, and then repeat the preceding instruction, pasting in the ARN for or browsing for a different bucket. For information about how CloudTrail evaluates multiple conditions, see [How CloudTrail evaluates multiple conditions for a field](filtering-data-events.md#filtering-data-events-conditions). **Note** You can have a maximum of 500 values for all selectors on an event data store. This includes arrays of multiple values for a selector such as `eventName`. If you have single values for all selectors, you can have a maximum of 500 conditions added to a selector. 1. Choose **\$1 Field** to add additional fields as required. To avoid errors, do not set conflicting or duplicate values for fields. For example, do not specify an ARN in one selector to be equal to a value, then specify that the ARN not equal the same value in another selector. 1. To add another resource type on which to log data events, choose **Add data event type**. Repeat steps 12 through this step to configure advanced event selectors for the resource type. 1. To enable aggregation on data events, choose one or more aggregation templates. These templates define how your data events will be summarized. You can choose from the following templates: 1. **API Activity** to get 5-minute summaries of your data events based on the API calls made. Use this to understand your API usage patterns, including frequency, callers, and source. 1. **Resource Access** to get the activity patterns on your AWS resources. Use this to understand how your AWS resources are being accessed, how many times they are being accessed in the 5-minute window, who is accessing the resource, and what actions are being performed. 1. **User Actions** to get activity patterns based on IAM principals making API calls in your account. **Note** Aggregations apply to all data events collected in your trail. 1. To log network activity events, choose **Network activity events**. Network activity events enable VPC endpoint owners to record AWS API calls made using their VPC endpoints from a private VPC to the AWS service. Additional charges apply for logging network activity events. For more information, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). To log network activity events, do the following: 1. From **Network activity event source**, choose the source for network activity events. 1. In **Log selector template**, choose a template. You can choose to log all network activity events, log all network activity access denied events, or choose **Custom** to build a custom log selector to filter on multiple fields, such as `eventName` and `vpcEndpointId`. 1. (Optional) Enter a name to identify the selector. The selector name is listed as **Name** in the advanced event selector and is viewable if you expand the **JSON view**. 1. In **Advanced event selectors** build expressions by choosing values for **Field**, **Operator**, and **Value**. You can skip this step if you are using a predefined log template. 1. For excluding or including network activity events, you can choose from the following fields in the console. + **`eventName`** – You can use any operator with `eventName`. You can use it to include or exclude any event, such as `CreateKey`. + **`errorCode`** – You can use it to filter on an error code. Currently, the only supported `errorCode` is `VpceAccessDenied`. + **`vpcEndpointId`** – Identifies the VPC endpoint that the operation passed through. You can use any operator with `vpcEndpointId`. 1. For each field, choose **\$1 Condition** to add as many conditions as you need, up to a maximum of 500 specified values for all conditions. 1. Choose **\$1 Field** to add additional fields as required. To avoid errors, do not set conflicting or duplicate values for fields. 1. To add another event source for which you want to log network activity events, choose **Add network activity event selector**. 1. Optionally, expand **JSON view** to see your advanced event selectors as a JSON block. 1. Choose **Insights events** if you want your trail to log CloudTrail Insights events. In **Event type**, select **Insights events**. You must be logging **Write** management events to log Insights events for **API call rate**. You must be logging **Read** or **Write** management events to log Insights events for **API error rate**. CloudTrail Insights analyzes management events for unusual activity, and logs events when anomalies are detected. By default, trails don't log Insights events. For more information about Insights events, see [Working with CloudTrail Insights](logging-insights-events-with-cloudtrail.md). Additional charges apply for logging Insights events. For CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). Insights events are delivered to a different folder named `/CloudTrail-Insight`of the same S3 bucket that is specified in the **Storage location** area of the trail details page. CloudTrail creates the new prefix for you. For example, if your current destination S3 bucket is named `amzn-s3-demo-bucket/AWSLogs/CloudTrail/`, the S3 bucket name with a new prefix is named `amzn-s3-demo-bucket/AWSLogs/CloudTrail-Insight/`. 1. When you are finished choosing event types to log, choose **Next**. 1. On the **Review and create** page, review your choices. Choose **Edit** in a section to change the trail settings shown in that section. When you are ready to create the trail, choose **Create trail**. 1. The new trail appears on the **Trails** page. In about 5 minutes, CloudTrail publishes log files that show the AWS API calls made in your account. You can see the log files in the S3 bucket that you specified. If you enabled Insights events for a trail, CloudTrail may take up to 36 hours to begin delivering these events, provided that unusual activity is detected during that time. **Note** CloudTrail typically delivers logs within an average of about 5 minutes of an API call. This time is not guaranteed. Review the [AWS CloudTrail Service Level Agreement](https://aws.amazon.com/cloudtrail/sla) for more information. If you misconfigure your trail (for example, the S3 bucket is unreachable), CloudTrail will attempt to redeliver the log files to your S3 bucket for 30 days, and these attempted-to-deliver events will be subject to standard CloudTrail charges. To avoid charges on a misconfigured trail, you need to delete the trail. ### Configure data event settings using basic event selectors You can use advanced event selectors to configure all data event types as well as network activity events. Advanced event selectors allow you to create fine-grained selectors to log only those events of interest. If you use basic event selectors to log data events, you're limited to logging data events for Amazon S3 buckets, AWS Lambda functions, and Amazon DynamoDB tables. You can't filter on the `eventName` field using basic event selectors. You also can't log [network activity events](logging-network-events-with-cloudtrail.md). ![\[Basic event selectors for data events on a trail\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/images/cloudtrail-data-basic-selectors.png) Use the following procedure to configure data event settings using basic event selectors. **To configure data event settings using basic event selectors** 1. In **Events**, choose **Data events** to log data events. Additional charges apply for logging data events. For more information, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). 1. For Amazon S3 buckets: 1. For **Data event source**, choose **S3**. 1. You can choose to log **All current and future S3 buckets**, or you can specify individual buckets or functions. By default, data events are logged for all current and future S3 buckets. **Note** Keeping the default **All current and future S3 buckets** option enables data event logging for all buckets currently in your AWS account and any buckets you create after you finish creating the trail. It also enables logging of data event activity performed by any IAM identity in your AWS account, even if that activity is performed on a bucket that belongs to another AWS account. If you are creating a trail for a single Region (done by using the AWS CLI), choosing **All current and future S3 buckets** enables data event logging for all buckets in the same Region as your trail and any buckets you create later in that Region. It will not log data events for Amazon S3 buckets in other Regions in your AWS account. 1. If you leave the default, **All current and future S3 buckets**, choose to log **Read** events, **Write** events, or both. 1. To select individual buckets, empty the **Read** and **Write** check boxes for **All current and future S3 buckets**. In **Individual bucket selection**, browse for a bucket on which to log data events. Find specific buckets by typing a bucket prefix for the bucket you want. You can select multiple buckets in this window. Choose **Add bucket** to log data events for more buckets. Choose to log **Read** events, such as `GetObject`, **Write** events, such as `PutObject`, or both. This setting takes precedence over individual settings you configure for individual buckets. For example, if you specify logging **Read** events for all S3 buckets, and then choose to add a specific bucket for data event logging, **Read** is already selected for the bucket you added. You cannot clear the selection. You can only configure the option for **Write**. To remove a bucket from logging, choose **X**. 1. To add another resource type on which to log data events, choose **Add data event type**. 1. For Lambda functions: 1. For **Data event source**, choose **Lambda**. 1. In **Lambda function**, choose **All regions** to log all Lambda functions, or **Input function as ARN** to log data events on a specific function. To log data events for all Lambda functions in your AWS account, select **Log all current and future functions**. This setting takes precedence over individual settings you configure for individual functions. All functions are logged, even if all functions are not displayed. **Note** If you're creating a multi-Region trail, this selection enables data event logging for all functions currently in your AWS account, and any Lambda functions you might create in any Region after you finish creating the trail. If you are creating a trail for a single Region (done by using the AWS CLI), this selection enables data event logging for all functions currently in that Region in your AWS account, and any Lambda functions you might create in that Region after you finish creating the trail. It does not enable data event logging for Lambda functions created in other Regions. Logging data events for all functions also enables logging of data event activity performed by any IAM identity in your AWS account, even if that activity is performed on a function that belongs to another AWS account. 1. If you choose **Input function as ARN**, enter the ARN of a Lambda function. **Note** If you have more than 15,000 Lambda functions in your account, you cannot view or select all functions in the CloudTrail console when creating a trail. You can still select the option to log all functions, even if they are not displayed. If you want to log data events for specific functions, you can manually add a function if you know its ARN. You can also finish creating the trail in the console, and then use the AWS CLI and the **put-event-selectors** command to configure data event logging for specific Lambda functions. For more information, see [Managing trails with the AWS CLI](cloudtrail-additional-cli-commands.md). 1. For DynamoDB tables: 1. For **Data event source**, choose **DynamoDB**. 1. In **DynamoDB table selection**, choose **Browse** to select a table, or paste in the ARN of a DynamoDB table to which you have access. A DynamoDB table ARN uses the following format: ``` arn:partition:dynamodb:region:account_ID:table/table_name ``` To add another table, choose **Add row**, and browse for a table or paste in the ARN of a table to which you have access. 1. To configure Insights events and other settings for your trail, go back to the preceding procedure in this topic, [Creating a trail with the console](#creating-a-trail-in-the-console). ## Next steps After you create your trail, you can return to the trail to make changes: + If you haven't already, you can configure CloudTrail to send log files to CloudWatch Logs. For more information, see [Sending events to CloudWatch Logs](send-cloudtrail-events-to-cloudwatch-logs.md). + Create a table and use it to run a query in Amazon Athena to analyze your AWS service activity. For more information, see [Creating a Table for CloudTrail Logs in the CloudTrail Console](https://docs.aws.amazon.com/athena/latest/ug/cloudtrail-logs.html#create-cloudtrail-table-ct) in the [Amazon Athena User Guide](https://docs.aws.amazon.com/athena/latest/ug/). + Add custom tags (key-value pairs) to the trail. + To create another trail, open the **Trails** page, and choose **Create trail**. # Updating a trail with the CloudTrail console This section describes how to change trail settings. To convert a single-Region trail to a multi-Region trail, or update a multi-Region trail to log events in only a single Region, you must use the AWS CLI. For more information about how to convert a single-Region trail to a multi-Region trail, see [Converting a single-Region trail to a multi-Region trail](cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-update-trail.md#cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-examples-convert). For more information about how to update a multi-Region trail to log events in a single Region, see [Converting a multi-Region trail to a single-Region trail](cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-update-trail.md#cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-examples-reduce). If you've enabled CloudTrail management events in Amazon Security Lake, you are required to maintain at least one organizational trail that is multi-Region and logs both `read` and `write` management events. You cannot update a qualifying trail in such a way that it fails to meet the Security Lake requirement. For example, by changing the trail to single-Region, or by turning off the logging of `read` or `write` management events. **Note** CloudTrail updates organization trails in member accounts even if a resource validation fails. Examples of validation failures include: an incorrect Amazon S3 bucket policy an incorrect Amazon SNS topic policy inability to deliver to a CloudWatch Logs log group insufficient permission to encrypt using a KMS key A member account with CloudTrail permissions can see any validation failures for an organization trail by viewing the trail's details page on the CloudTrail console, or by running the AWS CLI [https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html) command. **To update a trail with the AWS Management Console** 1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/). 1. In the navigation pane, choose **Trails**, and then choose a trail name. 1. In **General details**, choose **Edit** to change the following settings. You cannot change the name of a trail. + **Apply trail to my organization** - Change whether this trail is an AWS Organizations organization trail. **Note** Only the management account for the organization can convert an organization trail to a non-organization trail, or convert a non-organization trail to an organization trail. + **Trail log location** - Change the name of the S3 bucket or prefix in which you are storing logs for this trail. + **Log file SSE-KMS encryption** - Choose to enable or disable encrypting log files with SSE-KMS instead of SSE-S3. + **Log file validation** - Choose to enable or disable validation of the integrity of log files. + **SNS notification delivery** - Choose to enable or disable Amazon Simple Notification Service (Amazon SNS) notifications that log files have been delivered to the bucket specified for the trail. 1. To change the trail to an AWS Organizations organization trail, you can choose to enable the trail for all accounts in your organization. For more information, see [Creating a trail for an organization](creating-trail-organization.md). 1. To change the specified bucket in **Storage location**, choose **Create new S3 bucket** to create a bucket. When you create a bucket, CloudTrail creates and applies the required bucket policies. If you choose to create a new S3 bucket, your IAM policy needs to include permission for the `s3:PutEncryptionConfiguration` action because by default server-side encryption is enabled for the bucket. **Note** If you chose **Use existing S3 bucket**, specify a bucket in **Trail log bucket name**, or choose **Browse** to choose a bucket. The bucket policy must grant CloudTrail permission to write to it. For information about manually editing the bucket policy, see [Amazon S3 bucket policy for CloudTrail](create-s3-bucket-policy-for-cloudtrail.md). To make it easier to find your logs, create a new folder (also known as a *prefix*) in an existing bucket to store your CloudTrail logs. Enter the prefix in **Prefix**. 1. For **Log file SSE-KMS encryption**, choose **Enabled** if you want to encrypt your log files and digest files using SSE-KMS encryption instead of SSE-S3 encryption. The default is **Enabled**. If you don't enable SSE-KMS encryption, your log files and digest files are encrypted using SSE-S3 encryption. For more information about SSE-KMS encryption, see [Using server-side encryption with AWS Key Management Service (SSE-KMS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html). For more information about SSE-S3 encryption, see [Using Server-Side Encryption with Amazon S3-Managed Encryption Keys (SSE-S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html). If you enable SSE-KMS encryption, choose a **New** or **Existing** AWS KMS key. In **AWS KMS Alias**, specify an alias, in the format `alias/`*MyAliasName*. For more information, see [Updating a resource to use your KMS key with the console](create-kms-key-policy-for-cloudtrail-update-trail.md). CloudTrail also supports AWS KMS multi-Region keys. For more information about multi-Region keys, see [Using multi-Region keys](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) in the *AWS Key Management Service Developer Guide*. **Note** You can also type the ARN of a key from another account. For more information, see [Updating a resource to use your KMS key with the console](create-kms-key-policy-for-cloudtrail-update-trail.md). The key policy must allow CloudTrail to use the key to encrypt your log files and digest files, and allow the users you specify to read log files or digest files in unencrypted form. For information about manually editing the key policy, see [Configure AWS KMS key policies for CloudTrail](create-kms-key-policy-for-cloudtrail.md). 1. For **Log file validation**, choose **Enabled** to have log digests delivered to your S3 bucket. You can use the digest files to verify that your log files did not change after CloudTrail delivered them. For more information, see [Validating CloudTrail log file integrity](cloudtrail-log-file-validation-intro.md). 1. For **SNS notification delivery**, choose **Enabled** to be notified each time a log is delivered to your bucket. CloudTrail stores multiple events in a log file. SNS notifications are sent for every log file, not for every event. For more information, see [Configuring Amazon SNS notifications for CloudTrail](configure-sns-notifications-for-cloudtrail.md). If you enable SNS notifications, for **Create a new SNS topic**, choose **New** to create a topic, or choose **Existing** to use an existing topic. If you are creating multi-Region trail, SNS notifications for log file deliveries from all enabled Regions are sent to the single SNS topic that you create. If you choose **New**, CloudTrail specifies a name for the new topic for you, or you can type a name. If you choose **Existing**, choose an SNS topic from the drop-down list. You can also enter the ARN of a topic from another Region or from an account with appropriate permissions. For more information, see [Amazon SNS topic policy for CloudTrail](cloudtrail-permissions-for-sns-notifications.md). If you create a topic, you must subscribe to the topic to be notified of log file delivery. You can subscribe from the Amazon SNS console. Due to the frequency of notifications, we recommend that you configure the subscription to use an Amazon SQS queue to handle notifications programmatically. For more information, see [Getting started with Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html) in the *Amazon Simple Notification Service Developer Guide*. 1. In **CloudWatch Logs**, choose **Edit** to change settings for sending CloudTrail log files to CloudWatch Logs. Choose **Enabled** in **CloudWatch Logs** to enable sending log files. For more information, see [Sending events to CloudWatch Logs](send-cloudtrail-events-to-cloudwatch-logs.md). 1. If you enable integration with CloudWatch Logs, choose **New** to create a new log group, or **Existing** to use an existing one. If you choose **New**, CloudTrail specifies a name for the new log group for you, or you can type a name. 1. If you choose **Existing**, choose a log group from the drop-down list. 1. Choose **New** to create a new IAM role for permissions to send logs to CloudWatch Logs. Choose **Existing** to choose an existing IAM role from the drop-down list. The policy statement for the new or existing role is displayed when you expand **Policy document**. For more information about this role, see [Role policy document for CloudTrail to use CloudWatch Logs for monitoring](cloudtrail-required-policy-for-cloudwatch-logs.md). **Note** When you configure a trail, you can choose an S3 bucket and SNS topic that belong to another account. However, if you want CloudTrail to deliver events to a CloudWatch Logs log group, you must choose a log group that exists in your current account. Only the management account can configure a CloudWatch Logs log group for an organization trail using the console. The delegated administrator can configure a CloudWatch Logs log group using the AWS CLI or CloudTrail `CreateTrail` or `UpdateTrail` API operations. 1. In **Tags**, choose **Edit** to change, add, or delete tags on the trail. You can add up to 50 tag key pairs to help you identify, sort, and control access to your trail. Tags can help you identify both your CloudTrail trails and the Amazon S3 buckets that contain CloudTrail log files. You can then use resource groups for your CloudTrail resources. For more information, see [AWS Resource Groups](https://docs.aws.amazon.com/ARG/latest/userguide/resource-groups.html) and [Tags](cloudtrail-concepts.md#cloudtrail-concepts-tags). 1. In **Management events**, choose **Edit** to change management event logging settings. 1. For **API activity**, choose if you want your trail to log **Read** events, **Write** events, or both. For more information, see [Management events](logging-management-events-with-cloudtrail.md#logging-management-events). 1. Choose **Exclude AWS KMS events** to filter AWS Key Management Service (AWS KMS) events out of your trail. The default setting is to include all AWS KMS events. The option to log or exclude AWS KMS events is available only if you log management events on your trail. If you choose not to log management events, AWS KMS events are not logged, and you cannot change AWS KMS event logging settings. AWS KMS actions such as `Encrypt`, `Decrypt`, and `GenerateDataKey` typically generate a large volume (more than 99%) of events. These actions are now logged as **Read** events. Low-volume, relevant AWS KMS actions such as `Disable`, `Delete`, and `ScheduleKey` (which typically account for less than 0.5% of AWS KMS event volume) are logged as **Write** events. To exclude high-volume events like `Encrypt`, `Decrypt`, and `GenerateDataKey`, but still log relevant events such as `Disable`, `Delete` and `ScheduleKey`, choose to log **Write** management events, and clear the check box for **Exclude AWS KMS events**. 1. Choose **Exclude Amazon RDS Data API events** to filter Amazon Relational Database Service Data API events out of your trail. The default setting is to include all Amazon RDS Data API events. For more information about Amazon RDS Data API events, see [Logging Data API calls with AWS CloudTrail](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/logging-using-cloudtrail-data-api.html) in the *Amazon RDS User Guide for Aurora*. 1. **Important** Steps 7-11 are for configuring data events using advanced event selectors, which is the default. Advanced event selectors let you configure more [data event types](logging-data-events-with-cloudtrail.md#logging-data-events) and offer fine-grained control over which data events your trail captures. If you plan to log network activity events, you must use advanced event selectors. If you are using basic event selectors, see [Updating data event settings with basic event selectors](#cloudtrail-update-basic-event-selectors-console), then return to step 12 of this procedure. In **Data events**, choose **Edit** to change data event logging settings. By default, trails don't log data events. Additional charges apply for logging data events. For CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). For **Resource type**, choose the resource type on which you want to log data events. For more information about available resource types, see [Data events](logging-data-events-with-cloudtrail.md#logging-data-events). 1. Choose a log selector template. You can choose a predefined template, or choose **Custom** to define your own event collection conditions. You can choose from the following predefined templates: + **Log all events** – Choose this template to log all events. + **Log only read events** – Choose this template to log only read events. Read-only events are events that do not change the state of a resource, such as `Get*` or `Describe*` events. + **Log only write events** – Choose this template to log only write events. Write events add, change, or delete resources, attributes, or artifacts, such as `Put*`, `Delete*`, or `Write*` events. + **Log only AWS Management Console events** – Choose this template to log only events originating from the AWS Management Console. + **Exclude AWS service initiated events** – Choose this template to exclude AWS service events, which have an `eventType` of `AwsServiceEvent`, and events initiated with AWS service-linked roles (SLRs). **Note** Choosing a predefined template for S3 buckets enables data event logging for all buckets currently in your AWS account and any buckets you create after you finish creating the trail. It also enables logging of data event activity performed by any user or role in your AWS account, even if that activity is performed on a bucket that belongs to another AWS account. If the trail applies only to one Region, choosing a predefined template that logs all S3 buckets enables data event logging for all buckets in the same Region as your trail and any buckets you create later in that Region. It will not log data events for Amazon S3 buckets in other Regions in your AWS account. If you're creating a multi-Region trail, choosing a predefined template for Lambda functions enables data event logging for all functions currently in your AWS account, and any Lambda functions you might create in any Region after you finish creating the trail. If you are creating a trail for a single Region (done by using the AWS CLI), this selection enables data event logging for all functions currently in that Region in your AWS account, and any Lambda functions you might create in that Region after you finish creating the trail. It does not enable data event logging for Lambda functions created in other Regions. Logging data events for all functions also enables logging of data event activity performed by any user or role in your AWS account, even if that activity is performed on a function that belongs to another AWS account. 1. (Optional) In **Selector name**, enter a name to identify your selector. The selector name is a descriptive name for an advanced event selector, such as "Log data events for only two S3 buckets". The selector name is listed as `Name` in the advanced event selector and is viewable if you expand the **JSON view**. 1. If you selected **Custom**, in **Advanced event selectors** build an expression based on the values of advanced event selector fields. **Note** Selectors don't support the use of wildcards like `*` . To match multiple values with a single condition, you may use `StartsWith`, `EndsWith`, `NotStartsWith`, or `NotEndsWith` to explicitly match the beginning or end of the event field. 1. Choose from the following fields. + **`readOnly`** - `readOnly` can be set to **equals** a value of `true` or `false`. Read-only data events are events that do not change the state of a resource, such as `Get*` or `Describe*` events. Write events add, change, or delete resources, attributes, or artifacts, such as `Put*`, `Delete*`, or `Write*` events. To log both `read` and `write` events, don't add a `readOnly` selector. + **`eventName`** - `eventName` can use any operator. You can use it to include or exclude any data event logged to CloudTrail, such as `PutBucket`, `GetItem`, or `GetSnapshotBlock`. + **`eventSource`** – The event source to include or exclude. This field can use any operator. + **eventType** – The event type to include or exclude. For example, you can set this field to **not equals** `AwsServiceEvent` to exclude [AWS service events](non-api-aws-service-events.md). For a list of event types, see [`eventType`](cloudtrail-event-reference-record-contents.md#ct-event-type) in [CloudTrail record contents for management, data, and network activity events](cloudtrail-event-reference-record-contents.md). + **sessionCredentialFromConsole** – Include or exclude events originating from an AWS Management Console session. This field can be set to **equals** or **not equals** with a value of `true`. + **userIdentity.arn** – Include or exclude events for actions taken by specific IAM identities. For more information, see [CloudTrail userIdentity element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html). + **`resources.ARN`** - You can use any operator with `resources.ARN`, but if you use **equals** or **does not equal**, the value must exactly match the ARN of a valid resource of the type you've specified in the template as the value of `resources.type`. **Note** You can't use the `resources.ARN` field to filter resource types that do not have ARNs. For more information about the ARN formats of data event resources, see [Actions, resources, and condition keys for AWS services](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html) in the *Service Authorization Reference*. 1. For each field, choose **\$1 Condition** to add as many conditions as you need, up to a maximum of 500 specified values for all conditions. For example, to exclude data events for two S3 buckets from data events that are logged on your event data store, you can set the field to **resources.ARN**, set the operator for **does not start with**, and then paste in an S3 bucket ARN for which you do not want to log events. To add the second S3 bucket, choose **\$1 Condition**, and then repeat the preceding instruction, pasting in the ARN for or browsing for a different bucket. For information about how CloudTrail evaluates multiple conditions, see [How CloudTrail evaluates multiple conditions for a field](filtering-data-events.md#filtering-data-events-conditions). **Note** You can have a maximum of 500 values for all selectors on an event data store. This includes arrays of multiple values for a selector such as `eventName`. If you have single values for all selectors, you can have a maximum of 500 conditions added to a selector. 1. Choose **\$1 Field** to add additional fields as required. To avoid errors, do not set conflicting or duplicate values for fields. For example, do not specify an ARN in one selector to be equal to a value, then specify that the ARN not equal the same value in another selector. 1. To add another resource type on which to log data events, choose **Add data event type**. Repeat steps 3 through this step to configure advanced event selectors for the resource type. 1. In **Network activity events**, choose **Edit** to change network activity event logging settings. By default, trails don't log network activity events. Additional charges apply for logging network activity events. For more information, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). To log network activity events, do the following: 1. From **Network activity event source**, choose the source for network activity events. 1. In **Log selector template**, choose a template. You can choose to log all network activity events, log all network activity access denied events, or choose **Custom** to build a custom log selector to filter on multiple fields, such as `eventName` and `vpcEndpointId`. 1. (Optional) Enter a name to identify the selector. The selector name is listed as **Name** in the advanced event selector and is viewable if you expand the **JSON view**. 1. In **Advanced event selectors** build expressions by choosing values for **Field**, **Operator**, and **Value**. You can skip this step if you are using a predefined log template. 1. For excluding or including network activity events, you can choose from the following fields in the console. + **`eventName`** – You can use any operator with `eventName`. You can use it to include or exclude any event, such as `CreateKey`. + **`errorCode`** – You can use it to filter on an error code. Currently, the only supported `errorCode` is `VpceAccessDenied`. + **`vpcEndpointId`** – Identifies the VPC endpoint that the operation passed through. You can use any operator with `vpcEndpointId`. 1. For each field, choose **\$1 Condition** to add as many conditions as you need, up to a maximum of 500 specified values for all conditions. 1. Choose **\$1 Field** to add additional fields as required. To avoid errors, do not set conflicting or duplicate values for fields. 1. To add another event source for which you want to log network activity events, choose **Add network activity event selector**. 1. Optionally, expand **JSON view** to see your advanced event selectors as a JSON block. 1. In **Insights events**, choose **Edit** if you want your trail to log CloudTrail Insights events. In **Event type**, select **Insights events**. In **Insights events**, choose **API call rate**, **API error rate**, or both. You must be logging **Write** management events to log Insights events for **API call rate**. You must be logging **Read** or **Write** management events to log Insights events for **API error rate**. CloudTrail Insights analyzes management events for unusual activity, and logs events when anomalies are detected. By default, trails don't log Insights events. For more information about Insights events, see [Working with CloudTrail Insights](logging-insights-events-with-cloudtrail.md). Additional charges apply for logging Insights events. For CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). Insights events are delivered to a different folder named `/CloudTrail-Insight`of the same S3 bucket that is specified in the **Storage location** area of the trail details page. CloudTrail creates the new prefix for you. For example, if your current destination S3 bucket is named `amzn-s3-demo-bucket/AWSLogs/CloudTrail/`, the S3 bucket name with a new prefix is named `amzn-s3-demo-bucket/AWSLogs/CloudTrail-Insight/`. 1. When you are finished changing settings on your trail, choose **Update trail**. ## Updating data event settings with basic event selectors You can use advanced event selectors to configure all data event types as well as network activity events. Advanced event selectors allow you to create fine-grained selectors to log only those events of interest. If you use basic event selectors to log data events, you're limited to logging data events for Amazon S3 buckets, AWS Lambda functions, and Amazon DynamoDB tables. You can't filter on the `eventName` field using basic event selectors. You also can't log [network activity events](logging-network-events-with-cloudtrail.md). ![\[Basic event selectors for data events on a trail\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/images/cloudtrail-data-basic-selectors.png) Use the following procedure to configure data event settings using basic event selectors. 1. In **Data events**, choose **Edit** to change data event logging settings. With basic event selectors, you can specify logging data events for Amazon S3 buckets, AWS Lambda functions, DynamoDBtables, or a combination of those resources. Additional data event resource types are supported with advanced event selectors. By default, trails don't log data events. Additional charges apply for logging data events. For more information, see [Data events](logging-data-events-with-cloudtrail.md#logging-data-events). For CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). For Amazon S3 buckets: 1. For **Data event source**, choose **S3**. 1. You can choose to log **All current and future S3 buckets**, or you can specify individual buckets or functions. By default, data events are logged for all current and future S3 buckets. **Note** Keeping the default **All current and future S3 buckets** option enables data event logging for all buckets currently in your AWS account and any buckets you create after you finish creating the trail. It also enables logging of data event activity performed by any user or role in your AWS account, even if that activity is performed on a bucket that belongs to another AWS account. If the trail applies only to one Region, choosing **All current and future S3 buckets** enables data event logging for all buckets in the same Region as your trail and any buckets you create later in that Region. It will not log data events for Amazon S3 buckets in other Regions in your AWS account. 1. If you leave the default, **All current and future S3 buckets**, choose to log **Read** events, **Write** events, or both. 1. To select individual buckets, empty the **Read** and **Write** check boxes for **All current and future S3 buckets**. In **Individual bucket selection**, browse for a bucket on which to log data events. To find specific buckets, type a bucket prefix for the bucket you want. You can select multiple buckets in this window. Choose **Add bucket** to log data events for more buckets. Choose to log **Read** events, such as `GetObject`, **Write** events, such as `PutObject`, or both. This setting takes precedence over individual settings you configure for individual buckets. For example, if you specify logging **Read** events for all S3 buckets, and then choose to add a specific bucket for data event logging, **Read** is already selected for the bucket you added. You cannot clear the selection. You can only configure the option for **Write**. To remove a bucket from logging, choose **X**. 1. To add another resource type on which to log data events, choose **Add data event type**. 1. For Lambda functions: 1. For **Data event source**, choose **Lambda**. 1. In **Lambda function**, choose **All regions** to log all Lambda functions, or **Input function as ARN** to log data events on a specific function. To log data events for all Lambda functions in your AWS account, select **Log all current and future functions**. This setting takes precedence over individual settings you configure for individual functions. All functions are logged, even if all functions are not displayed. **Note** If you're creating a multi-Region trail, this selection enables data event logging for all functions currently in your AWS account, and any Lambda functions you might create in any Region after you finish creating the trail. If you are creating a trail for a single Region (done by using the AWS CLI), this selection enables data event logging for all functions currently in that Region in your AWS account, and any Lambda functions you might create in that Region after you finish creating the trail. It does not enable data event logging for Lambda functions created in other Regions. Logging data events for all functions also enables logging of data event activity performed by any user or role in your AWS account, even if that activity is performed on a function that belongs to another AWS account. 1. If you choose **Input function as ARN**, enter the ARN of a Lambda function. **Note** If you have more than 15,000 Lambda functions in your account, you cannot view or select all functions in the CloudTrail console when creating a trail. You can still select the option to log all functions, even if they are not displayed. If you want to log data events for specific functions, you can manually add a function if you know its ARN. You can also finish creating the trail in the console, and then use the AWS CLI and the **put-event-selectors** command to configure data event logging for specific Lambda functions. For more information, see [Managing trails with the AWS CLI](cloudtrail-additional-cli-commands.md). 1. To add another resource type on which to log data events, choose **Add data event type**. 1. For DynamoDB tables: 1. For **Data event source**, choose **DynamoDB**. 1. In **DynamoDB table selection**, choose **Browse** to select a table, or paste in the ARN of a DynamoDB table to which you have access. A DynamoDB table ARN is in the following format: ``` arn:partition:dynamodb:region:account_ID:table/table_name ``` To add another table, choose **Add row**, and browse for a table or paste in the ARN of a table to which you have access. 1. To configure Insights events and other settings for your trail, go back to the preceding procedure in this topic, [Updating a trail with the CloudTrail console](#cloudtrail-update-a-trail-console). # Deleting a trail with the CloudTrail console You can delete trails with the CloudTrail console. If an organization's management account or delegated administrator account deletes an organization trail, the trail is removed from all member accounts of the organization. **Important** While deleting a CloudTrail trail is an irreversible action, CloudTrail does not delete log files in the Amazon S3 bucket for that trail, the Amazon S3 bucket itself, or the CloudWatch log group to which the trail delivers events. Deleting a multi-Region trail will stop logging of events in all AWS Regions enabled in your AWS account. Deleting a single-Region trail will stop logging of events in that Region only. It will not stop logging of events in other Regions even if the trails in those other Regions have identical names to the deleted trail. For information about account closure and deletion of CloudTrail trails, see [AWS account closure and trails](cloudtrail-account-closure.md). If you've enabled CloudTrail management events in Amazon Security Lake, you are required to maintain at least one organizational trail that is multi-Region and logs both `read` and `write` management events. You cannot delete a trail if it is the only trail you have that meets this requirement, unless you turn off CloudTrail management events in Security Lake. **To delete a trail with the CloudTrail console** 1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/). 1. Open the **Trails** page of the CloudTrail console. 1. Choose the trail name. 1. At the top of the trail details page, choose **Delete**. 1. When you are prompted to confirm, choose **Delete** to delete the trail permanently. The trail is removed from the list of trails. Log files that were already delivered to the Amazon S3 bucket are not deleted and continue to incur S3 charges. **Note** Content delivered to Amazon S3 buckets might contain customer content. For more information about removing sensitive data, see [Emptying a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/empty-bucket.html) and [Deleting a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/delete-bucket.html) in the *Amazon S3 User Guide*. # Turning off logging for a trail When you create a trail, logging is turned on automatically. You can turn off logging for a trail from the trail's details page. **Note** When you turn off logging, existing logs are still stored in the trail's Amazon S3 bucket and continue to incur S3 charges. For information on S3 pricing, see [Amazon S3 pricing](https://aws.amazon.com/s3/pricing/). **Event delivery after logging is stopped** After you turn off logging for a trail, the trail can still receive events that occurred before logging was turned off. Events can be delayed for a number of reasons, including high network traffic, connectivity issues, a service outage, or updates to existing events. CloudTrail uses the most recent time that logging was turned off to determine whether to deliver delayed events, rather than the logging state of the trail at the time the event occurred. As a result, delayed events that occurred before logging was last turned off can still be delivered to the trail. For more information about delayed event delivery, see the `addendum` field in [CloudTrail record contents for management, data, and network activity events](cloudtrail-event-reference-record-contents.md). Additionally, event selectors and advanced event selectors are not evaluated for delayed events delivered to a trail after logging is turned off. This means that a trail can receive any type of event that occurred before logging was turned off, regardless of the trail's event selector configuration. **To turn off logging for a trail with the CloudTrail console** 1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/). 1. In the navigation pane, choose **Trails**, and then choose the name of the trail. 1. At the top of the trail details page, choose **Stop logging** to turn off logging for the trail. 1. When you are prompted to confirm, choose **Stop logging**. CloudTrail stops logging activity for that trail. 1. To resume logging for that trail, choose **Start logging** on the trail configuration page. # Creating, updating, and managing trails with the AWS CLI You can use the AWS CLI to create, update, and manage your trails. 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. **Note** You need the AWS command line tools to run the AWS Command Line Interface (AWS CLI) commands in this topic. Make sure you have a recent version of the AWS CLI installed. For more information, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/). For help with CloudTrail commands at the AWS CLI command line, type `aws cloudtrail help`. ## Commonly used commands for trail creation, management, and status Some of the more commonly used commands for creating and updating trails in CloudTrail include: + **[create-trail](cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-create-trail.md)** to create a trail. + **[update-trail](cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-update-trail.md)** to change the configuration of an existing trail. + **[add-tags](cloudtrail-additional-cli-commands.md#cloudtrail-additional-cli-commands-add-tag)** to add one or more tags (key-value pairs) to an existing trail. + **[remove-tags](cloudtrail-additional-cli-commands.md#cloudtrail-additional-cli-commands-remove-tag)** to remove one or more tags from a trail. + **[list-tags](cloudtrail-additional-cli-commands.md#cloudtrail-additional-cli-commands-list-tags)** to return a list of tags associated with a trail. + **[put-event-selectors](cloudtrail-additional-cli-commands.md#configuring-adv-event-selector-examples)** to add or modify event selectors for a trail. + **[put-insight-selectors](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_PutInsightSelectors.html)** to add or modify Insights event selectors for an existing trail, and enable or disable Insights events. + **[start-logging](cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-create-trail.md#cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-examples-single-start-logging)** to begin logging events with your trail. + **[stop-logging](cloudtrail-additional-cli-commands.md#cloudtrail-start-stop-logging-cli-commands)** to pause logging events with your trail. + **[delete-trail](cloudtrail-additional-cli-commands.md#cloudtrail-delete-trail-cli)** to delete a trail. This command does not delete the Amazon S3 bucket that contains the log files for that trail, if any. + **[describe-trails](cloudtrail-additional-cli-commands.md#cloudtrail-additional-cli-commands-retrieve)** to return information about trails in an AWS Region. + **[get-trail](cloudtrail-additional-cli-commands.md#cloudtrail-additional-cli-commands-retrieve)** to return settings information for a trail. + **[get-trail-status](cloudtrail-additional-cli-commands.md#cloudtrail-additional-cli-commands-retrieve)** to return information about the current status of a trail. + **[get-event-selectors](cloudtrail-additional-cli-commands.md#configuring-adv-event-selector-examples)** to return information about event selectors configured for a trail. + **[get-insight-selectors](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_GetInsightSelectors.html)** to return information about Insights event selectors configured for a trail. ### Supported commands for creating and updating trails: create-trail and update-trail The `create-trail` and `update-trail` commands offer a variety of functionality for creating and managing trails, including: + Creating a trail that receives logs across Regions, or update a trail with the `--is-multi-region-trail` option. In most circumstances, you should create trails that log events in all AWS Regions. + Creating a trail that receives logs for all AWS accounts in an organization with the **--is-organization-trail** option. + Converting a multi-Region trail to single-Region trail with the `--no-is-multi-region-trail` option. + Enabling or disabling log file encryption with the `--kms-key-id` option. The option specifies an AWS KMS key that you already created and to which you have attached a policy that allows CloudTrail to encrypt your logs. For more information, see [Enabling and disabling encryption for CloudTrail log files, digest files and event data stores with the AWS CLI](cloudtrail-log-file-encryption-cli.md). + Enabling or disabling 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](cloudtrail-log-file-validation-intro.md). + Specifying 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](monitor-cloudtrail-log-files-with-cloudwatch-logs.md). ### Deprecated commands: create-subscription and update-subscription **Important** The `create-subscription` and `update-subscription` commands were used to create and update trails, but are deprecated. Do not use these commands. They do not provide full functionality for creating and managing trails. If you configured automation that uses one or both of these commands, we recommend that you update your code or scripts to use supported commands such as **create-trail**. # Using the `create-trail` command to create a trail You can run the `create-trail` command to create trails that are specifically configured to meet your business needs. 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. ## Creating a multi-Region trail A trail can be applied to all AWS Regions that are [enabled](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-enable-standalone) in your AWS account, or can be applied to a single Region. A trail that applies to all AWS Regions that are enabled in your AWS account is referred to as a *multi-Region trail*. As a best practice, we recommend creating a multi-Region trail because it captures activity in all enabled Regions. To create a multi-Region trail, use the `--is-multi-region-trail` option. By default, the `create-trail` command creates a trail that logs events only in the AWS Region where the trail was created. To ensure that you log global service events and capture all management event activity in your AWS account, you should create trails that log events in all AWS Regions. **Note** When you create a trail, if you specify an Amazon S3 bucket that was not created with CloudTrail, you need to attach the appropriate policy. See [Amazon S3 bucket policy for CloudTrail](create-s3-bucket-policy-for-cloudtrail.md). The following example creates a multi-Region trail with the name *my-trail* and a tag with a key named *Group* with a value of *Marketing* that delivers logs from all enabled Regions in your account to an existing bucket named *amzn-s3-demo-bucket*. ``` aws cloudtrail create-trail --name my-trail --s3-bucket-name amzn-s3-demo-bucket --is-multi-region-trail --tags-list [key=Group,value=Marketing] ``` To confirm that your trail is a multi-Region trail, verify that the `IsMultiRegionTrail` element in the output shows `true`. ``` { "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "IsMultiRegionTrail": true, "IsOrganizationTrail": false, "S3BucketName": "amzn-s3-demo-bucket" } ``` **Note** Use the `start-logging` command to start logging for your trail. ## 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, logging is turned on automatically. The following example starts logging for a trail. ``` aws cloudtrail start-logging --name my-trail ``` This command doesn't return an output, but you can use the `get-trail-status` command to verify that logging has started. ``` aws cloudtrail get-trail-status --name my-trail ``` To confirm that the trail is logging, the `IsLogging` element in the output shows `true`. ``` { "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 single-Region trail The following command creates a single-Region trail. The specified Amazon S3 bucket must already exist and have the appropriate CloudTrail permissions applied. For more information, see [Amazon S3 bucket policy for CloudTrail](create-s3-bucket-policy-for-cloudtrail.md). ``` aws cloudtrail create-trail --name my-trail --s3-bucket-name amzn-s3-demo-bucket ``` The following is example output. ``` { "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "IsMultiRegionTrail": false, "IsOrganizationTrail": false, "S3BucketName": "amzn-s3-demo-bucket" } ``` ## Creating a multi-Region trail that has log file validation enabled To enable log file validation when using `create-trail`, use the `--enable-log-file-validation` option. For information about log file validation, see [Validating CloudTrail log file integrity](cloudtrail-log-file-validation-intro.md). The following example creates a multi-Region trail that delivers logs to the specified bucket. The command uses the `--enable-log-file-validation` option. ``` aws cloudtrail create-trail --name my-trail --s3-bucket-name amzn-s3-demo-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`. ``` { "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", "LogFileValidationEnabled": true, "IsMultiRegionTrail": true, "IsOrganizationTrail": false, "S3BucketName": "amzn-s3-demo-bucket" } ``` # Using the `update-trail` command to update a trail **Important** As of November 22, 2021, AWS CloudTrail changed how trails capture global service events. Now, events created by Amazon CloudFront, AWS Identity and Access Management, and AWS STS are recorded in the Region in which they were created, the US East (N. Virginia) Region, us-east-1. This makes how CloudTrail treats these services consistent with that of other AWS global services. To continue receiving global service events outside of US East (N. Virginia), be sure to convert *single-Region trails* using global service events outside of US East (N. Virginia) into *multi-Region trails*. For more information about capturing global service events, see [Enabling and disabling global service event logging](#cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-examples-gses) later in this section. In contrast, the **Event history** in the CloudTrail console and the **aws cloudtrail lookup-events** command will show these events in the AWS Region where they occurred. You can use the `update-trail` command to change the configuration settings for a trail. You can also use the **add-tags** and **remove-tags** commands to add and remove tags for a trail. You can only update trails from the 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. If you've enabled CloudTrail management events in Amazon Security Lake, you are required to maintain at least one organizational trail that is multi-Region and logs both `read` and `write` management events. You cannot update a qualifying trail in such a way that it fails to meet the Security Lake requirement. For example, by changing the trail to single-Region, or by turning off the logging of `read` or `write` management events. **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](create-s3-bucket-policy-for-cloudtrail.md). **Topics** + [ ## Converting a single-Region trail to a multi-Region trail ](#cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-examples-convert) + [ ## Converting a multi-Region trail to a single-Region trail ](#cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-examples-reduce) + [ ## Enabling and disabling global service event logging ](#cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-examples-gses) + [ ## Enabling log file validation ](#cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-examples-lfi) + [ ## Disabling log file validation ](#cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-examples-lfi-disable) ## Converting a single-Region trail to a multi-Region trail To change an existing single-Region trail to a multi-Region trail, use the `--is-multi-region-trail` option. ``` aws cloudtrail update-trail --name my-trail --is-multi-region-trail ``` To confirm that the trail is now a multi-Region trail, verify that the `IsMultiRegionTrail` element in the output shows `true`. ``` { "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "IsMultiRegionTrail": true, "IsOrganizationTrail": false, "S3BucketName": "amzn-s3-demo-bucket" } ``` ## Converting a multi-Region trail to a single-Region trail To change an existing multi-Region trail so that it applies only to the Region in which it was created, use the `--no-is-multi-region-trail` option. ``` 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`. ``` { "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "IsMultiRegionTrail": false, "IsOrganizationTrail": false, "S3BucketName": "amzn-s3-demo-bucket" } ``` ## Enabling and disabling global service event logging To change a trail so that it does not log global service events, use the `--no-include-global-service-events` option. ``` aws cloudtrail update-trail --name my-trail --no-include-global-service-events ``` To confirm that the trail no longer logs global service events, the `IncludeGlobalServiceEvents` element in the output shows `false`. ``` { "IncludeGlobalServiceEvents": false, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "IsMultiRegionTrail": false, "IsOrganizationTrail": false, "S3BucketName": "amzn-s3-demo-bucket" } ``` To change a trail so that it logs global service events, use the `--include-global-service-events` option. Single-Region trails will no longer receive global service events beginning November 22, 2021, unless the trail already appears in US East (N. Virginia) Region, us-east-1. To continue capturing global service events, update the trail configuration to a multi-Region trail. For example, this command updates a single-Region trail in US East (Ohio), us-east-2, into a multi-Region trail. Replace *myExistingSingleRegionTrailWithGSE* with the appropriate trail name for your configuration. ``` aws cloudtrail --region us-east-2 update-trail --name myExistingSingleRegionTrailWithGSE --is-multi-region-trail ``` Because global service events are only available in US East (N. Virginia) beginning November 22, 2021, you can also create a single-Region trail to subscribe to global service events in the US East (N. Virginia) Region, us-east-1. The following command creates a single-Region trail in us-east-1 to receive CloudFront, IAM, and AWS STS events: ``` aws cloudtrail --region us-east-1 create-trail --include-global-service-events --name myTrail --s3-bucket-name amzn-s3-demo-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. ``` 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`. ``` { "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", "LogFileValidationEnabled": true, "IsMultiRegionTrail": false, "IsOrganizationTrail": false, "S3BucketName": "amzn-s3-demo-bucket" } ``` ## Disabling log file validation To disable log file validation for a trail, use the `--no-enable-log-file-validation` option. ``` 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`. ``` { "IncludeGlobalServiceEvents": true, "Name": "my-trail", "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/my-trail", "LogFileValidationEnabled": false, "IsMultiRegionTrail": false, "IsOrganizationTrail": false, "S3BucketName": "amzn-s3-demo-bucket" } ``` To validate log files with the AWS CLI, see [Validating CloudTrail log file integrity with the AWS CLI](cloudtrail-log-file-validation-cli.md). # 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. **Topics** + [ ## Add one or more tags to a trail ](#cloudtrail-additional-cli-commands-add-tag) + [ ## List tags for one or more trails ](#cloudtrail-additional-cli-commands-list-tags) + [ ## Remove one or more tags from a trail ](#cloudtrail-additional-cli-commands-remove-tag) + [ ## Retrieving trail settings and the status of a trail ](#cloudtrail-additional-cli-commands-retrieve) + [ ## Configuring CloudTrail Insights event selectors ](#configuring-insights-selector) + [ ## Configuring advanced event selectors ](#configuring-adv-event-selector-examples) + [ ## Configuring basic event selectors ](#configuring-event-selector-examples) + [ ## Stopping and starting logging for a trail ](#cloudtrail-start-stop-logging-cli-commands) + [ ## Deleting a trail ](#cloudtrail-delete-trail-cli) ## Add one or more tags to a trail To add one or more tags to an existing trail, run 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, run 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 Run 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": "amzn-s3-demo-bucket1", "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": "amzn-s3-demo-bucket2", "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": "amzn-s3-demo-bucket3", "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 } ] } ``` Run 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": "amzn-s3-demo-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 adding 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 CloudTrail Insights event selectors Enable Insights events on a trail by running the **put-insight-selectors**, and specifying `ApiCallRateInsight`, `ApiErrorRateInsight`, or both as the value of the `InsightType` attribute. To view the Insights selector settings for a trail, run the `get-insight-selectors` command. You must either run this command from the AWS Region where the trail was created (the Home Region), or you must specify that Region by adding the **--region** parameter to the command. **Note** To log Insights events for `ApiCallRateInsight`, the trail must log `write` management events. To log Insights events for `ApiErrorRateInsight`, the trail must log `read` or `write` management events. ### Example trail that logs Insights events The following example uses **put-insight-selectors** to create an Insights event selector for a trail named *TrailName3*. This enables Insights event collection for the *TrailName3* trail. The Insights event selector logs both `ApiErrorRateInsight` and `ApiCallRateInsight` Insights event types. ``` aws cloudtrail put-insight-selectors --trail-name TrailName3 --insight-selectors '[{"InsightType": "ApiCallRateInsight"},{"InsightType": "ApiErrorRateInsight"}]' ``` The example returns the Insights event selector that is configured for the trail. ``` { "InsightSelectors": [ { "InsightType": "ApiErrorRateInsight" }, { "InsightType": "ApiCallRateInsight" } ], "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName3" } ``` ### Example: Turn off collection of Insights events The following example uses **put-insight-selectors** to remove the Insights event selector for a trail named *TrailName3*. Clearing the JSON string of Insights selectors disables Insights event collection for the *TrailName3* trail. ``` aws cloudtrail put-insight-selectors --trail-name TrailName3 --insight-selectors '[]' ``` The example returns the now-empty Insights event selector that is configured for the trail. ``` { "InsightSelectors": [ ], "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName3" } ``` ## Configuring advanced event selectors You can use advanced event selectors to log [management events](logging-management-events-with-cloudtrail.md), [data events](logging-data-events-with-cloudtrail.md) for all resource types, and [network activity events](logging-network-events-with-cloudtrail.md). In contrast, you can use basic event selectors to log management events and data events for the `AWS::DynamoDB::Table`, `AWS::Lambda::Function`, and `AWS::S3::Object` resource types. You can use either basic event selectors, or advanced event selectors, but not both. If you apply advanced event selectors to a trail that is using basic event selectors, the basic event selectors are overwritten. To convert a trail to advanced event selectors, run the **get-event-selectors** command to confirm the current event selectors, and then configure the advanced event selectors to match the coverage of the previous event selectors, then add any additional selectors. You must either run the `get-event-selectors` command from the AWS Region where the trail was created (the Home Region), or you must specify that Region by adding the **--region** parameter. ``` aws cloudtrail get-event-selectors --trail-name TrailName ``` **Note** If the trail is an organization trail, and you are signed in with a member account in the organization in AWS Organizations, you must provide the full ARN of the trail, and not just the name. The following example shows the settings for a trail that is using advanced event selectors to log management events. By default, a trail is configured to log all management events and no data events or network activity events. ``` { "TrailARN": "arn:aws:cloudtrail:us-east-1:123456789012:trail/management-events-trail", "AdvancedEventSelectors": [ { "Name": "Management events selector", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "Management" ] } ] } ] } ``` To create an advanced 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 advanced event selector for a trail, the trail processes and logs the event. You can configure up to 500 conditions on a trail, including all values specified for all advanced event selectors on your trail. For more information, see [Logging data events](logging-data-events-with-cloudtrail.md) and [Logging network activity events](logging-network-events-with-cloudtrail.md). **Topics** + [ ### Example trail with specific advanced event selectors ](#configuring-adv-event-selector-specific) + [ ### Example trail that uses custom advanced event selectors to log Amazon S3 on AWS Outposts data events ](#configuring-adv-event-selector-outposts) + [ ### Example trail that uses advanced event selectors to exclude AWS Key Management Service events ](#configuring-adv-event-selector-exclude) + [ ### Example trail that uses advanced event selectors to exclude Amazon RDS Data API management events ](#configuring-adv-event-selector-exclude-rds) ### Example trail with specific advanced event selectors The following example creates custom advanced event selectors for a trail named *TrailName* to include read and write management events (by omitting the `readOnly` selector), `PutObject` and `DeleteObject` data events for all Amazon S3 bucket/prefix combinations except for a bucket named `amzn-s3-demo-bucket`, data events for an AWS Lambda function named `MyLambdaFunction`, and network activity events for AWS KMS access denied events over a VPC endpoint. Because these are custom advanced event selectors, each set of selectors has a descriptive name. Note that a trailing slash is part of the ARN value for S3 buckets. ``` aws cloudtrail put-event-selectors --trail-name TrailName --advanced-event-selectors '[ { "Name": "Log readOnly and writeOnly management events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Management"] } ] }, { "Name": "Log PutObject and DeleteObject events for all but one bucket", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Data"] }, { "Field": "resources.type", "Equals": ["AWS::S3::Object"] }, { "Field": "eventName", "Equals": ["PutObject","DeleteObject"] }, { "Field": "resources.ARN", "NotStartsWith": ["arn:aws:s3:::amzn-s3-demo-bucket/"] } ] }, { "Name": "Log data plane actions on MyLambdaFunction", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Data"] }, { "Field": "resources.type", "Equals": ["AWS::Lambda::Function"] }, { "Field": "resources.ARN", "Equals": ["arn:aws:lambda:us-east-2:111122223333:function/MyLambdaFunction"] } ] }, { "Name": "Audit AccessDenied AWS KMS events over a VPC endpoint", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["NetworkActivity"]}, { "Field": "eventSource", "Equals": ["kms.amazonaws.com"]}, { "Field": "errorCode", "Equals": ["VpceAccessDenied"]} ] } ]' ``` The example returns the advanced event selectors that are configured for the trail. ``` { "AdvancedEventSelectors": [ { "Name": "Log readOnly and writeOnly management events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "Management" ] } ] }, { "Name": "Log PutObject and DeleteObject events for all but one bucket", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "Data" ] }, { "Field": "resources.type", "Equals": [ "AWS::S3::Object" ] }, { "Field": "resources.ARN", "NotStartsWith": [ "arn:aws:s3:::amzn-s3-demo-bucket/" ] }, ] }, { "Name": "Log data plane actions on MyLambdaFunction", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "Data" ] }, { "Field": "resources.type", "Equals": [ "AWS::Lambda::Function" ] }, { "Field": "eventName", "Equals": [ "Invoke" ] }, { "Field": "resources.ARN", "Equals": [ "arn:aws:lambda:us-east-2:123456789012:function/MyLambdaFunction" ] } ] }, { "Name": "Audit AccessDenied AWS KMS events over a VPC endpoint", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["NetworkActivity"] }, { "Field": "eventSource", "Equals": ["kms.amazonaws.com"] }, { "Field": "errorCode", "Equals": ["VpceAccessDenied"] } ] } ], "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName" } ``` ### Example trail that uses custom advanced event selectors to log Amazon S3 on AWS Outposts data events The following example shows how to configure your trail to include all data events for all Amazon S3 on AWS Outposts objects in your outpost. In this release, the supported value for S3 on AWS Outposts events for the `resources.type` field is `AWS::S3Outposts::Object`. ``` aws cloudtrail put-event-selectors --trail-name TrailName --region region \ --advanced-event-selectors \ '[ { "Name": "OutpostsEventSelector", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Data"] }, { "Field": "resources.type", "Equals": ["AWS::S3Outposts::Object"] } ] } ]' ``` The command returns the following example output. ``` { "AdvancedEventSelectors": [ { "Name": "OutpostsEventSelector", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "Data" ] }, { "Field": "resources.type", "Equals": [ "AWS::S3Outposts::Object" ] } ] } ], "TrailARN": "arn:aws:cloudtrail:region:123456789012:trail/TrailName" } ``` ### Example trail that uses advanced event selectors to exclude AWS Key Management Service events The following example creates an advanced event selector for a trail named *TrailName* to include read-only and write-only management events (by omitting the `readOnly` selector), but to exclude AWS Key Management Service (AWS KMS) events. Because AWS KMS events are treated as management events, and there can be a high volume of them, they can have a substantial impact on your CloudTrail bill if you have more than one trail that captures management events. If you choose not to log management events, AWS KMS events are not logged, and you cannot change AWS KMS event logging settings. To start logging AWS KMS events to a trail again, remove the `eventSource` selector, and run the command again. ``` aws cloudtrail put-event-selectors --trail-name TrailName \ --advanced-event-selectors ' [ { "Name": "Log all management events except KMS events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Management"] }, { "Field": "eventSource", "NotEquals": ["kms.amazonaws.com"] } ] } ]' ``` The example returns the advanced event selectors that are configured for the trail. ``` { "AdvancedEventSelectors": [ { "Name": "Log all management events except KMS events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "Management" ] }, { "Field": "eventSource", "NotEquals": [ "kms.amazonaws.com" ] } ] } ], "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName" } ``` To start logging excluded events to a trail again, remove the `eventSource` selector, as shown in the following command. ``` aws cloudtrail put-event-selectors --trail-name TrailName \ --advanced-event-selectors ' [ { "Name": "Log all management events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Management"] } ] } ]' ``` ### Example trail that uses advanced event selectors to exclude Amazon RDS Data API management events The following example creates an advanced event selector for a trail named *TrailName* to include read-only and write-only management events (by omitting the `readOnly` selector), but to exclude Amazon RDS Data API management events. To exclude Amazon RDS Data API management events, specify the Amazon RDS Data API event source in the string value for the `eventSource` field: `rdsdata.amazonaws.com`. If you choose not to log management events, Amazon RDS Data API management events are not logged, and you cannot change Amazon RDS Data API event logging settings. To start logging Amazon RDS Data API management events to a trail again, remove the `eventSource` selector, and run the command again. ``` aws cloudtrail put-event-selectors --trail-name TrailName \ --advanced-event-selectors ' [ { "Name": "Log all management events except Amazon RDS Data API management events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Management"] }, { "Field": "eventSource", "NotEquals": ["rdsdata.amazonaws.com"] } ] } ]' ``` The example returns the advanced event selectors that are configured for the trail. ``` { "AdvancedEventSelectors": [ { "Name": "Log all management events except Amazon RDS Data API management events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "Management" ] }, { "Field": "eventSource", "NotEquals": [ "rdsdata.amazonaws.com" ] } ] } ], "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName" } ``` To start logging excluded events to a trail again, remove the `eventSource` selector, as shown in the following command. ``` aws cloudtrail put-event-selectors --trail-name TrailName \ --advanced-event-selectors ' [ { "Name": "Log all management events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Management"] } ] } ]' ``` ## Configuring basic event selectors You can only use basic event selectors to log management events and data events for the `AWS::DynamoDB::Table`, `AWS::Lambda::Function`, and `AWS::S3::Object` resource types. You can log management events, all data resource types, and network activity events by using advanced event selectors. You can use either basic event selectors, or advanced event selectors, but not both. If you apply basic event selectors to a trail that is using advanced event selectors, the advanced event selectors are overwritten. 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 shows the settings for a trail that is using basic event selectors to log management events. ``` { "EventSelectors": [ { "ExcludeManagementEventSources": [], "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. If you want to log Insights events on the trail, be sure the event selector enables logging of the Insights types you want configured your trail. For more information about logging Insights events, see [Working with CloudTrail Insights](logging-insights-events-with-cloudtrail.md). 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 events](logging-data-events-with-cloudtrail.md). **Topics** + [ ### Example trail with specific event selectors ](#configuring-event-selector-example1) + [ ### Example trail that logs all management and data events ](#configuring-event-selector-example2) + [ ### Example trail that does not log AWS Key Management Service events ](#configuring-event-selector-example-kms) + [ ### Example trail that logs relevant low-volume AWS Key Management Service events ](#configuring-event-selector-log-kms) + [ ### Example trail that does not log Amazon RDS data API events ](#configuring-event-selector-example-rds) ### Example 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:::amzn-s3-demo-bucket/prefix","arn:aws:s3:::amzn-s3-demo-bucket2/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": [ { "ExcludeManagementEventSources": [], "IncludeManagementEvents": true, "DataResources": [ { "Values": [ "arn:aws:s3:::amzn-s3-demo-bucket/prefix", "arn:aws:s3:::amzn-s3-demo-bucket2/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 trail that logs all management and data events The following example creates an event selector for a trail named *TrailName2* that includes all management events, including read-only and write-only management events, and data events for all Amazon S3 buckets, AWS Lambda functions, and Amazon DynamoDB tables in the AWS account. Because this example uses basic event selectors, it cannot configure logging for S3 events on AWS Outposts, Amazon Managed Blockchain JSON-RPC calls on Ethereum nodes, or other advanced event selector resource types. You also can't log network activity events using basic event selectors. You must use advanced event selectors to log network activity events and data events for all other resource types. For more information, see [Configuring advanced event selectors](#configuring-adv-event-selector-examples). **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"]},{"Type": "AWS::DynamoDB::Table","Values": ["arn:aws:dynamodb"]}]}]' ``` The example returns the event selectors configured for the trail. ``` { "EventSelectors": [ { "ExcludeManagementEventSources": [], "IncludeManagementEvents": true, "DataResources": [ { "Values": [ "arn:aws:s3:::" ], "Type": "AWS::S3::Object" }, { "Values": [ "arn:aws:lambda" ], "Type": "AWS::Lambda::Function" }, { "Values": [ "arn:aws:dynamodb" ], "Type": "AWS::DynamoDB::Table" } ], "ReadWriteType": "All" } ], "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName2" } ``` ### Example trail that does not log AWS Key Management Service events The following example creates an event selector for a trail named *TrailName* to include read-only and write-only management events, but to exclude AWS Key Management Service (AWS KMS) events. Because AWS KMS events are treated as management events, and there can be a high volume of them, they can have a substantial impact on your CloudTrail bill if you have more than one trail that captures management events. The user in this example has chosen to exclude AWS KMS events from every trail except for one. To exclude an event source, add `ExcludeManagementEventSources` to your event selectors, and specify an event source in the string value. If you choose not to log management events, AWS KMS events are not logged, and you cannot change AWS KMS event logging settings. To start logging AWS KMS events to a trail again, pass an empty array as the value of `ExcludeManagementEventSources`. ``` aws cloudtrail put-event-selectors --trail-name TrailName --event-selectors '[{"ReadWriteType": "All","ExcludeManagementEventSources": ["kms.amazonaws.com"],"IncludeManagementEvents": true]}]' ``` The example returns the event selector that is configured for the trail. ``` { "EventSelectors": [ { "ExcludeManagementEventSources": [ "kms.amazonaws.com" ], "IncludeManagementEvents": true, "DataResources": [], "ReadWriteType": "All" } ], "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName" } ``` To start logging AWS KMS events to a trail again, pass an empty array as the value of `ExcludeManagementEventSources`, as shown in the following command. ``` aws cloudtrail put-event-selectors --trail-name TrailName --event-selectors '[{"ReadWriteType": "All","ExcludeManagementEventSources": [],"IncludeManagementEvents": true]}]' ``` ### Example trail that logs relevant low-volume AWS Key Management Service events The following example creates an event selector for a trail named *TrailName* to include write-only management events and AWS KMS events. Because AWS KMS events are treated as management events, and there can be a high volume of them, they can have a substantial impact on your CloudTrail bill if you have more than one trail that captures management events. The user in this example has chosen to include AWS KMS **Write** events, which will include `Disable`, `Delete` and `ScheduleKey`, but no longer include high-volume actions such as `Encrypt`, `Decrypt`, and `GenerateDataKey` (these are now treated as **Read** events). ``` aws cloudtrail put-event-selectors --trail-name TrailName --event-selectors '[{"ReadWriteType": "WriteOnly","ExcludeManagementEventSources": [],"IncludeManagementEvents": true]}]' ``` The example returns the event selector that is configured for the trail. This logs write-only management events, including AWS KMS events. ``` { "EventSelectors": [ { "ExcludeManagementEventSources": [], "IncludeManagementEvents": true, "DataResources": [], "ReadWriteType": "WriteOnly" } ], "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName" } ``` ### Example trail that does not log Amazon RDS data API events The following example creates an event selector for a trail named *TrailName* to include read-only and write-only management events, but to exclude Amazon RDS Data API events. Because Amazon RDS Data API events are treated as management events, and there can be a high volume of them, they can have a substantial impact on your CloudTrail bill if you have more than one trail that captures management events. The user in this example has chosen to exclude Amazon RDS Data API events from every trail except for one. To exclude an event source, add `ExcludeManagementEventSources` to your event selectors, and specify the Amazon RDS Data API event source in the string value: `rdsdata.amazonaws.com`. If you choose not to log management events, Amazon RDS Data API events are not logged, and you cannot change event logging settings. To start logging Amazon RDS Data API management events to a trail again, pass an empty array as the value of `ExcludeManagementEventSources`. ``` aws cloudtrail put-event-selectors --trail-name TrailName --event-selectors '[{"ReadWriteType": "All","ExcludeManagementEventSources": ["rdsdata.amazonaws.com"],"IncludeManagementEvents": true]}]' ``` The example returns the event selector that is configured for the trail. ``` { "EventSelectors": [ { "ExcludeManagementEventSources": [ "rdsdata.amazonaws.com" ], "IncludeManagementEvents": true, "DataResources": [], "ReadWriteType": "All" } ], "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName" } ``` To start logging Amazon RDS Data API management events to a trail again, pass an empty array as the value of `ExcludeManagementEventSources`, as shown in the following command. ``` aws cloudtrail put-event-selectors --trail-name TrailName --event-selectors '[{"ReadWriteType": "All","ExcludeManagementEventSources": [],"IncludeManagementEvents": true]}]' ``` ## 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. If you stop logging or delete a trail, CloudTrail Insights is disabled on that trail. **Event delivery after logging is stopped** After you stop logging for a trail, the trail can still receive events that occurred before logging was stopped. Events can be delayed for a number of reasons, including high network traffic, connectivity issues, a service outage, or updates to existing events. CloudTrail uses the most recent time that logging was stopped to determine whether to deliver delayed events, rather than the logging state of the trail at the time the event occurred. As a result, delayed events that occurred before logging was last stopped can still be delivered to the trail. For more information about delayed event delivery, see the `addendum` field in [CloudTrail record contents for management, data, and network activity events](cloudtrail-event-reference-record-contents.md). Additionally, event selectors and advanced event selectors are not evaluated for delayed events delivered to a trail after logging is stopped. This means that a trail can receive any type of event that occurred before logging was stopped, regardless of the trail's event selector configuration. ## Deleting a trail If you've enabled CloudTrail management events in Amazon Security Lake, you are required to maintain at least one organizational trail that is multi-Region and logs both `read` and `write` management events. You cannot delete a trail if it is the only trail you have that meets this requirement, unless you turn off CloudTrail management events in Security Lake. You can delete a trail with the following command. You can delete a trail only in the Region it was created (the Home Region). **Important** While deleting a CloudTrail trail is an irreversible action, CloudTrail does not delete log files in the Amazon S3 bucket for that trail, the Amazon S3 bucket itself, or the CloudWatch log group to which the trail delivers events. Deleting a multi-Region trail will stop logging of events in all AWS Regions enabled in your AWS account. Deleting a single-Region trail will stop logging of events in that Region only. It will not stop logging of events in other Regions even if the trails in those other Regions have identical names to the deleted trail. For information about account closure and deletion of CloudTrail trails, see [AWS account closure and trails](cloudtrail-account-closure.md). ``` 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. # Creating multiple trails You can use CloudTrail log files to troubleshoot operational or security issues in your AWS account. You can create trails for different users, who can create and manage their own trails. You can configure trails to deliver log files to separate S3 buckets or shared S3 buckets. **Note** The first copy of management events in each AWS Region for an account is free. If you create more trails that deliver the same management events to other destinations, those subsequent deliveries incur CloudTrail costs. For more information about CloudTrail costs, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/) and [Managing CloudTrail trail costs](cloudtrail-trail-manage-costs.md). For example, you might have the following users: + A security administrator creates a trail in the Europe (Ireland) Region and configures KMS log file encryption. The trail delivers the log files to an S3 bucket in the Europe (Ireland) Region. + An IT auditor creates a trail in the Europe (Ireland) Region and configures log file integrity validation to ensure the log files have not changed since CloudTrail delivered them. The trail is configured to deliver log files to an S3 bucket in the Europe (Frankfurt) Region + A developer creates a trail in the Europe (Frankfurt) Region and configures CloudWatch alarms to receive notifications for specific API activity. The trail shares the same S3 bucket as the trail configured for log file integrity. + Another developer creates a trail in the Europe (Frankfurt) Region and configures SNS. The log files are delivered to a separate S3 bucket in the Europe (Frankfurt) Region. The following image illustrates this example. ![\[An example of log file delivery for multiple trails\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/images/eu-shared-01.png) **Note** You can create up to five trails per AWS Region. A multi-Region trail counts as one trail per Region. You can use resource-level permissions to manage a user's ability to perform specific operations on CloudTrail. For example, you might grant one user permission to view trail activity, but restrict the user from starting or stopping logging for a trail. You might grant another user full permission to create and delete trails. This gives you granular control over your trails and user access. For more information about resource-level permissions, see [Examples: Creating and applying policies for actions on specific trails](security_iam_id-based-policy-examples.md#grant-custom-permissions-for-cloudtrail-users-resource-level). For more information about multiple trails, see the [CloudTrail FAQs](https://aws.amazon.com/cloudtrail/faqs/). # Creating a trail for an organization If you have created an organization in AWS Organizations, you can create a trail that logs all events for all AWS accounts in that organization. This is sometimes called an *organization trail*. The management account for the organization can assign a [delegated administrator](cloudtrail-delegated-administrator.md) to create new organization trails or manage existing organization trails. For more information on adding a delegated administrator, see [Add a CloudTrail delegated administrator](cloudtrail-add-delegated-administrator.md). The management account for the organization can edit an existing trail in their account, and apply it to an organization, making it an organization trail. Organization trails log events for the management account and all member accounts in the organization. For more information about AWS Organizations, see [Organizations Terminology and Concepts](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_getting-started_concepts.html). **Note** You must sign in with the management account or a delegated administrator account associated with an organization to create an organization trail. You must also have [sufficient permissions](creating-an-organizational-trail-prepare.md#org_trail_permissions) for the user or role in the management or delegated administrator account to create the trail. If you don't have sufficient permissions, you won't have the option to apply the trail to an organization. All organization trails created using the console are multi-Region organization trails that log events from the [enabled](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-enable-organization) AWS Regions in each member account in the organization. To log events in all AWS partitions in your organization, create a multi-Region organization trail in each partition. You can create either a single-Region or multi-Region organization trail by using the AWS CLI. If you create a single-Region trail, you log activity only in the trail's AWS Region (also referred to as the *Home* Region). Although most AWS Regions are enabled by default for your AWS account, you must manually enable certain Regions (also referred to as *opt-in Regions*). For information about which Regions are enabled by default, see [Considerations before enabling and disabling Regions](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-considerations) in the *AWS Account Management Reference Guide*. For the list of Regions CloudTrail supports, see [CloudTrail supported Regions](cloudtrail-supported-regions.md). When you create an organization trail, a copy of the trail with the name that you give it is created in the member accounts that belongs to your organization. + If the organization trail is for a **single-Region** and the trail's home Region **is not an opt-in Region**, a copy of the trail is created in the organization trail's home Region in each member account. + If the organization trail is for a **single-Region** and the trail's home Region **is an opt-in Region**, a copy of the trail is created in the organization trail's home Region in the member accounts that have enabled that Region. + If the organization trail is **multi-Region** and the trail's home Region **is** **not an opt-in Region**, a copy of the trail is created in each enabled AWS Region in each member account. When a member account enables an opt-in Region, a copy of the multi-Region trail is created in the newly opted in Region for the member account after activation of that Region is complete. + If the organization trail is **multi-Region** and the home Region **is** **an opt-in Region**, member accounts will not send activity to the organization trail unless they opt into the AWS Region where the multi-Region trail was created. For example, if you create a multi-Region trail and choose the Europe (Spain) Region as the home Region for the trail, only member accounts that enabled the Europe (Spain) Region for their account will send their account activity to the organization trail. **Note** CloudTrail creates organization trails in member accounts even if a resource validation fails. Examples of validation failures include: an incorrect Amazon S3 bucket policy an incorrect Amazon SNS topic policy inability to deliver to a CloudWatch Logs log group insufficient permission to encrypt using a KMS key A member account with CloudTrail permissions can see any validation failures for an organization trail by viewing the trail's details page on the CloudTrail console, or by running the AWS CLI [https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html) command. Users with CloudTrail permissions in member accounts can see organization trails when they log into the CloudTrail console from their AWS accounts, or when they run AWS CLI commands such as `describe-trails`. However, users in member accounts do not have sufficient permissions to delete organization trails, turn logging on or off, change what types of events are logged, or otherwise change an organization trail in any way. When you create an organization trail in the console, CloudTrail creates a [service-linked role](using-service-linked-roles.md) to perform logging tasks in your organization's member accounts. This role is named **AWSServiceRoleForCloudTrail**, and is required for CloudTrail to log events for an organization. If an AWS account is added to an organization, the organization trail and service-linked role are added to that AWS account, and logging starts for that account automatically in the organization trail. If an AWS account is removed from an organization, the organization trail and service-linked role are deleted from the AWS account that is no longer part of the organization. However, log files for the removed account that were created before the account's removal remain in the Amazon S3 bucket where log files are stored for the trail. If the management account for an AWS Organizations organization creates an organization trail, but then is subsequently removed as the organization's management account, any organization trail created using their account becomes a non-organization trail. In the following example, the organization's management account 111111111111 creates a trail named *MyOrganizationTrail* for the organization *o-exampleorgid*. The trail logs activity for all accounts in the organization in the same Amazon S3 bucket. All accounts in the organization can see *MyOrganizationTrail* in their list of trails, but member accounts cannot remove or modify the organization trail. Only the management account or delegated administrator account can change or delete the trail for the organization. Only the management account can remove a member account from an organization. Similarly, by default, only the management account has access to the Amazon S3 bucket for the trail, and the logs contained within it. The high-level bucket structure for log files contains a folder named with the organization ID, and subfolders named with the account IDs for each account in the organization. Events for each member account are logged in the folder that corresponds to the member account ID. If member account 444444444444 is removed from the organization, *MyOrganizationTrail* and the service-linked role no longer appear in AWS account 444444444444, and no further events are logged for that account by the organization trail. However, the 444444444444 folder remains in the Amazon S3 bucket, with all logs created before the removal of the account from the organization. ![\[A conceptual overview of a sample organization in Organizations.\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/images/organization-trail.png) In this example, the ARN of the trail created in the management account is `aws:cloudtrail:us-east-2:111111111111:trail/MyOrganizationTrail`. This ARN is the ARN for the trail in all member accounts as well. Organization trails are similar to regular trails in many ways. You can create multiple trails for your organization, and choose whether to create a multi-Region or single-Region organization trail, and what kinds of events you want logged in your organization trail, just as in any other trail. However, there are some differences. For example, when you create a trail in the console and choose whether to log data events for Amazon S3 buckets or AWS Lambda functions, the only resources listed in the CloudTrail console are those for the management account, but you can add the ARNs for resources in member accounts. Data events for specified member account resources are logged without having to manually configure cross-account access to those resources. For more information about logging management events, Insights events, and data events, see [Logging management events](logging-management-events-with-cloudtrail.md), [Logging data events](logging-data-events-with-cloudtrail.md), and [Working with CloudTrail Insights](logging-insights-events-with-cloudtrail.md). **Note** In the console, you create a multi-Region trail. It's a recommended best practice to log activity in all enabled Regions in your AWS account, because it helps you keep your AWS environment more secure. To create a single-Region trail, [use the AWS CLI](cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-create-trail.md#cloudtrail-create-and-update-a-trail-by-using-the-aws-cli-examples-single). When you view events in **Event history** for an organization in AWS Organizations, you can view the events only for the AWS account with which you are signed in. For example, if you are signed in with the organization management account, **Event history** shows the last 90 days of management events for the management account. Organization member account events are not shown in **Event history** for the management account. To view member account events in **Event history**, sign in with the member account. You can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs for an organization trail the same way you would for any other trail. For example, you can analyze the data in an organization trail using Amazon Athena. For more information, see [AWS service integrations with CloudTrail logs](cloudtrail-aws-service-specific-topics.md#cloudtrail-aws-service-specific-topics-integrations). **Topics** + [ # Moving from member account trails to organization trails ](creating-an-organizational-trail-best-practice.md) + [ # Prepare for creating a trail for your organization ](creating-an-organizational-trail-prepare.md) + [ # Creating a trail for your organization in the console ](creating-an-organizational-trail-in-the-console.md) + [ # Creating a trail for an organization with the AWS CLI ](cloudtrail-create-and-update-an-organizational-trail-by-using-the-aws-cli.md) + [ # Troubleshooting issues with an organization trail ](cloudtrail-troubleshooting.md) # Moving from member account trails to organization trails If you already have CloudTrail trails configured for individual member accounts, but want to move to an organization trail to log events in all accounts, you do not want to lose events by deleting individual member account trails before you create an organization trail. But when you have two trails, you incur higher costs because of the additional copy of events delivered to the organization trail. To help manage costs, but avoid losing events before log delivery starts on the organization trail, consider keeping both your individual member account trails and your organization trail for up to one day. This ensures that the organization trail logs all events, but you incur duplicate event costs only for one day. After the first day, you can stop logging on (or delete) any individual member account trails. # Prepare for creating a trail for your organization Before you create a trail for your organization, be sure that your organization management account or delegated administrator account is set up correctly for trail creation. + Your organization must have all features enabled before you can create a trail for it. For more information, see [Enabling All Features in Your Organization](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_support-all-features.html). + The management account must have the **AWSServiceRoleForOrganizations** role. This role is created automatically by Organizations when you create your organization, and is required for CloudTrail to log events for an organization. For more information, see [Organizations and service-linked roles](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_integrate_services.html#orgs_integrate_services-using_slrs). + The user or role that creates the organization trail in the management or delegated administrator account must have sufficient permissions to create an organization trail. You must at least apply either the **AWSCloudTrail\$1FullAccess** policy, or an equivalent policy, to that role or user. You must also have sufficient permissions in IAM and Organizations to create the service-linked role and enable trusted access. If you choose to create a new S3 bucket for an organization trail using the CloudTrail console,
 your policy also needs to include the `s3:PutEncryptionConfiguration`
 action because by default server-side encryption is enabled for the bucket. The following example policy shows the minimum required permissions. **Note** You shouldn't share the **AWSCloudTrail\$1FullAccess** policy broadly across your AWS account. Instead, you should restrict it to AWS account administrators due to the highly sensitive nature of the information collected by CloudTrail. Users with this role have the ability to turn off or reconfigure the most sensitive and important auditing functions in their AWS accounts. For this reason, you must closely control and monitor access to this policy. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iam:GetRole", "organizations:EnableAWSServiceAccess", "organizations:ListAccounts", "iam:CreateServiceLinkedRole", "organizations:DisableAWSServiceAccess", "organizations:DescribeOrganization", "organizations:ListAWSServiceAccessForOrganization", "s3:PutEncryptionConfiguration" ], "Resource": "*" } ] } ``` ------ + To use the AWS CLI or the CloudTrail APIs to create an organization trail, you must enable trusted access for CloudTrail in Organizations, and you must manually create an Amazon S3 bucket with a policy that allows logging for an organization trail. For more information, see [Creating a trail for an organization with the AWS CLI](cloudtrail-create-and-update-an-organizational-trail-by-using-the-aws-cli.md). + To use an existing IAM role to add monitoring of an organization trail to Amazon CloudWatch Logs, you must manually modify the IAM role to allow delivery of CloudWatch Logs for member accounts to the CloudWatch Logs group for the management account, as shown in the following example. **Note** You must use an IAM role and CloudWatch Logs log group that exists in your own account. You cannot use an IAM role or CloudWatch Logs log group owned by a different account. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AWSCloudTrailCreateLogStream20141101", "Effect": "Allow", "Action": [ "logs:CreateLogStream" ], "Resource": [ "arn:aws:logs:us-east-2:111111111111:log-group:CloudTrail/DefaultLogGroupTest:log-stream:111111111111_CloudTrail_us-east-2*", "arn:aws:logs:us-east-2:111111111111:log-group:CloudTrail/DefaultLogGroupTest:log-stream:o-exampleorgid_*" ] }, { "Sid": "AWSCloudTrailPutLogEvents20141101", "Effect": "Allow", "Action": [ "logs:PutLogEvents" ], "Resource": [ "arn:aws:logs:us-east-2:111111111111:log-group:CloudTrail/DefaultLogGroupTest:log-stream:111111111111_CloudTrail_us-east-2*", "arn:aws:logs:us-east-2:111111111111:log-group:CloudTrail/DefaultLogGroupTest:log-stream:o-exampleorgid_*" ] } ] } ``` ------ You can learn more about CloudTrail and Amazon CloudWatch Logs in [Monitoring CloudTrail Log Files with Amazon CloudWatch Logs](monitor-cloudtrail-log-files-with-cloudwatch-logs.md). In addition, consider the limits on CloudWatch Logs and the pricing considerations for the service before deciding to enable the experience for an organization trail. For more information, see [CloudWatch Logs Limits](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/cloudwatch_limits_cwl.html) and [Amazon CloudWatch Pricing](https://aws.amazon.com/cloudwatch/pricing/). + To log data events in your organization trail for specific resources in member accounts, have ready a list of Amazon Resource Names (ARNs) for each of those resources. Member account resources are not displayed in the CloudTrail console when you create a trail; you can browse for resources in the management account on which data event collection is supported, such as S3 buckets. Similarly, if you want to add specific member resources when creating or updating an organization trail at the command line, you need the ARNs for those resources. **Note** Additional charges apply for logging data events. For CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). You should also consider reviewing how many trails already exist in the management account and in the member accounts before creating an organization trail. CloudTrail limits the number of trails that can be created in each Region. You cannot exceed this limit in the Region where you create the organization trail in the management account. However, the trail will be created in the member accounts even if member accounts have reached the limit of trails in a Region. While the first trail of management events in any Region is free, charges apply to additional trails. To reduce the potential cost of an organization trail, consider deleting any unneeded trails in the management and member accounts. For more information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). ## Security best practices in organization trails As a security best practice, we recommend adding the `aws:SourceArn` condition key to resource policies (such as those for S3 buckets, KMS keys, or SNS topics) that you use with an organization trail. The value of `aws:SourceArn` is the organization trail ARN (or ARNs, if you are using the same resource for more than one trail, such as the same S3 bucket to store logs for more than one trail). This ensures that the resource, such as an S3 bucket, accepts only data that is associated with the specific trail. The trail ARN must use the account ID of the management account. The following policy snippet shows an example where more than one trail is using the resource. ``` "Condition": { "StringEquals": { "aws:SourceArn": ["Trail_ARN_1",..., "Trail_ARN_n"] } } ``` For information about how to add condition keys to resource policies, see the following: + [Amazon S3 bucket policy for CloudTrail](create-s3-bucket-policy-for-cloudtrail.md) + [Configure AWS KMS key policies for CloudTrail](create-kms-key-policy-for-cloudtrail.md) + [Amazon SNS topic policy for CloudTrail](cloudtrail-permissions-for-sns-notifications.md) # Creating a trail for your organization in the console To create an organization trail from the CloudTrail console, you must sign in to the console as a user or role in the management or delegated administrator account that has [sufficient permissions](creating-an-organizational-trail-prepare.md#org_trail_permissions). If you don't sign in with the management or delegated administrator account, you won't see the option to apply a trail to an organization when you create or edit a trail from the CloudTrail console. **To create an organization trail with the AWS Management Console** 1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/). You must be signed in using an IAM identity in the management or delegated administrator account with [sufficient permissions](creating-an-organizational-trail-prepare.md#org_trail_permissions) to create an organization trail. 1. Choose **Trails**, and then choose **Create trail**. 1. On the **Create Trail** page, for **Trail name**, type a name for your trail. For more information, see [Naming requirements for CloudTrail resources, S3 buckets, and KMS keys](cloudtrail-trail-naming-requirements.md). 1. Select **Enable for all accounts in my organization**. You only see this option if you sign in to the console with a user or role in the management or delegated administrator account. To successfully create an organization trail, be sure that the user or role has [sufficient permissions](creating-an-organizational-trail-prepare.md#org_trail_permissions). 1. For **Storage location**, choose **Create new S3 bucket** to create a bucket. When you create a bucket, CloudTrail creates and applies the required bucket policies. **Note** If you chose **Use existing S3 bucket**, specify a bucket in **Trail log bucket name**, or choose **Browse** to choose a bucket. You can choose a bucket belonging to any account, however, the bucket policy must grant CloudTrail permission to write to it. For information about manually editing the bucket policy, see [Amazon S3 bucket policy for CloudTrail](create-s3-bucket-policy-for-cloudtrail.md). To make it easier to find your logs, create a new folder (also known as a *prefix*) in an existing bucket to store your CloudTrail logs. Enter the prefix in **Prefix**. 1. For **Log file SSE-KMS encryption**, choose **Enabled** if you want to encrypt your log files and digest files using SSE-KMS encryption instead of SSE-S3 encryption. The default is **Enabled**. If you don't enable SSE-KMS encryption, your log files and digest files are encrypted using SSE-S3 encryption. For more information about SSE-KMS encryption, see [Using server-side encryption with AWS Key Management Service (SSE-KMS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html). For more information about SSE-S3 encryption, see [Using Server-Side Encryption with Amazon S3-Managed Encryption Keys (SSE-S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html). If you enable SSE-KMS encryption, choose a **New** or **Existing** AWS KMS key. In **AWS KMS Alias**, specify an alias, in the format `alias/`*MyAliasName*. For more information, see [Updating a resource to use your KMS key with the console](create-kms-key-policy-for-cloudtrail-update-trail.md). **Note** You can also type the ARN of a key from another account. For more information, see [Updating a resource to use your KMS key with the console](create-kms-key-policy-for-cloudtrail-update-trail.md). The key policy must allow CloudTrail to use the key to encrypt your log files and digest files, and allow the users you specify to read log files or digest files in unencrypted form. For information about manually editing the key policy, see [Configure AWS KMS key policies for CloudTrail](create-kms-key-policy-for-cloudtrail.md). 1. In **Additional settings**, configure the following. 1. For **Log file validation**, choose **Enabled** to have log digests delivered to your S3 bucket. You can use the digest files to verify that your log files did not change after CloudTrail delivered them. For more information, see [Validating CloudTrail log file integrity](cloudtrail-log-file-validation-intro.md). 1. For **SNS notification delivery**, choose **Enabled** to be notified each time a log is delivered to your bucket. CloudTrail stores multiple events in a log file. SNS notifications are sent for every log file, not for every event. For more information, see [Configuring Amazon SNS notifications for CloudTrail](configure-sns-notifications-for-cloudtrail.md). If you enable SNS notifications, for **Create a new SNS topic**, choose **New** to create a topic, or choose **Existing** to use an existing topic. If you are creating multi-Region trail, SNS notifications for log file deliveries from all Regions are sent to the single SNS topic that you create. If you choose **New**, CloudTrail specifies a name for the new topic for you, or you can type a name. If you choose **Existing**, choose an SNS topic from the drop-down list. You can also enter the ARN of a topic from another Region or from an account with appropriate permissions. For more information, see [Amazon SNS topic policy for CloudTrail](cloudtrail-permissions-for-sns-notifications.md). If you create a topic, you must subscribe to the topic to be notified of log file delivery. You can subscribe from the Amazon SNS console. Due to the frequency of notifications, we recommend that you configure the subscription to use an Amazon SQS queue to handle notifications programmatically. For more information, see [Getting started with Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html) in the *Amazon Simple Notification Service Developer Guide*. 1. Optionally, configure CloudTrail to send log files to CloudWatch Logs by choosing **Enabled** in **CloudWatch Logs**. For more information, see [Sending events to CloudWatch Logs](send-cloudtrail-events-to-cloudwatch-logs.md). **Note** Only the management account can configure a CloudWatch Logs log group for an organization trail using the console. The delegated administrator can configure a CloudWatch Logs log group using the AWS CLI or CloudTrail `CreateTrail` or `UpdateTrail` API operations. 1. If you enable integration with CloudWatch Logs, choose **New** to create a new log group, or **Existing** to use an existing one. If you choose **New**, CloudTrail specifies a name for the new log group for you, or you can type a name. 1. If you choose **Existing**, choose a log group from the drop-down list. 1. Choose **New** to create a new IAM role for permissions to send logs to CloudWatch Logs. Choose **Existing** to choose an existing IAM role from the drop-down list. The policy statement for the new or existing role is displayed when you expand **Policy document**. For more information about this role, see [Role policy document for CloudTrail to use CloudWatch Logs for monitoring](cloudtrail-required-policy-for-cloudwatch-logs.md). **Note** When you configure a trail, you can choose an S3 bucket and Amazon SNS topic that belong to another account. However, if you want CloudTrail to deliver events to a CloudWatch Logs log group, you must choose a log group that exists in your current account. 1. For **Tags**, you can add up to 50 tag key pairs to help you identify, sort, and control access to your trail. Tags can help you identify both your CloudTrail trails and the Amazon S3 buckets that contain CloudTrail log files. You can then use resource groups for your CloudTrail resources. For more information, see [AWS Resource Groups](https://docs.aws.amazon.com/ARG/latest/userguide/resource-groups.html) and [Tags](cloudtrail-concepts.md#cloudtrail-concepts-tags). 1. On the **Choose log events** page, choose the event types that you want to log. For **Management events**, do the following. 1. For **API activity**, choose if you want your trail to log **Read** events, **Write** events, or both. For more information, see [Management events](logging-management-events-with-cloudtrail.md#logging-management-events). 1. Choose **Exclude AWS KMS events** to filter AWS Key Management Service (AWS KMS) events out of your trail. The default setting is to include all AWS KMS events. The option to log or exclude AWS KMS events is available only if you log management events on your trail. If you choose not to log management events, AWS KMS events are not logged, and you cannot change AWS KMS event logging settings. AWS KMS actions such as `Encrypt`, `Decrypt`, and `GenerateDataKey` typically generate a large volume (more than 99%) of events. These actions are now logged as **Read** events. Low-volume, relevant AWS KMS actions such as `Disable`, `Delete`, and `ScheduleKey` (which typically account for less than 0.5% of AWS KMS event volume) are logged as **Write** events. To exclude high-volume events like `Encrypt`, `Decrypt`, and `GenerateDataKey`, but still log relevant events such as `Disable`, `Delete` and `ScheduleKey`, choose to log **Write** management events, and clear the check box for **Exclude AWS KMS events**. 1. Choose **Exclude Amazon RDS Data API events** to filter Amazon Relational Database Service Data API events out of your trail. The default setting is to include all Amazon RDS Data API events. For more information about Amazon RDS Data API events, see [Logging Data API calls with AWS CloudTrail](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/logging-using-cloudtrail-data-api.html) in the *Amazon RDS User Guide for Aurora*. 1. To log data events, choose **Data events**. Additional charges apply for logging data events. For more information, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). 1. **Important** Steps 12-16 are for configuring data events using advanced event selectors, which is the default. Advanced event selectors let you configure more [resource types](logging-data-events-with-cloudtrail.md#logging-data-events) and offer fine-grained control over which data events your trail captures. If you plan to log network activity events, you must use advanced event selectors. If you are using basic event selectors, complete the steps in [Configure data event settings using basic event selectors](cloudtrail-create-a-trail-using-the-console-first-time.md#trail-data-events-basic-selectors), then return to step 17 of this procedure. For **Resource type**, choose the resource type on which you want to log data events. For more information about available resource types, see [Data events](logging-data-events-with-cloudtrail.md#logging-data-events). 1. Choose a log selector template. You can choose a predefined template, or choose **Custom** to define your own event collection conditions. You can choose from the following predefined templates: + **Log all events** – Choose this template to log all events. + **Log only read events** – Choose this template to log only read events. Read-only events are events that do not change the state of a resource, such as `Get*` or `Describe*` events. + **Log only write events** – Choose this template to log only write events. Write events add, change, or delete resources, attributes, or artifacts, such as `Put*`, `Delete*`, or `Write*` events. + **Log only AWS Management Console events** – Choose this template to log only events originating from the AWS Management Console. + **Exclude AWS service initiated events** – Choose this template to exclude AWS service events, which have an `eventType` of `AwsServiceEvent`, and events initiated with AWS service-linked roles (SLRs). **Note** Choosing a predefined template for S3 buckets enables data event logging for all buckets currently in your AWS account and any buckets you create after you finish creating the trail. It also enables logging of data event activity performed by any IAM identity in your AWS account, even if that activity is performed on a bucket that belongs to another AWS account. If the trail applies only to one Region, choosing a predefined template that logs all S3 buckets enables data event logging for all buckets in the same Region as your trail and any buckets you create later in that Region. It will not log data events for Amazon S3 buckets in other Regions in your AWS account. If you're creating a multi-Region trail, choosing a predefined template for Lambda functions enables data event logging for all functions currently in your AWS account, and any Lambda functions you might create in any Region after you finish creating the trail. If you are creating a trail for a single Region (done by using the AWS CLI), this selection enables data event logging for all functions currently in that Region in your AWS account, and any Lambda functions you might create in that Region after you finish creating the trail. It does not enable data event logging for Lambda functions created in other Regions. Logging data events for all functions also enables logging of data event activity performed by any IAM identity in your AWS account, even if that activity is performed on a function that belongs to another AWS account. 1. (Optional) In **Selector name**, enter a name to identify your selector. The selector name is a descriptive name for an advanced event selector, such as "Log data events for only two S3 buckets". The selector name is listed as `Name` in the advanced event selector and is viewable if you expand the **JSON view**. 1. If you selected **Custom**, in **Advanced event selectors** build an expression based on the values of advanced event selector fields. **Note** Selectors don't support the use of wildcards like `*` . To match multiple values with a single condition, you may use `StartsWith`, `EndsWith`, `NotStartsWith`, or `NotEndsWith` to explicitly match the beginning or end of the event field. 1. Choose from the following fields. + **`readOnly`** - `readOnly` can be set to **equals** a value of `true` or `false`. Read-only data events are events that do not change the state of a resource, such as `Get*` or `Describe*` events. Write events add, change, or delete resources, attributes, or artifacts, such as `Put*`, `Delete*`, or `Write*` events. To log both `read` and `write` events, don't add a `readOnly` selector. + **`eventName`** - `eventName` can use any operator. You can use it to include or exclude any data event logged to CloudTrail, such as `PutBucket`, `GetItem`, or `GetSnapshotBlock`. + **`eventSource`** – The event source to include or exclude. This field can use any operator. + **eventType** – The event type to include or exclude. For example, you can set this field to **not equals** `AwsServiceEvent` to exclude [AWS service events](non-api-aws-service-events.md). For a list of event types, see [`eventType`](cloudtrail-event-reference-record-contents.md#ct-event-type) in [CloudTrail record contents for management, data, and network activity events](cloudtrail-event-reference-record-contents.md). + **sessionCredentialFromConsole** – Include or exclude events originating from an AWS Management Console session. This field can be set to **equals** or **not equals** with a value of `true`. + **userIdentity.arn** – Include or exclude events for actions taken by specific IAM identities. For more information, see [CloudTrail userIdentity element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html). + **`resources.ARN`** - You can use any operator with `resources.ARN`, but if you use **equals** or **does not equal**, the value must exactly match the ARN of a valid resource of the type you've specified in the template as the value of `resources.type`. **Note** You can't use the `resources.ARN` field to filter resource types that do not have ARNs. For more information about the ARN formats of data event resources, see [Actions, resources, and condition keys for AWS services](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html) in the *Service Authorization Reference*. 1. For each field, choose **\$1 Condition** to add as many conditions as you need, up to a maximum of 500 specified values for all conditions. For example, to exclude data events for two S3 buckets from data events that are logged on your event data store, you can set the field to **resources.ARN**, set the operator for **does not start with**, and then paste in an S3 bucket ARN for which you do not want to log events. To add the second S3 bucket, choose **\$1 Condition**, and then repeat the preceding instruction, pasting in the ARN for or browsing for a different bucket. For information about how CloudTrail evaluates multiple conditions, see [How CloudTrail evaluates multiple conditions for a field](filtering-data-events.md#filtering-data-events-conditions). **Note** You can have a maximum of 500 values for all selectors on an event data store. This includes arrays of multiple values for a selector such as `eventName`. If you have single values for all selectors, you can have a maximum of 500 conditions added to a selector. 1. Choose **\$1 Field** to add additional fields as required. To avoid errors, do not set conflicting or duplicate values for fields. For example, do not specify an ARN in one selector to be equal to a value, then specify that the ARN not equal the same value in another selector. 1. To add resource type on which to log data events, choose **Add data event type**. Repeat steps 12 through this step to configure advanced event selectors for the resource type. 1. To log network activity events, choose **Network activity events**. Network activity events enable VPC endpoint owners to record AWS API calls made using their VPC endpoints from a private VPC to the AWS service. Additional charges apply for logging data events. For more information, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). To log network activity events, do the following: 1. From **Network activity event source**, choose the source for network activity events. 1. In **Log selector template**, choose a template. You can choose to log all network activity events, log all network activity access denied events, or choose **Custom** to build a custom log selector to filter on multiple fields, such as `eventName` and `vpcEndpointId`. 1. (Optional) Enter a name to identify the selector. The selector name is listed as **Name** in the advanced event selector and is viewable if you expand the **JSON view**. 1. In **Advanced event selectors** build expressions by choosing values for **Field**, **Operator**, and **Value**. You can skip this step if you are using a predefined log template. 1. For excluding or including network activity events, you can choose from the following fields in the console. + **`eventName`** – You can use any operator with `eventName`. You can use it to include or exclude any event, such as `CreateKey`. + **`errorCode`** – You can use it to filter on an error code. Currently, the only supported `errorCode` is `VpceAccessDenied`. + **`vpcEndpointId`** – Identifies the VPC endpoint that the operation passed through. You can use any operator with `vpcEndpointId`. 1. For each field, choose **\$1 Condition** to add as many conditions as you need, up to a maximum of 500 specified values for all conditions. 1. Choose **\$1 Field** to add additional fields as required. To avoid errors, do not set conflicting or duplicate values for fields. 1. To add another event source for which you want to log network activity events, choose **Add network activity event selector**. 1. Optionally, expand **JSON view** to see your advanced event selectors as a JSON block. 1. Choose **Insights events** if you want your trail to log CloudTrail Insights events. In **Event type**, select **Insights events**. In **Insights events**, choose **API call rate**, **API error rate**, or both. You must be logging **Write** management events to log Insights events for **API call rate**. You must be logging **Read** or **Write** management events to log Insights events for **API error rate**. CloudTrail Insights analyzes management events for unusual activity, and logs events when anomalies are detected. By default, trails don't log Insights events. For more information about Insights events, see [Working with CloudTrail Insights](logging-insights-events-with-cloudtrail.md). Additional charges apply for logging Insights events. For CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). Insights events are delivered to a different folder named `/CloudTrail-Insight`of the same S3 bucket that is specified in the **Storage location** area of the trail details page. CloudTrail creates the new prefix for you. For example, if your current destination S3 bucket is named `amzn-s3-demo-destination-bucket/AWSLogs/CloudTrail/`, the S3 bucket name with a new prefix is named `amzn-s3-demo-destination-bucket/AWSLogs/CloudTrail-Insight/`. 1. When you are finished choosing event types to log, choose **Next**. 1. On the **Review and create** page, review your choices. Choose **Edit** in a section to change the trail settings shown in that section. When you are ready to create the trail, choose **Create trail**. 1. The new trail appears on the **Trails** page. An organization trail might take up to 24 hours to be created in all enabled Regions in all member accounts. The **Trails** page shows the trails in your account from all Regions. In about 5 minutes, CloudTrail publishes log files that show the AWS API calls made in your organization. You can see the log files in the Amazon S3 bucket that you specified. **Note** You can't rename a trail after it has been created. Instead, you can delete the trail and create a new one. ## Next steps After you create your trail, you can return to the trail to make changes: + Change the configuration of your trail by editing it. For more information, see [Updating a trail with the CloudTrail console](cloudtrail-update-a-trail-console.md). + If needed, configure the Amazon S3 bucket to allow specific users in member accounts to read the log files for the organization. For more information, see [Sharing CloudTrail log files between AWS accounts](cloudtrail-sharing-logs.md). + Configure CloudTrail to send log files to CloudWatch Logs. For more information, see [Sending events to CloudWatch Logs](send-cloudtrail-events-to-cloudwatch-logs.md) and [the CloudWatch Logs item](creating-an-organizational-trail-prepare.md#cwl-org-pb) in [Prepare for creating a trail for your organization](creating-an-organizational-trail-prepare.md). **Note** Only the management account can configure a CloudWatch Logs log group for an organization trail. + Create a table and use it to run a query in Amazon Athena to analyze your AWS service activity. For more information, see [Creating a Table for CloudTrail Logs in the CloudTrail Console](https://docs.aws.amazon.com/athena/latest/ug/cloudtrail-logs.html#create-cloudtrail-table-ct) in the [Amazon Athena User Guide](https://docs.aws.amazon.com/athena/latest/ug/). + Add custom tags (key-value pairs) to the trail. + To create another organization trail, return to the **Trails** page and choose **Create trail**. **Note** When you configure a trail, you can choose an Amazon S3 bucket and SNS topic that belong to another account. However, if you want CloudTrail to deliver events to a CloudWatch Logs log group, you must choose a log group that exists in your current account. # Creating a trail for an organization with the AWS CLI You can create an organization trail by using the AWS CLI. The AWS CLI is regularly updated with additional functionality and commands. To help ensure success, be sure that you have installed or updated to a recent AWS CLI version before you begin. **Note** The examples in this section are specific to creating and updating organization trails. For examples of using the AWS CLI to manage trails, see [Managing trails with the AWS CLI](cloudtrail-additional-cli-commands.md) and [Configuring CloudWatch Logs monitoring with the AWS CLI](send-cloudtrail-events-to-cloudwatch-logs.md#send-cloudtrail-events-to-cloudwatch-logs-cli). When creating or updating an organization trail with the AWS CLI, you must use an AWS CLI profile in the management account or delegated administrator account with sufficient permissions. If you are converting an organization trail to a non-organization trail, you must use the management account for the organization. You must configure the Amazon S3 bucket used for an organization trail with sufficient permissions. ## 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 first statement allows CloudTrail to call the Amazon S3 `GetBucketAcl` action on the Amazon S3 bucket. + The second statement allows logging in the event the trail is changed from an organization trail to a trail for that account only. + The third statement allows logging for an organization trail. 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 AWS accounts](cloudtrail-sharing-logs.md). ## Enabling CloudTrail as a trusted service in AWS 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](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_support-all-features.html), 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 AWS 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. **Note** When you create an organization trail with the AWS CLI, you must use an AWS CLI profile in the management account or delegated administrator account with sufficient permissions. 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" } ``` **Note** Run the `start-logging` command to start logging for your trail. For more information, see [Stopping and starting logging for a trail](cloudtrail-additional-cli-commands.md#cloudtrail-start-stop-logging-cli-commands). ### Creating an organization trail as a single-Region trail The following command creates an organization trail that only logs events in a single AWS Region, also known as a single-Region trail. The AWS Region where events are logged is the Region specified in the configuration profile for the AWS 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](cloudtrail-trail-naming-requirements.md). 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. **Note** Run the `start-logging` command to start logging for your trail. ## 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 AWS account to an entire organization. Remember that you can run the `update-trail` command only from the Region in which the trail was created. **Note** If you use the AWS CLI or one of the AWS SDKs to update a trail, be sure that the trail's bucket policy is up-to-date. For more information, see [Creating a trail for an organization with the AWS CLI](#cloudtrail-create-and-update-an-organizational-trail-by-using-the-aws-cli). When you update an organization trail with the AWS CLI, you must use an AWS CLI profile in the management account or delegated administrator account with sufficient permissions. If you want to convert an organization trail to a non-organization trail, you must use the management account for the organization, because the management account is the owner of all organization resources. CloudTrail updates organization trails in member accounts even if a resource validation fails. Examples of validation failures include: an incorrect Amazon S3 bucket policy an incorrect Amazon SNS topic policy inability to deliver to a CloudWatch Logs log group insufficient permission to encrypt using a KMS key A member account with CloudTrail permissions can see any validation failures for an organization trail by viewing the trail's details page on the CloudTrail console, or by running the AWS CLI [https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html) command. ### Applying an existing trail to an organization To change an existing trail so that it also applies to an organization instead of a single AWS account, add the `--is-organization-trail` option, as shown in the following example. **Note** Use the management account to change an existing non-organization trail to an organization trail. ``` 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" } ``` # Troubleshooting issues with an organization trail This section provides information on how to troubleshoot issues with an organization trail. **Topics** + [ ## CloudTrail is not delivering events ](#event-delivery-failure-optin) + [ ## CloudTrail is not sending Amazon SNS notifications for a member account in an organization ](#sns-topic-policy-failure) ## CloudTrail is not delivering events **If CloudTrail is not delivering CloudTrail log files to the Amazon S3 bucket** Check if there is an issue with the S3 bucket. + From the CloudTrail console, check the trail's details page. If there's an issue with the S3 bucket, the details page includes a warning that delivery to the S3 bucket failed. + From the AWS CLI, run the [https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html) command. If there's a failure, the command output includes the `LatestDeliveryError` field, which displays any Amazon S3 error that CloudTrail encountered when attempting to deliver log files to the designated bucket. This error occurs only when there is a problem with the destination S3 bucket, and does not occur for requests that time out. To resolve the issue, fix the bucket policy so that CloudTrail can write to the bucket; or create a new bucket, and then call `update-trail` to specify the new bucket. For information about the organization bucket policy, see [Create or update an Amazon S3 bucket to use to store the log files for an organization trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/create-s3-bucket-policy-for-cloudtrail.html#org-trail-bucket-policy). **Note** If you misconfigure your trail (for example, the S3 bucket is unreachable), CloudTrail will attempt to redeliver the log files to your S3 bucket for 30 days, and these attempted-to-deliver events will be subject to standard CloudTrail charges. To avoid charges on a misconfigured trail, you need to delete the trail. **If CloudTrail is not delivering logs to CloudWatch Logs** Check if there is an issue with the configuration of the CloudWatch Logs role policy. + From the CloudTrail console, check the trail's details page. If there's an issue with CloudWatch Logs, the details page includes a warning that indicates CloudWatch Logs delivery failed. + From the AWS CLI, run the [https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html) command. If there's a failure, the command output includes the `LatestCloudWatchLogsDeliveryError` field, which displays any CloudWatch Logs error that CloudTrail encountered when attempting to deliver logs to CloudWatch Logs. To resolve the issue, fix the CloudWatch Logs role policy. For information about the CloudWatch Logs role policy, see [Role policy document for CloudTrail to use CloudWatch Logs for monitoring](cloudtrail-required-policy-for-cloudwatch-logs.md). **If you're not seeing activity for a member account in an organization trail** If you're not seeing activity for a member account in an organization trail, check the following: + **Check the home Region for the trail to see if it is an opt-in Region** Although most AWS Regions are enabled by default for your AWS account, you must manually enable certain Regions (also referred to as *opt-in Regions*). For information about which Regions are enabled by default, see [Considerations before enabling and disabling Regions](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-considerations) in the *AWS Account Management Reference Guide*. For the list of Regions CloudTrail supports, see [CloudTrail supported Regions](cloudtrail-supported-regions.md). If the organization trail is multi-Region and the home Region is an opt-in Region, member accounts will not send activity to the organization trail unless they opt into the AWS Region where the multi-Region trail was created. For example, if you create a multi-Region trail and choose the Europe (Spain) Region as the home Region for the trail, only member accounts that enabled the Europe (Spain) Region for their account will send their account activity to the organization trail. To resolve the issue, enable the opt-in Region in each member account in your organization. For information about enabling an opt-in Region, see [Enable or disable a Region in your organization](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-enable-organization) in the *AWS Account Management Reference Guide*. + **Check if the organization resource-based policy conflicts with the CloudTrail service-linked role policy** CloudTrail uses the service-linked role named [`AWSServiceRoleForCloudTrail`](using-service-linked-roles-create-slr-for-org-trails.md#service-linked-role-permissions-create-slr-for-org-trails) to support organization trails. This service-linked role allows CloudTrail to perform actions on organization resources, such as `organizations:DescribeOrganization`. If the organization's resource-based policy denies an action that is allowed in the service-linked role policy, CloudTrail will not be able to perform the action even though it is allowed in the service-linked role policy. To resolve the issue, fix the organization's resource-based policy so that it doesn't deny actions that are allowed in the service-linked role policy. ## CloudTrail is not sending Amazon SNS notifications for a member account in an organization When a member account with an AWS Organizations organization trail is not sending Amazon SNS notifications, there could be an issue with the configuration of the SNS topic policy. CloudTrail creates organization trails in member accounts even if a resource validation fails, for example, the organization trail's SNS topic does not include all member account IDs. If the SNS topic policy is incorrect, an authorization failure occurs. To check whether a trail's SNS topic policy has an authorization failure: + From the CloudTrail console, check the trail's details page. If there's an authorization failure, the details page includes a warning `SNS authorization failed` and indicates to fix the SNS topic policy. + From the AWS CLI, run the [https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html) command. If there's an authorization failure, the command output includes the `LastNotificationError` field with a value of `AuthorizationError`. To resolve the issue, fix the Amazon SNS topic policy. For information about the Amazon SNS topic policy, see [Amazon SNS topic policy for CloudTrail](cloudtrail-permissions-for-sns-notifications.md). For more information about SNS topics and subscribing to them, see [Getting started with Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html) in the *Amazon Simple Notification Service Developer Guide*. # Understanding multi-Region trails and opt-in Regions A trail can be applied to all AWS Regions that are [enabled](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-enable-standalone) in your AWS account, or can be applied to a single Region. A trail that applies to all AWS Regions that are enabled in your AWS account is referred to as a *multi-Region trail*. As a best practice, we recommend creating a multi-Region trail because it captures activity in all enabled Regions. All trails created using the CloudTrail console are multi-Region trails. You can only create a single-Region trail using the AWS CLI or [https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_CreateTrail.html](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_CreateTrail.html) API operation. Although most AWS Regions are enabled by default for your AWS account, you must manually enable certain Regions (also referred to as *opt-in Regions*). For information about which Regions are enabled by default, see [Considerations before enabling and disabling Regions](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-considerations) in the *AWS Account Management Reference Guide*. For the list of Regions CloudTrail supports, see [CloudTrail supported Regions](cloudtrail-supported-regions.md). **Topics** + [ ## What are the advantages of multi-Region trails? ](#cloudtrail-multi-region-trails-advantages) + [ ## What happens when you create a multi-Region trail? ](#cloudtrail-multi-region-trails-create) + [ ## What happens when you enable an opt-in Region? ](#cloudtrail-multi-region-trails-optin) + [ ## What happens when you disable an opt-in Region? ](#cloudtrail-multi-region-trails-disable) ## What are the advantages of multi-Region trails? A multi-Region trail has the following advantages: + The configuration settings for the trail apply consistently across all [enabled](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html) AWS Regions. + You receive CloudTrail events from all enabled AWS Regions in a single Amazon S3 bucket and, optionally, in a CloudWatch Logs log group. + You manage trail configurations for all enabled AWS Regions from one location. ## What happens when you create a multi-Region trail? Creating a multi-Region trail, has the following effects: + CloudTrail delivers log files for account activity from all [enabled](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html) AWS Regions to the single Amazon S3 bucket that you specify, and, optionally, to a CloudWatch Logs log group. + If you configured an Amazon SNS topic for the trail, SNS notifications about log file deliveries in all enabled AWS Regions are sent to that single SNS topic. + You can see the multi-Region trail in all enabled AWS Regions, but you can only modify the trail in the home Region where it was created. ## What happens when you enable an opt-in Region? After you enable an opt-in Region, CloudTrail creates an identical copy of each multi-Region trail in the opt-in Region that you enabled. CloudTrail uses a distributed computing model called [eventual consistency](cloudtrail-data-consistency.md). Because enabling a Region takes a few minutes to several hours, you may not immediately see all events in the logs for the newly enabled Region. It may take up to several hours for CloudTrail to deliver all logs for the newly enabled Region. During this time, you can view the last 90 days of management events logged in that Region by viewing the CloudTrail [https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events-console.html](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events-console.html), or by running the [https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events-cli.html](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events-cli.html) command. Event history is active by default in your AWS account, captures the last 90 days of management events logged in a Region, and does not require a trail. For information about enabling an opt-in Region for your AWS account, see [Enable or disable a Region for standalone accounts](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-enable-standalone) or [Enable or disable a Region in your organization](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-enable-organization). ## What happens when you disable an opt-in Region? Because your account may have activity in the Region you disabled, such as actions by AWS services to remove resources, CloudTrail will continue to capture activity and attempt to deliver events to the S3 bucket for any trails that are not deleted before the Region is disabled. # Copying trail events to CloudTrail Lake You can copy existing trail events to a CloudTrail Lake event data store to create a point-in-time snapshot of events logged to the trail. Copying trail events does not interfere with the trail's ability to log events and does not modify the trail in any way. You can copy trail events to an existing event data store configured for CloudTrail events, or you can create a new CloudTrail event data store and choose the **Copy trail events** option as part of event data store creation. For more information about copying trail events to an existing event data store, see [Copy trail events to an existing event data store using the CloudTrail console](cloudtrail-copy-trail-events.md). For more information about creating a new event data store, see [Create an event data store for CloudTrail events with the console](query-event-data-store-cloudtrail.md). Copying trail events to a CloudTrail Lake event data store, allows you to run queries on the copied events. CloudTrail Lake queries offer a deeper and more customizable view of events than simple key and value lookups in Event history, or running `LookupEvents`. For more information on CloudTrail Lake, see [Working with AWS CloudTrail Lake](cloudtrail-lake.md). If you are copying trail events to an organization event data store, you must use the management account for the organization. You cannot copy trail events using the delegated administrator account for an organization. CloudTrail Lake event data stores incur charges. When you create an event data store, you choose the [pricing option](cloudtrail-lake-manage-costs.md#cloudtrail-lake-manage-costs-pricing-option) you want to use for the event data store. The pricing option determines the cost for ingesting and storing events, and the default and maximum retention period for the event data store. For information about CloudTrail pricing and managing Lake costs, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/) and [Managing CloudTrail Lake costs](cloudtrail-lake-manage-costs.md). When you copy trail events to a CloudTrail Lake event data store, you incur charges based on the amount of uncompressed data the event data store ingests. When you copy trail events to CloudTrail Lake, CloudTrail unzips the logs that are stored in gzip (compressed) format and then copies the events contained in the logs to your event data store. The size of the uncompressed data could be greater than the actual S3 storage size. To get a general estimate of the size of the uncompressed data, you can multiply the size of the logs in the S3 bucket by 10. You can reduce costs by specifying a narrower time range for the copied events. If you are planning to only use the event data store to query your copied events, you can turn off event ingestion to avoid incurring charges on future events. For more information, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/) and [Managing CloudTrail Lake costs](cloudtrail-lake-manage-costs.md). **Scenarios** The following table describes some common scenarios for copying trail events and how you accomplish each scenario using the console. | Scenario | How do I accomplish this in the console? | | --- | --- | | Analyze and query historical trail events in CloudTrail Lake without ingesting new events | Create a [new event data store](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-event-data-store-cloudtrail.html#query-event-data-store-cloudtrail-procedure) and choose the **Copy trail events** option as part of event data store creation. When creating the event data store, deselect **Ingest events** (step 15 of the procedure) to ensure the event data store contains only the historical events for your trail and no future events. | | Replace your existing trail with a CloudTrail Lake event data store | Create an event data store with the same event selectors as your trail to ensure that the event data store has the same coverage as your trail. To avoid duplicating events between the source trail and destination event data store, choose a date range for the copied events that is earlier than the creation of the event data store. After your event data store is created, you can turn off logging for the trail to avoid additional charges. | **Topics** + [ ## Considerations for copying trail events ](#cloudtrail-trail-copy-considerations) + [ ## Required permissions for copying trail events ](#cloudtrail-copy-trail-events-permissions) + [ # Copy trail events to an existing event data store using the CloudTrail console ](cloudtrail-copy-trail-events.md) ## Considerations for copying trail events Consider the following factors when copying trail events. + When copying trail events, CloudTrail uses the S3 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API operation to retrieve the trail events in the source S3 bucket. There are some S3 archived storage classes, such as S3 Glacier Flexible Retrieval, S3 Glacier Deep Archive, S3 Outposts, and S3 Intelligent-Tiering Deep Archive tiers that are not accessible by using `GetObject`. To copy trail events stored in these archived storage classes, you must first restore a copy using the S3 `RestoreObject` operation. For information about restoring archived objects, see [Restoring Archived Objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/restoring-objects.html) in the *Amazon S3 User Guide*. + When you copy trail events to an event data store, CloudTrail copies all trail events regardless of the configuration of the destination event data store's event types, advanced event selectors, or AWS Region. + Before copying trail events to an existing event data store, be sure the event data store's pricing option and retention period are configured appropriately for your use case. + **Pricing option:** The pricing option determines the cost for ingesting and storing events. For more information about pricing options, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/) and [Event data store pricing options](cloudtrail-lake-manage-costs.md#cloudtrail-lake-manage-costs-pricing-option). + **Retention period:** The retention period determines how long event data is kept in the event data store. CloudTrail only copies trail events that have an `eventTime` within the event data store’s retention period. To determine the appropriate retention period, take the sum of the oldest event you want to copy in days and the number of days you want to retain the events in the event data store (**retention period** = *oldest-event-in-days* \$1 *number-days-to-retain*). For example, if the oldest event you're copying is 45 days old and you want to keep the events in the event data store for a further 45 days, you would set the retention period to 90 days. + If you are copying trail events to an event data store for investigation and do not want to ingest any future events, you can stop ingestion on the event data store. When creating the event data store, deselect the **Ingest events** option (step 15 of the [procedure](query-event-data-store-cloudtrail.md#query-event-data-store-cloudtrail-procedure)) to ensure the event data store contains only the historical events for your trail and no future events. + Before copying trail events, disable any access control lists (ACLs) attached to the source S3 bucket, and update the S3 bucket policy for the destination event data store. For more information about updating the S3 bucket policy, see [Amazon S3 bucket policy for copying trail events](#cloudtrail-copy-trail-events-permissions-s3). For more information about disabling ACLs, see [ Controlling ownership of objects and disabling ACLs for your bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html). + CloudTrail only copies trail events from Gzip compressed log files that are in the source S3 bucket. CloudTrail does not copy trail events from uncompressed log files, or log files that were compressed using a format other than Gzip. + To avoid duplicating events between the source trail and destination event data store, choose a time range for the copied events that is earlier than the creation of the event data store. + By default, CloudTrail only copies CloudTrail events contained in the S3 bucket's `CloudTrail` prefix and the prefixes inside the `CloudTrail` prefix, and does not check prefixes for other AWS services. If you want to copy CloudTrail events contained in another prefix, you must choose the prefix when you copy trail events. + To copy trail events to an organization event data store, you must use the management account for the organization. You cannot use the delegated administrator account to copy trail events to an organization event data store. ## Required permissions for copying trail events Before copying trail events, ensure you have all the required permissions for your IAM role. You only need to update the IAM role permissions if you choose an existing IAM role to copy trail events. If you choose to create a new IAM role, CloudTrail provides all necessary permissions for the role. If the source S3 bucket uses a KMS key for data encryption, ensure that the KMS key policy allows CloudTrail to decrypt data in the bucket. If the source S3 bucket uses multiple KMS keys, you must update each key's policy to allow CloudTrail to decrypt the data in the bucket. **Topics** + [ ### IAM permissions for copying trail events ](#cloudtrail-copy-trail-events-permissions-iam) + [ ### Amazon S3 bucket policy for copying trail events ](#cloudtrail-copy-trail-events-permissions-s3) + [ ### KMS key policy for decrypting data in the source S3 bucket ](#cloudtrail-copy-trail-events-permissions-kms) ### IAM permissions for copying trail events When copying trail events, you have the option to create a new IAM role, or use an existing IAM role. When you choose a new IAM role, CloudTrail creates an IAM role with the required permissions and no further action is required on your part. If you choose an existing role, ensure the IAM role's policies allow CloudTrail to copy trail events from the source S3 bucket. This section provides examples of the required IAM role permission and trust policies. The following example provides the permissions policy, which allows CloudTrail to copy trail events from the source S3 bucket. Replace *amzn-s3-demo-bucket*, *myAccountID*, *region*, *prefix*, and *eventDataStoreId* with the appropriate values for your configuration. The *myAccountID* is the AWS account ID used for CloudTrail Lake, which may not be the same as the AWS account ID for the S3 bucket. Replace *key-region*, *keyAccountID*, and *keyID* with the values for the KMS key used to encrypt the source S3 bucket. You can omit the `AWSCloudTrailImportKeyAccess` statement if the source S3 bucket does not use a KMS key for encryption. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "AWSCloudTrailImportBucketAccess", "Effect": "Allow", "Action": ["s3:ListBucket", "s3:GetBucketAcl"], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket" ], "Condition": { "StringEquals": { "aws:SourceAccount": "myAccountID", "aws:SourceArn": "arn:aws:cloudtrail:region:myAccountID:eventdatastore/eventDataStoreId" } } }, { "Sid": "AWSCloudTrailImportObjectAccess", "Effect": "Allow", "Action": ["s3:GetObject"], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/prefix", "arn:aws:s3:::amzn-s3-demo-bucket/prefix/*" ], "Condition": { "StringEquals": { "aws:SourceAccount": "myAccountID", "aws:SourceArn": "arn:aws:cloudtrail:region:myAccountID:eventdatastore/eventDataStoreId" } } }, { "Sid": "AWSCloudTrailImportKeyAccess", "Effect": "Allow", "Action": ["kms:GenerateDataKey","kms:Decrypt"], "Resource": [ "arn:aws:kms:key-region:keyAccountID:key/keyID" ] } ] } ``` The following example provides the IAM trust policy, which allows CloudTrail to assume an IAM role to copy trail events from the source S3 bucket. Replace *myAccountID*, *region*, and *eventDataStoreArn* with the appropriate values for your configuration. The *myAccountID* is the AWS account ID used for CloudTrail Lake, which may not be the same as the AWS account ID for the S3 bucket. ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "cloudtrail.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "myAccountID", "aws:SourceArn": "arn:aws:cloudtrail:region:myAccountID:eventdatastore/eventDataStoreId" } } } ] } ``` ### Amazon S3 bucket policy for copying trail events By default, Amazon S3 buckets and objects are private. Only the resource owner (the AWS account that created the bucket) can access the bucket and objects it contains. The resource owner can grant access permissions to other resources and users by writing an access policy. Before you copy trail events, you must update the S3 bucket policy to allow CloudTrail to copy trail events from the source S3 bucket. You can add the following statement to the S3 bucket policy to grant these permissions. Replace *roleArn* and *amzn-s3-demo-bucket* with the appropriate values for your configuration. **** ``` { "Sid": "AWSCloudTrailImportBucketAccess", "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetBucketAcl", "s3:GetObject" ], "Principal": { "AWS": "roleArn" }, "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket", "arn:aws:s3:::amzn-s3-demo-bucket/*" ] }, ``` ### KMS key policy for decrypting data in the source S3 bucket If the source S3 bucket uses a KMS key for data encryption, ensure the KMS key policy provides CloudTrail with the `kms:Decrypt` and `kms:GenerateDataKey` permissions required to copy trail events from an S3 bucket with SSE-KMS encryption enabled. If your source S3 bucket uses multiple KMS keys, you must update each key's policy. Updating the KMS key policy allows CloudTrail to decrypt data in the source S3 bucket, run validation checks to ensure that events conform to CloudTrail standards, and copy events into the CloudTrail Lake event data store. The following example provides the KMS key policy, which allows CloudTrail to decrypt the data in the source S3 bucket. Replace *roleArn*, *amzn-s3-demo-bucket*, *myAccountID*, *region*, and *eventDataStoreId* with the appropriate values for your configuration. The *myAccountID* is the AWS account ID used for CloudTrail Lake, which may not be the same as the AWS account ID for the S3 bucket. ``` { "Sid": "AWSCloudTrailImportDecrypt", "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:GenerateDataKey" ], "Principal": { "AWS": "roleArn" }, "Resource": "*", "Condition": { "StringLike": { "kms:EncryptionContext:aws:s3:arn": "arn:aws:s3:::amzn-s3-demo-bucket/*" }, "StringEquals": { "aws:SourceAccount": "myAccountID", "aws:SourceArn": "arn:aws:cloudtrail:region:myAccountID:eventdatastore/eventDataStoreId" } } } ``` # Copy trail events to an existing event data store using the CloudTrail console Use the following procedure to copy trail events to an existing event data store. For information about how to create a new event data store, see [Create an event data store for CloudTrail events with the console](query-event-data-store-cloudtrail.md). **Note** Before copying trail events to an existing event data store, be sure the event data store's pricing option and retention period are configured appropriately for your use case. **Pricing option:** The pricing option determines the cost for ingesting and storing events. For more information about pricing options, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/) and [Event data store pricing options](cloudtrail-lake-manage-costs.md#cloudtrail-lake-manage-costs-pricing-option). **Retention period:** The retention period determines how long event data is kept in the event data store. CloudTrail only copies trail events that have an `eventTime` within the event data store’s retention period. To determine the appropriate retention period, take the sum of the oldest event you want to copy in days and the number of days you want to retain the events in the event data store (**retention period** = *oldest-event-in-days* \$1 *number-days-to-retain*). For example, if the oldest event you're copying is 45 days old and you want to keep the events in the event data store for a further 45 days, you would set the retention period to 90 days. **To copy trail events to an event data store** 1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/). 1. Choose **Trails** in the left navigation pane of the CloudTrail console. 1. On the **Trails** page, choose the trail, and then choose **Copy events to Lake**. If the source S3 bucket for the trail uses a KMS key for data encryption, ensure that the KMS key policy allows CloudTrail to decrypt data in the bucket. If the source S3 bucket uses multiple KMS keys, you must update each key's policy to allow CloudTrail to decrypt data in the bucket. For more information about updating the KMS key policy, see [KMS key policy for decrypting data in the source S3 bucket](cloudtrail-copy-trail-to-lake.md#cloudtrail-copy-trail-events-permissions-kms). 1. (Optional) By default, CloudTrail only copies CloudTrail events contained in the S3 bucket's `CloudTrail` prefix and the prefixes inside the `CloudTrail` prefix, and does not check prefixes for other AWS services. If you want to copy CloudTrail events contained in another prefix, choose **Enter S3 URI**, and then choose **Browse S3** to browse to the prefix. The S3 bucket policy must grant CloudTrail access to copy trail events. For more information about updating the S3 bucket policy, see [Amazon S3 bucket policy for copying trail events](cloudtrail-copy-trail-to-lake.md#cloudtrail-copy-trail-events-permissions-s3). 1. For **Specify a time range of events**, choose the time range for copying the events. CloudTrail checks the prefix and log file name to verify the name contains a date between the chosen start and end date before attempting to copy trail events. You can choose a **Relative range** or an **Absolute range**. To avoid duplicating events between the source trail and destination event data store, choose a time range that is earlier than the creation of the event data store. **Note** CloudTrail only copies trail events that have an `eventTime` within the event data store’s retention period. For example, if an event data store’s retention period is 90 days, then CloudTrail will not copy any trail events with an `eventTime` older than 90 days. + If you choose **Relative range**, you can choose to copy events logged in the last 6 months, 1 year, 2 years, 7 years, or a custom range. CloudTrail copies the events logged within the chosen time period. + If you choose **Absolute range**, you can choose a specific start and end date. CloudTrail copies the events that occurred between the chosen start and end dates. 1. For **Delivery location**, choose the destination event data store from the drop-down list. 1. For **Permissions**, choose from the following IAM role options. If you choose an existing IAM role, verify that the IAM role policy provides the necessary permissions. For more information about updating the IAM role permissions, see [IAM permissions for copying trail events](cloudtrail-copy-trail-to-lake.md#cloudtrail-copy-trail-events-permissions-iam). + Choose **Create a new role (recommended)** to create a new IAM role. For **Enter IAM role name**, enter a name for the role. CloudTrail automatically creates the necessary permissions for this new role. + Choose **Use a custom IAM role ARN** to use a custom IAM role that is not listed. For **Enter IAM role ARN**, enter the IAM ARN. + Choose an existing IAM role from the drop-down list. 1. Choose **Copy events**. 1. You are prompted to confirm the copy. When you are ready to confirm, choose **Copy trail events to Lake**, and then choose **Copy events**. 1. On the **Copy details** page, you can see the copy status and review any failures. When a trail event copy completes, its **Copy status** is set to either **Completed** if there were no errors, or **Failed** if errors occurred. **Note** Details shown on the event copy details page are not in real-time. The actual values for details such as **Prefixes copied** may be higher than what is shown on the page. CloudTrail updates the details incrementally over the course of the event copy. 1. If the **Copy status** is **Failed**, fix any errors shown in **Copy failures**, and then choose **Retry copy**. When you retry a copy, CloudTrail resumes the copy at the location where the failure occurred. For more information about viewing the details of a trail event copy, see [View event copy details with the CloudTrail console](copy-trail-details.md). # Getting and viewing your CloudTrail log files After you create a trail and configure it to capture the log files you want, you need to be able to find the log files and interpret the information they contain. CloudTrail delivers your log files to an Amazon S3 bucket that you specify when you create the trail. CloudTrail typically delivers logs within an average of about 5 minutes of an API call. This time is not guaranteed. Review the [AWS CloudTrail Service Level Agreement](https://aws.amazon.com/cloudtrail/sla) for more information. Insights events are typically delivered to your bucket within 30 minutes of unusual activity. After you enable Insights events for the first time, allow up to 36 hours to see the first Insights events, if unusual activity is detected. **Note** If you misconfigure your trail (for example, the S3 bucket is unreachable), CloudTrail will attempt to redeliver the log files to your S3 bucket for 30 days, and these attempted-to-deliver events will be subject to standard CloudTrail charges. To avoid charges on a misconfigured trail, you need to delete the trail. **Topics** + [ ## Finding your CloudTrail log files ](#cloudtrail-find-log-files) + [ # Downloading your CloudTrail log files ](cloudtrail-read-log-files.md) ## Finding your CloudTrail log files CloudTrail publishes log files to your S3 bucket in a gzip archive. In the S3 bucket, the log file has a formatted name that includes the following elements: + The bucket name that you specified when you created trail (found on the Trails page of the CloudTrail console) + The (optional) prefix you specified when you created your trail + The string "AWSLogs" + The account number + The string "CloudTrail" for data, management events + The string "CloudTrail-Insight" for insights events + The string "CloudTrail-NetworkActivity" for network activity events + The string "CloudTrail-Aggregated" for aggregated events for data events + A Region identifier such as us-west-1 + The year the log file was published in `YYYY` format + The month the log file was published in `MM` format + The day the log file was published in `DD` format + An alphanumeric string that disambiguates the file from others that cover the same time period The following example shows a complete log file object name for data, management events: ``` amzn-s3-demo-bucket/prefix_name/AWSLogs/Account ID/CloudTrail/region/YYYY/MM/DD/file_name.json.gz ``` The following example shows a complete log file object name for insight events: ``` amzn-s3-demo-bucket/prefix_name/AWSLogs/Account ID/CloudTrail-Insight/region/YYYY/MM/DD/file_name.json.gz ``` The following example shows a complete log file object name for network activity events: ``` amzn-s3-demo-bucket/prefix_name/AWSLogs/Account ID/CloudTrail-NetworkActivity/region/YYYY/MM/DD/file_name.json.gz ``` The following example shows a complete log file object name for data event aggregations: ``` amzn-s3-demo-bucket/prefix_name/AWSLogs/Account ID/CloudTrail-Aggregated/region/YYYY/MM/DD/file_name.json.gz ``` **Note** For organization trails, the log file object name in the S3 bucket includes the organization unit ID in the path, as follows: ``` amzn-s3-demo-bucket/prefix_name/AWSLogs/O-ID/Account ID/CloudTrail/Region/YYYY/MM/DD/file_name.json.gz ``` To retrieve a log file, you can use the Amazon S3 console, the Amazon S3 command line interface (CLI), or the API. **To find your log files with the Amazon S3 console** 1. Open the Amazon S3 console. 1. Choose the bucket you specified. 1. Navigate through the object hierarchy until you find the log file you want. All log files have a .gz extension. You will navigate through an object hierarchy that is similar to the following example, but with a different bucket name, account ID, Region, and date. ``` All Buckets amzn-s3-demo-bucket AWSLogs 123456789012 CloudTrail us-west-1 2014 06 20 ``` A log file for the preceding object hierarchy will look like the following: ``` 123456789012_CloudTrail_us-west-1_20140620T1255ZHdkvFTXOA3Vnhbc.json.gz ``` **Note** Although uncommon, you may receive log files that contain one or more duplicate events. In most cases, duplicate events will have the same `eventID`. For more information about the `eventID` field, see [CloudTrail record contents for management, data, and network activity events](cloudtrail-event-reference-record-contents.md). # Downloading your CloudTrail log files Log files are in JSON format. If you have a JSON viewer add-on installed, you can view the files directly in your browser. Double-click the log file name in the bucket to open a new browser window or tab. The JSON displays in a readable format. CloudTrail log files are Amazon S3 objects. You can use the Amazon S3 console, the AWS Command Line Interface (CLI), or the Amazon S3 API to retrieve log files. For more information, see [Amazon S3 objects overview](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingObjects.html) in the* Amazon Simple Storage Service User Guide.* The following procedure describes how to download a log file with the AWS Management Console. **To download and read a log file** 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. Choose the bucket and choose the log file that you want to download. 1. Choose **Download** or **Download as** and follow the prompts to save the file. This saves the file in compressed format. **Note** Some browsers, such as Chrome, automatically extract the log file for you. If your browser does this for you, skip to step 5. 1. Use a product such as [7-Zip](https://www.7-zip.org/) to extract the log file. 1. Open the log file in a text editor such as Notepad\$1\$1. For more information about the event fields that can appear in a log file entry, see [CloudTrail record contents for management, data, and network activity events](cloudtrail-event-reference-record-contents.md). AWS partners with third-party specialists in logging and analysis to provide solutions that use CloudTrail output. For more information, see [AWS CloudTrail partners](https://aws.amazon.com/cloudtrail/partners/). **Note** You can also use the **Event history** feature to look up events for create, update, and delete API activity during the last 90 days. For more information, see [Working with CloudTrail event history](view-cloudtrail-events.md). # Configuring Amazon SNS notifications for CloudTrail You can be notified when CloudTrail publishes new log files to your Amazon S3 bucket. You manage notifications using Amazon Simple Notification Service (Amazon SNS). Notifications are optional. If you want notifications, you configure CloudTrail to send update information to an Amazon SNS topic whenever a new log file has been sent. To receive these notifications, you can use Amazon SNS to subscribe to the topic. As a subscriber you can get updates sent to a Amazon Simple Queue Service (Amazon SQS) queue, which enables you to handle these notifications programmatically. **Topics** + [ ## Configuring CloudTrail to send notifications ](#configure-cloudtrail-to-send-notifications) ## Configuring CloudTrail to send notifications On the CloudTrail console, you can configure a trail to use an Amazon SNS topic by enabling the **SNS notification delivery** option when you [create](cloudtrail-create-a-trail-using-the-console-first-time.md#creating-a-trail-in-the-console) or [update](cloudtrail-update-a-trail-console.md) a trail. If you choose to use a new topic, CloudTrail creates the Amazon SNS topic for you and attaches an appropriate policy, so that CloudTrail has permission to publish to that topic. With the AWS CLI, you can [create](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/create-trail.html) or [update](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/update-trail.html) a trail to use an Amazon SNS topic by specifying a value for the `--sns-topic-name` parameter. You can specify the name or the ARN for the Amazon SNS topic. When you create an SNS topic name, the name must meet the following requirements: + Between 1 and 256 characters long + Contain uppercase and lowercase ASCII letters, numbers, underscores, or hyphens When you configure notifications for a multi-Region trail, notifications from all Regions are sent to the Amazon SNS topic that you specify. If you have one or more Region-specific trails, you must create a separate topic for each Region and subscribe to each individually. To receive notifications, subscribe to the Amazon SNS topic or topics that CloudTrail uses. You do this with the Amazon SNS console or Amazon SNS CLI commands. For more information, see [Subscribing to an Amazon SNS topic](https://docs.aws.amazon.com/sns/latest/dg/sns-create-subscribe-endpoint-to-topic.html) in the *Amazon Simple Notification Service Developer Guide*. **Note** CloudTrail sends a notification when log files are written to the Amazon S3 bucket. An active account can generate a large number of notifications. If you subscribe with email or SMS, you can receive a large volume of messages. We recommend that you subscribe using Amazon Simple Queue Service (Amazon SQS), which lets you handle notifications programmatically. For more information, see [Subscribing an Amazon SQS queue to an Amazon SNS topic (console)](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-configure-subscribe-queue-sns-topic.html) in the *Amazon Simple Queue Service Developer Guide*. The Amazon SNS notification consists of a JSON object that includes a `Message` field. The `Message` field lists the full path to the log file, as shown in the following example: ``` { "s3Bucket": "amzn-s3-demo-bucket","s3ObjectKey": ["AWSLogs/123456789012/CloudTrail/us-east-2/2013/12/13/123456789012_CloudTrail_us-west-2_20131213T1920Z_LnPgDQnpkSKEsppV.json.gz"] } ``` If multiple log files are delivered to your Amazon S3 bucket, a notification may contain multiple logs, as shown in the following example: ``` { "s3Bucket": "amzn-s3-demo-bucket", "s3ObjectKey": [ "AWSLogs/123456789012/CloudTrail/us-east-2/2016/08/11/123456789012_CloudTrail_us-east-2_20160811T2215Z_kpaMYavMQA9Ahp7L.json.gz", "AWSLogs/123456789012/CloudTrail/us-east-2/2016/08/11/123456789012_CloudTrail_us-east-2_20160811T2210Z_zqDkyQv3TK8ZdLr0.json.gz", "AWSLogs/123456789012/CloudTrail/us-east-2/2016/08/11/123456789012_CloudTrail_us-east-2_20160811T2205Z_jaMVRa6JfdLCJYHP.json.gz" ] } ``` If you choose to receive notifications by email, the body of the email consists of the content of the `Message` field. For information about the JSON structure, see [Fanout to Amazon SQS queues](https://docs.aws.amazon.com/sns/latest/dg/sns-sqs-as-subscriber.html) in the *Amazon Simple Notification Service Developer Guide*. Only the `Message` field shows CloudTrail information. The other fields contain information from the Amazon SNS service. If you create a trail with the CloudTrail API, you can specify an existing Amazon SNS topic that you want CloudTrail to send notifications to with the [https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_CreateTrail.html](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_CreateTrail.html) or [https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_UpdateTrail.html](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_UpdateTrail.html) operations. You must make sure that the topic exists and that it has permissions that allow CloudTrail to send notifications to it. See [Amazon SNS topic policy for CloudTrail](cloudtrail-permissions-for-sns-notifications.md). ### Additional resources For more information about Amazon SNS topics and about subscribing to them, see the [https://docs.aws.amazon.com/sns/latest/dg/](https://docs.aws.amazon.com/sns/latest/dg/). # Using AWS CloudTrail with interface VPC endpoints If you use Amazon Virtual Private Cloud (Amazon VPC) to host your AWS resources, you can establish a private connection between your VPC and AWS CloudTrail. You can use this connection to enable CloudTrail to communicate with your resources on your VPC without going through the public internet. Amazon VPC is an AWS service that you can use to launch AWS resources in a virtual network that you define. With a VPC, you have control over your network settings, such the IP address range, subnets, route tables, and network gateways. With VPC endpoints, the routing between the VPC and AWS services is handled by the AWS network, and you can use IAM policies to control access to service resources. To connect your VPC to CloudTrail, you define an *interface VPC endpoint* for CloudTrail. An interface endpoint is an elastic network interface with a private IP address that serves as an entry point for traffic destined to a supported AWS service. The endpoint provides reliable, scalable connectivity to CloudTrail without requiring an internet gateway, network address translation (NAT) instance, or VPN connection. For more information, see [What is Amazon VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) in the *Amazon VPC User Guide*. Interface VPC endpoints are powered by AWS PrivateLink, an AWS technology that enables private communication between AWS services using an elastic network interface with private IP addresses. For more information, see [AWS PrivateLink](https://aws.amazon.com/privatelink/). The following sections are for users of Amazon VPC. For more information, see [Get started with Amazon VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-getting-started.html) in the *Amazon VPC User Guide*. **Topics** + [ ## Regions ](#cloudtrail-interface-VPC-availability) + [ ## Create a VPC endpoint for CloudTrail ](#create-VPC-endpoint-for-CloudTrail) + [ ## Create a VPC endpoint policy for CloudTrail ](#create-VPC-endpoint-policy) + [ ## Shared subnets ](#shared-subnet-cloudtrail) ## Regions AWS CloudTrail supports VPC endpoints and VPC endpoint policies in all AWS Regions in which CloudTrail is supported. ## Create a VPC endpoint for CloudTrail To start using CloudTrail with your VPC, create an interface VPC endpoint for CloudTrail. For more information, see [Access an AWS service using an interface VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint.html) in the *Amazon VPC User Guide*. You don't need to change the settings for CloudTrail. CloudTrail calls other AWS services using either public endpoints or private interface VPC endpoints, whichever are in use. ## Create a VPC endpoint policy for CloudTrail A VPC endpoint policy is an IAM resource that you can attach to an interface VPC endpoint. The default endpoint policy gives you full access to CloudTrail APIs through the interface VPC endpoint. To control the access granted to CloudTrail from your VPC, attach a custom endpoint policy to the interface VPC endpoint. An endpoint policy specifies the following information: + The principals that can perform actions (AWS accounts, IAM users, and IAM roles). + The actions that can be performed. + The resources on which actions can be performed. For more information about VPC endpoint policies, including how to update a policy, see [Controlling access to services with VPC endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html) in the *Amazon VPC User Guide*. Following are examples of custom VPC endpoint policies for CloudTrail. **Topics** + [ ### Example: Allow all CloudTrail actions ](#create-VPC-endpoint-policy-example1) + [ ### Example: Allow specific CloudTrail actions ](#create-VPC-endpoint-policy-example2) + [ ### Example: Deny all CloudTrail actions ](#create-VPC-endpoint-policy-example3) + [ ### Example: Deny specific CloudTrail actions ](#create-VPC-endpoint-policy-example4) + [ ### Example: Allow all CloudTrail actions from a specific VPC ](#create-VPC-endpoint-policy-example5) + [ ### Example: Allow all CloudTrail actions from a specific VPC endpoint ](#create-VPC-endpoint-policy-example6) ### Example: Allow all CloudTrail actions The following example VPC endpoint policy grants access to all CloudTrail actions for all principals on all resources. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "cloudtrail:*", "Effect": "Allow", "Resource": "*", "Principal": "*" } ] } ``` ------ ### Example: Allow specific CloudTrail actions The following example VPC endpoint policy grants access to perform the `cloudtrail:ListTrails` and `cloudtrail:ListEventDataStores` actions for all principals on all resources. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": ["cloudtrail:ListTrails", "cloudtrail:ListEventDataStores"], "Effect": "Allow", "Principal": "*", "Resource": "*" } ] } ``` ------ ### Example: Deny all CloudTrail actions The following example VPC endpoint policy denies access to all CloudTrail actions for all principals on all resources. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "cloudtrail:*", "Effect": "Deny", "Principal": "*", "Resource": "*" } ] } ``` ------ ### Example: Deny specific CloudTrail actions The following example VPC endpoint policy denies the `cloudtrail:CreateTrail` and `cloudtrail:CreateEventDataStore` actions for all principals on all resources. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": ["cloudtrail:CreateTrail", "cloudtrail:CreateEventDataStore"], "Effect": "Deny", "Principal": "*", "Resource": "*" } ] } ``` ------ ### Example: Allow all CloudTrail actions from a specific VPC The following example VPC endpoint policy grants access to perform all CloudTrail actions for all principals on all resources but only if the requester uses the specified VPC to make the request. Replace *vpc-id* with your VPC ID. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "cloudtrail:*", "Resource": "*", "Principal": "*", "Condition": { "StringEquals": { "aws:SourceVpc": "vpc-1234567890abcdef0" } } } ] } ``` ------ ### Example: Allow all CloudTrail actions from a specific VPC endpoint The following example VPC endpoint policy grants access to perform all CloudTrail actions for all principals on all resources but only if the requester uses the specified VPC endpoint to make the request. Replace *vpc-endpoint-id* with your VPC endpoint ID. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "cloudtrail:*", "Resource": "*", "Condition": { "StringEquals": { "aws:SourceVpce": "vpce-1a2b3c4d" } } } ] } ``` ------ ## Shared subnets A CloudTrail VPC endpoint, like any other VPC endpoint, can only be created by an owner account in the shared subnet. However, a participant account can use CloudTrail VPC endpoints in subnets that are shared with the participant account. For more information about Amazon VPC sharing, see [Share your VPC with other accounts](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-sharing.html) in the *Amazon VPC User Guide*. # Naming requirements for CloudTrail resources, S3 buckets, and KMS keys This section provides information about the naming requirements for CloudTrail resources, Amazon S3 buckets, and KMS keys. **Topics** + [ ## CloudTrail resource naming requirements ](#cloudtrail-resource-naming-requirements) + [ ## Amazon S3 bucket naming requirements ](#cloudtrail-s3-bucket-naming-requirements) + [ ## AWS KMS alias naming requirements ](#KMS-key-naming-requirements) ## CloudTrail resource naming requirements CloudTrail resource names must meet the following requirements: + Contain only ASCII letters (a-z, A-Z), numbers (0-9), periods (.), underscores (\$1), or dashes (-). + Start with a letter or number, and end with a letter or number. + Be between 3 and 128 characters. + Have no adjacent periods, underscores or dashes. Names like my-\$1namespace and my-\$1-namespace are invalid. + Not be in IP address format (for example, `192.168.5.4`). ## Amazon S3 bucket naming requirements The Amazon S3 bucket that you use to store CloudTrail log files must have a name that conforms with naming requirements for non-US Standard regions. Amazon S3 defines a bucket name as a series of one or more labels, separated by periods. For a complete list of naming rules, see [Bucket naming rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html) in the *Amazon Simple Storage Service User Guide*. The following are some of the rules: + The bucket name can be between 3 and 63 characters long, and can contain only lower-case characters, numbers, periods, and dashes. + Each label in the bucket name must start with a lowercase letter or number. + The bucket name cannot contain underscores, end with a dash, have consecutive periods, or use dashes adjacent to periods. + The bucket name cannot be formatted as an IP address (198.51.100.24). **Warning** Because S3 allows your bucket to be used as a URL that can be accessed publicly, the bucket name that you choose must be globally unique. If some other account has already created a bucket with the name that you chose, you must use another name. For more information, see [Bucket restrictions and limitations](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html) in the *Amazon Simple Storage Service User Guide*. ## AWS KMS alias naming requirements When you create an AWS KMS key, you can choose an alias to identify it. For example, you might choose the alias "KMS-CloudTrail-us-west-2" to encrypt the logs for a specific trail. The alias must meet the following requirements: + Between 1 and 256 characters, inclusive + Contain alphanumeric characters (A-Z, a-z, 0-9), hyphens (-), forward slashes (/), and underscores (\$1) + Cannot begin with **aws** For more information, see [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service Developer Guide*. # AWS account closure and trails AWS CloudTrail continuously monitors and records events for account activity generated by any user, role, or AWS service for an AWS account. Users can create a CloudTrail trail to receive a copy of these events in a S3 bucket that they own. CloudTrail is a foundational security service, therefore, trails created by users continue to exist and deliver events even after an AWS account is closed, unless a user explicitly deletes the trails in their AWS account prior to closing it. This ensures that if a user reopens a closed account that user has an unbroken record of account activity. It also provides users with visibility into any final account activity, including the deletion and termination of remaining account resources and services. Before you close your AWS account, consider the following: + Trails continue to exist even after the post-closure period has passed. The post-closure period refers to the 90 days between when you close your account and when AWS permanently closes your AWS account. + This behavior also applies to the organization trails that are created by the management account or the delegated administrator, and to multi-Region organization trails that are created in the organization's member accounts. + For trails that deliver events to an S3 bucket in the same account, trails continue to exist even after the account is closed. However, since the S3 bucket is deleted when the account is closed, trails do not continue to deliver events. + For trails that deliver events to an S3 bucket in a different account, trails continue to exist even after the account is closed. Trails also continue to deliver events to the S3 bucket if events can be delivered. For example, organization trails continue to deliver events to the S3 bucket if you close a member account in an organization, but you do not close the management account. + For trails encrypted with AWS KMS keys, trails continue to exist after the account is closed in addition to the KMS keys. Users have the option to delete trails prior to closing their AWS account, or to contact [AWS Support](https://console.aws.amazon.com/support/home) to request trail deletion after their AWS account has been closed. For information about closing an AWS account, see [Close an AWS account](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-closing.html) in the *AWS Account Management Reference Guide*. **Note** If CloudTrail log file validation is enabled, users will continue to receive hourly digest files which indicate if any CloudTrail logs were created or not. CloudTrail Lake event data stores, CloudTrail Lake channels for integrations, CloudTrail service-linked channels, and resources created for trails (for example, Amazon CloudWatch Logs log groups and Amazon S3 buckets existing in the closed account), follow standard AWS behavior for account closure and are permanently deleted after the post-closure period (typically 90 days).