Creating, updating, and managing trails with the Amazon Command Line Interface - Amazon CloudTrail
Commonly used commands for trail creation, management, and status
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Creating, updating, and managing trails with the Amazon Command Line Interface

You can use the Amazon CLI to create, update, and manage your trails. When using the Amazon CLI, remember that your commands run in the Amazon 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 Amazon command line tools to run the Amazon Command Line Interface (Amazon CLI) commands in this topic. Make sure you have a recent version of the Amazon CLI installed. For more information, see the Amazon Command Line Interface User Guide. For help with CloudTrail commands at the Amazon 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 to create a trail.

  • update-trail to change the configuration of an existing trail.

  • add-tags to add one or more tags (key-value pairs) to an existing trail.

  • remove-tags to remove one or more tags from a trail.

  • list-tags to return a list of tags associated with a trail.

  • put-event-selectors to add or modify event selectors for a trail.

  • put-insight-selectors to add or modify Insights event selectors for an existing trail, and enable or disable Insights events.

  • start-logging to begin logging events with your trail.

  • stop-logging to pause logging events with your trail.

  • delete-trail 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 to return information about trails in an Amazon Region.

  • get-trail to return settings information for a trail.

  • get-trail-status to return information about the current status of a trail.

  • get-event-selectors to return information about event selectors configured for a trail.

  • get-insight-selectors 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 Amazon Regions.

  • Creating a trail that receives logs for all Amazon 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 Amazon 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 CloudTrail log file encryption with the Amazon CLI.

  • 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.

  • 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.

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.