Configuration and credential file settings in the AWS CLI
You can save your frequently used configuration settings and credentials in files that are maintained by the AWS CLI.
The files are divided into profiles
. By default, the AWS CLI uses the settings
found in the profile named default
. To use alternate settings, you can create
and reference additional profiles.
You can override an individual setting by either setting one of the supported environment variables, or by using a command line parameter. For more information on configuration setting precedence, see Configuring settings for the AWS CLI.
Note
For information on setting up your credentials, see Authentication and access credentials for the AWS CLI.
Topics
Format of the configuration and credential files
The config
and credentials
files are organized into
sections. Sections include profiles,
sso-sessions, and services. A section is a named collection of settings, and
continues until another section definition line is encountered. Multiple profiles and
sections can be stored in the config
and
credentials
files.
These files are plaintext files that use the following format:
-
Section names are enclosed in brackets [ ] such as
[default]
,[profile
, anduser1
][sso-session]
. -
All entries in a section take the general form of
setting_name=value
. -
Lines can be commented out by starting the line with a hash character (
#
).
The config and credentials files contain the following section types:
Section type:
profile
The AWS CLI stores
Depending on the file, profile section names use the following format:
-
Config file:
[default]
[profile
user1
] -
Credentials file:
[default]
[
user1
]Do not use the word
profile
when creating an entry in thecredentials
file.
Each profile can specify different credentials and can also specify different
AWS Regions and output formats. When naming the profile in a
config
file, include the prefix word
"profile
", but do not include it in the
credentials
file.
The following examples show a credentials
and
config
file with two profiles, region, and output specified. The
first [default] is used when you run a AWS CLI
command with no profile specified. The second is used when you run a AWS CLI command
with the --profile user1
parameter.
For more information and additional authorization and credential methods see, see Authenticating using IAM user credentials for the AWS CLI.
Section
type: sso-session
The sso-session
section of the config
file is
used to group configuration variables for acquiring SSO access tokens, which can
then be used to acquire AWS credentials. The following settings are used:
-
(Required)
sso_start_url
-
(Required)
sso_region
You define an sso-session
section and associate it to a profile.
sso_region
and sso_start_url
must be set within the
sso-session
section. Typically, sso_account_id
and
sso_role_name
must be set in the profile
section so
that the SDK can request SSO credentials.
The following example configures the SDK to request SSO credentials and supports automated token refresh:
[profile
dev
] sso_session =my-sso
sso_account_id =111122223333
sso_role_name =SampleRole
[sso-sessionmy-sso
] sso_region =us-east-1
sso_start_url =https://my-sso-portal.awsapps.com/start
This also allows sso-session
configurations to be reused across
multiple profiles:
[profile
dev
] sso_session =my-sso
sso_account_id =111122223333
sso_role_name =SampleRole
[profileprod
] sso_session =my-sso
sso_account_id =111122223333
sso_role_name =SampleRole2
[sso-sessionmy-sso
] sso_region =us-east-1
sso_start_url =https://my-sso-portal.awsapps.com/start
However, sso_account_id
and sso_role_name
aren't
required for all scenarios of SSO token configuration. If your application only uses
AWS services that support bearer authentication, then traditional AWS
credentials are not needed. Bearer authentication is an HTTP authentication scheme
that uses security tokens called bearer tokens. In this scenario,
sso_account_id
and sso_role_name
aren't required. See
the individual guide for your AWS service to determine if it supports bearer token
authorization.
Additionally, registration scopes can be configured as part of a
sso-session
. Scope is a mechanism in OAuth 2.0 to limit an
application's access to a user's account. An application can request one or more
scopes, and the access token issued to the application will be limited to the scopes
granted. These scopes define the permissions requested to be authorized for the
registered OIDC client and access tokens retrieved by the client. The following
example sets sso_registration_scopes
to provide access for listing
accounts/roles:
[sso-session
my-sso
] sso_region =us-east-1
sso_start_url =https://my-sso-portal.awsapps.com/start
sso_registration_scopes =sso:account:access
The authentication token is cached to disk under the
~/.aws/sso/cache
directory with a filename based on the
session name.
For more information on this configuration type, see Configuring IAM Identity Center authentication with the AWS CLI.
Section type:
services
The services
section is a group of settings that configures custom
endpoints for AWS service requests. A profile then is linked to a
services
section.
[profile
dev
] services =my-services
The services
section is separated into subsections by
<SERVICE> =
lines, where <SERVICE>
is the
AWS service identifier key. The AWS service identifier is based on the API
model’s serviceId
by replacing all spaces with underscores and
lowercasing all letters. For a list of all service identifier keys to use in the
services
section, see Using endpoints in the AWS CLI.
The service identifier key is followed by nested settings with each on its own line
and indented by two spaces.
The following example configures the endpoint to use for requests made to the
Amazon DynamoDB service in the my-services
section that is used in the dev
profile. Any immediately
following lines that are indented are included in that subsection and apply to that
service.
[profile
dev
] services =my-services
[servicesmy-services
] dynamodb = endpoint_url =http://localhost:8000
For more information on service-specific endpoints, see Using endpoints in the AWS CLI.
If your profile has role-based credentials configured through a
source_profile
parameter for IAM assume role functionality, the
SDK only uses service configurations for the specified profile. It does not use
profiles that are role chained to it. For example, using the following
shared config
file:
[profile
A
] credential_source =Ec2InstanceMetadata
endpoint_url =https://profile-a-endpoint.aws/
[profileB
] source_profile =A
role_arn =arn:aws:iam::123456789012:role/roleB
services =profileB
[servicesprofileB
] ec2 = endpoint_url =https://profile-b-ec2-endpoint.aws
If you use profile B
and make a call in your code to Amazon EC2, the
endpoint resolves as https://profile-b-ec2-endpoint.aws
. If your code
makes a request to any other service, the endpoint resolution will not follow any
custom logic. The endpoint does not resolve to the global endpoint defined in
profile A
. For a global endpoint to take effect for profile
B
, you would need to set endpoint_url
directly within
profile B
.
Where are configuration settings stored?
The AWS CLI stores sensitive credential information that you specify with aws
configure
in a local file named credentials
, in a folder
named
in your home directory. The less sensitive
configuration options that you specify with .aws
aws configure
are stored in a
local file named config
, also stored in the
folder in your home directory. .aws
Storing credentials in the config file
You can keep all of your profile settings in a single file as the AWS CLI can read
credentials from the config
file. If there are credentials in
both files for a profile sharing the same name, the keys in the credentials file
take precedence. We suggest keeping credentials in the credentials
files. These files are also used by the various language software development kits
(SDKs). If you use one of the SDKs in addition to the AWS CLI, confirm if the
credentials should be stored in their own file.
Where you find your home directory location varies based on the operating system, but
is referred to using the environment variables %UserProfile%
in Windows and
$HOME
or ~
(tilde) in Unix-based systems. You can specify
a non-default location for the files by setting the AWS_CONFIG_FILE
and
AWS_SHARED_CREDENTIALS_FILE
environment variables to another local
path. See Configuring environment variables for the
AWS CLI
for details.
When you use a shared profile that specifies an AWS Identity and Access Management (IAM) role, the
AWS CLI calls the AWS STS AssumeRole
operation to retrieve temporary
credentials. These credentials are then stored (in
). Subsequent AWS CLI commands
use the cached temporary credentials until they expire, and at that point the AWS CLI
automatically refreshes the credentials.~/.aws/cli/cache
Using named profiles
If no profile is explicitly defined, the default
profile is used.
To use a named profile, add the --profile
option to your command. The
following example lists all of your Amazon EC2 instances using the credentials and settings
defined in the profile-name
user1
profile.
$
aws ec2 describe-instances --profile user1
To use a named profile for multiple commands, you can avoid specifying the profile in
every command by setting the AWS_PROFILE
environment variable as the
default profile. You can override this setting by using the --profile
parameter.
Set and view configuration settings using commands
There are several ways to view and set your configuration settings using commands.
aws configure
-
Run this command to quickly set and view your credentials, Region, and output format. The following example shows sample values.
$
aws configure
AWS Access Key ID [None]:
AWS Secret Access Key [None]:AKIAIOSFODNN7EXAMPLE
Default region name [None]:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default output format [None]:us-west-2
json
aws configure set
-
You can set any credentials or configuration settings using
aws configure set
. Specify the profile that you want to view or modify with the--profile
setting.For example, the following command sets the
region
in the profile namedinteg
.$
aws configure set region
us-west-2
--profileinteg
To remove a setting, manually delete the setting in your
config
andcredentials
files in a text editor. aws configure get
-
You can retrieve any credentials or configuration settings you've set using
aws configure get
. Specify the profile that you want to view or modify with the--profile
setting.For example, the following command retrieves the
region
setting in the profile namedinteg
.$
aws configure get
region
--profileinteg
us-west-2
If the output is empty, the setting is not explicitly set and uses the default value.
aws configure import
-
Import
CSV
credentials generated from the IAM web console. This is not for credentials generated from IAM Identity Center; customers who use IAM Identity Center should use aws configure sso. A CSV file is imported with the profile name matching the username. The CSV file must contain the following headers.-
User Name
-
Access key ID
-
Secret access key
Note
During initial key pair creation, once you close the Download .csv file dialog box, you cannot access your secret access key after you close the dialog box. If you need a
.csv
file, you'll need to create one yourself with the required headers and your stored key pair information. If you do not have access to your key pair information, you need to create a new key pair.$
aws configure import --csv
file://credentials.csv
-
aws configure list
-
To list configuration data, use the
aws configure list
command. This command lists the profile, access key, secret key, and region configuration information used for the specified profile. For each configuration item, it shows the value, where the configuration value was retrieved, and the configuration variable name.For example, if you provide the AWS Region in an environment variable, this command shows you the name of the region you've configured, that this value came from an environment variable, and the name of the environment variable.
For temporary credential methods such as roles and IAM Identity Center, this command displays the temporarily cached access key and secret access key is displayed.
$
aws configure list
Name Value Type Location ---- ----- ---- -------- profile <not set> None None access_key ****************ABCD shared-credentials-file secret_key ****************ABCD shared-credentials-file region us-west-2 env AWS_DEFAULT_REGION
aws configure list-profiles
-
To list all your profile names, use the
aws configure list-profiles
command.$
aws configure list-profiles
default test
aws configure sso
-
Run this command to quickly set and view your AWS IAM Identity Center credentials, Region, and output format. The following example shows sample values.
$
aws configure sso
SSO session name (Recommended):
my-sso
SSO start URL [None]:
https://my-sso-portal.awsapps.com/start
SSO region [None]:
us-east-1
SSO registration scopes [None]:
sso:account:access
aws configure sso-session
-
Run this command to quickly set and view your AWS IAM Identity Center credentials, Region, and output format in the sso-session section of the
credentials
andconfig
files. The following example shows sample values.$
aws configure sso-session
SSO session name:
my-sso
SSO start URL [None]:
https://my-sso-portal.awsapps.com/start
SSO region [None]:
us-east-1
SSO registration scopes [None]:
sso:account:access
Setting new configuration and credentials command examples
The following examples show configuring a default profile with credentials, region, and output specified for different authentication methods.
Supported config
file settings
The following settings are supported in the config
file. The
values listed in the specified (or default) profile are used unless they are overridden
by the presence of an environment variable with the same name, or a command line option
with the same name. For more information on what order settings take precendence, see
Configuring settings for the AWS CLI
Global settings
-
aws_access_key_id
-
Specifies the AWS access key used as part of the credentials to authenticate the command request. Although this can be stored in the
config
file, we recommend that you store this in thecredentials
file.Can be overridden by the
AWS_ACCESS_KEY_ID
environment variable. You can't specify the access key ID as a command line option.aws_access_key_id =
AKIAIOSFODNN7EXAMPLE
aws_secret_access_key
-
Specifies the AWS secret key used as part of the credentials to authenticate the command request. Although this can be stored in the
config
file, we recommend that you store this in thecredentials
file.Can be overridden by the
AWS_SECRET_ACCESS_KEY
environment variable. You can't specify the secret access key as a command line option.aws_secret_access_key =
wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token
-
Specifies an AWS session token. A session token is required only if you manually specify temporary security credentials. Although this can be stored in the
config
file, we recommend that you store this in thecredentials
file.Can be overridden by the
AWS_SESSION_TOKEN
environment variable. You can't specify the session token as a command line option.aws_session_token =
AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4Olgk
ca_bundle
-
Specifies a CA certificate bundle (a file with the
.pem
extension) that is used to verify SSL certificates.Can be overridden by the
AWS_CA_BUNDLE
environment variable or the--ca-bundle
command line option.ca_bundle =
dev/apps/ca-certs/cabundle-2019mar05.pem
cli_auto_prompt
-
Enables the auto-prompt for the AWS CLI version 2. There are two settings that can be used:
-
on
uses the full auto-prompt mode each time you attempt to run anaws
command. This includes pressing ENTER after both a complete command or incomplete command.cli_auto_prompt = on
-
on-partial
uses partial auto-prompt mode. If a command is incomplete or cannot be run due to client-side validation errors, auto-prompt is used. This mode is particular useful if you have pre-existing scripts, runbooks, or you only want to be auto-prompted for commands you are unfamiliar with rather than prompted on every command.cli_auto_prompt = on-partial
You can override this setting by using the
aws_cli_auto_prompt
environment variable or the--cli-auto-prompt
and--no-cli-auto-prompt
command line parameters.For information on the AWS CLI version 2 auto-prompt feature, see Enabling and using command prompts in the AWS CLI.
-
cli_binary_format
-
Specifies how the AWS CLI version 2 interprets binary input parameters. It can be one of the following values:
-
base64 – This is the default value. An input parameter that is typed as a binary large object (BLOB) accepts a base64-encoded string. To pass true binary content, put the content in a file and provide the file's path and name with the
fileb://
prefix as the parameter's value. To pass base64-encoded text contained in a file, provide the file's path and name with thefile://
prefix as the parameter's value. -
raw-in-base64-out – Default for the AWS CLI version 1. If the setting's value is
raw-in-base64-out
, files referenced using thefile://
prefix is read as text and then the AWS CLI attempts to encode it to binary.
This entry does not have an equivalent environment variable. You can specify the value on a single command by using the
--cli-binary-format raw-in-base64-out
parameter.cli_binary_format = raw-in-base64-out
If you reference a binary value in a file using the
fileb://
prefix notation, the AWS CLI always expects the file to contain raw binary content and does not attempt to convert the value.If you reference a binary value in a file using the
file://
prefix notation, the AWS CLI handles the file according to the currentcli_binary_format
setting. If that setting's value isbase64
(the default when not explicitly set), the AWS CLI expects the file to contain base64-encoded text. If that setting's value israw-in-base64-out
, the AWS CLI expects the file to contain raw binary content. -
cli_history
-
Disabled by default. This setting enables command history for the AWS CLI. After enabling this setting, the AWS CLI records the history of
aws
commands.cli_history = enabled
You can list your history using the
aws history list
command, and use the resultingcommand_ids
in theaws history show
command for details. For more information seeaws history
in the AWS CLI reference guide. cli_pager
-
Specifies the pager program used for output. By default, AWS CLI version 2 returns all output through your operating system’s default pager program.
Can be overridden by the AWS_PAGER environment variable.
cli_pager=less
cli_timestamp_format
-
Specifies the format of timestamp values included in the output. You can specify either of the following values:
-
iso8601 – The default value for the AWS CLI version 2. If specified, the AWS CLI reformats all timestamps according to ISO 8601
. ISO 8601 formatted timestamps look like the following examples. The first example shows the time in Coordinated Universal Time (UTC)
by including a Z
after the time. The date and the time are separated by aT
.2019-10-31T22:21:41Z
To specify a different time zone, instead of the
Z
, specify a+
or-
and the number of hours the desired time zone is ahead of or behind UTC, as a two-digit value. The following example shows the same time as the previous example but adjusted to Pacific Standard time, which is eight hours behind UTC.2019-10-31T14:21:41-08
-
wire – The default value for the AWS CLI version 1. If specified, the AWS CLI displays all timestamp values exactly as received in the HTTP query response.
This entry does not have an equivalent environment variable or command line option.
cli_timestamp_format = iso8601
-
credential_process
-
Specifies an external command that the AWS CLI runs to generate or retrieve authentication credentials to use for this command. The command must return the credentials in a specific format. For more information about how to use this setting, see Sourcing credentials with an external process in the AWS CLI.
This entry does not have an equivalent environment variable or command line option.
credential_process =
/opt/bin/awscreds-retriever --username susan
credential_source
-
Used within Amazon EC2 instances or containers to specify where the AWS CLI can find credentials to use to assume the role you specified with the
role_arn
parameter. You cannot specify bothsource_profile
andcredential_source
in the same profile.This parameter can have one of three values:
-
Environment – Specifies that the AWS CLI is to retrieve source credentials from environment variables.
-
Ec2InstanceMetadata – Specifies that the AWS CLI is to use the IAM role attached to the EC2 instance profile to get source credentials.
-
EcsContainer – Specifies that the AWS CLI is to use the IAM role attached to the ECS container as source credentials.
credential_source = Ec2InstanceMetadata
-
duration_seconds
-
Specifies the maximum duration of the role session, in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role (which can be a maximum of 43200). This is an optional parameter and by default, the value is set to 3600 seconds.
endpoint_url
-
Specifies the endpoint that is used for all service requests. If this setting is used in the services section of the
config
file, then the endpoint is used only for the specified service.The following example uses the global endpoint
http://localhost:1234
and a service-specific endpoint ofhttp://localhost:4567
for Amazon S3.[profile dev] endpoint_url = http://localhost:1234 services = s3-specific [services s3-specific] s3 = endpoint_url = http://localhost:4567
Endpoint configuration settings are located in multiple places, such as the system or user environment variables, local AWS configuration files, or explicitly declared on the command line as a parameter. The AWS CLI endpoint configuration settings take precedence in the following order:
-
The
--endpoint-url
command line option. -
If enabled, the
AWS_IGNORE_CONFIGURED_ENDPOINT_URLS
global endpoint environment variable or profile settingignore_configure_endpoint_urls
to ignore custom endpoints. -
The value provided by a service-specific environment variable
AWS_ENDPOINT_URL_<SERVICE>
, such asAWS_ENDPOINT_URL_DYNAMODB
. -
The values provided by the
AWS_USE_DUALSTACK_ENDPOINT
,AWS_USE_FIPS_ENDPOINT
, andAWS_ENDPOINT_URL
environment variables. -
The service-specific endpoint value provided by the
endpoint_url
setting within aservices
section of the sharedconfig
file. -
The value provided by the
endpoint_url
setting within aprofile
of the sharedconfig
file. -
use_dualstack_endpoint
,use_fips_endpoint
, andendpoint_url
settings. -
Any default endpoint URL for the respective AWS service is used last. For a list of the standard service endpoints available in each Region, see AWS Regions and Endpoints in the Amazon Web Services General Reference.
-
ignore_configure_endpoint_urls
-
If enabled, the AWS CLI ignores all custom endpoint configurations specified in the
config
file. Valid values aretrue
andfalse
.ignore_configure_endpoint_urls = true
Endpoint configuration settings are located in multiple places, such as the system or user environment variables, local AWS configuration files, or explicitly declared on the command line as a parameter. The AWS CLI endpoint configuration settings take precedence in the following order:
-
The
--endpoint-url
command line option. -
If enabled, the
AWS_IGNORE_CONFIGURED_ENDPOINT_URLS
global endpoint environment variable or profile settingignore_configure_endpoint_urls
to ignore custom endpoints. -
The value provided by a service-specific environment variable
AWS_ENDPOINT_URL_<SERVICE>
, such asAWS_ENDPOINT_URL_DYNAMODB
. -
The values provided by the
AWS_USE_DUALSTACK_ENDPOINT
,AWS_USE_FIPS_ENDPOINT
, andAWS_ENDPOINT_URL
environment variables. -
The service-specific endpoint value provided by the
endpoint_url
setting within aservices
section of the sharedconfig
file. -
The value provided by the
endpoint_url
setting within aprofile
of the sharedconfig
file. -
use_dualstack_endpoint
,use_fips_endpoint
, andendpoint_url
settings. -
Any default endpoint URL for the respective AWS service is used last. For a list of the standard service endpoints available in each Region, see AWS Regions and Endpoints in the Amazon Web Services General Reference.
-
external_id
-
Specifies a unique identifier that is used by third parties to assume a role in their customers' accounts. This maps to the
ExternalId
parameter in theAssumeRole
operation. This parameter is needed only if the trust policy for the role specifies a value forExternalId
. For more information, see How to use an external ID when granting access to your AWS resources to a third party in the IAM User Guide. max_attempts
-
Specifies a value of maximum retry attempts the AWS CLI retry handler uses, where the initial call counts toward the
max_attempts
value that you provide.You can override this value by using the
AWS_MAX_ATTEMPTS
environment variable.max_attempts =
3
mfa_serial
-
The identification number of an MFA device to use when assuming a role. This is mandatory only if the trust policy of the role being assumed includes a condition that requires MFA authentication. The value can be either a serial number for a hardware device (such as
GAHT12345678
) or an Amazon Resource Name (ARN) for a virtual MFA device (such asarn:aws:iam::123456789012:mfa/
).user
output
-
Specifies the default output format for commands requested using this profile. You can specify any of the following values:
-
yaml-stream – The output is streamed and formatted as a YAML
string. Streaming allows for faster handling of large data types. -
text – The output is formatted as multiple lines of tab-separated string values. This can be useful to pass the output to a text processor, like
grep
,sed
, orawk
. -
table – The output is formatted as a table using the characters +|- to form the cell borders. It typically presents the information in a "human-friendly" format that is much easier to read than the others, but not as programmatically useful.
Can be overridden by the
AWS_DEFAULT_OUTPUT
environment variable or the--output
command line option.output =
table
parameter_validation
-
Specifies whether the AWS CLI client attempts to validate parameters before sending them to the AWS service endpoint.
-
true – This is the default value. If specified, the AWS CLI performs local validation of command line parameters.
-
false – If specified, the AWS CLI does not validate command line parameters before sending them to the AWS service endpoint.
This entry does not have an equivalent environment variable or command line option.
parameter_validation = false
-
region
-
Specifies the AWS Region to send requests to for commands requested using this profile.
-
You can specify any of the Region codes available for the chosen service as listed in AWS Regions and Endpoints in the Amazon Web Services General Reference.
-
aws_global
enables you to specify the global endpoint for services that support a global endpoint in addition to Regional endpoints, such as AWS Security Token Service (AWS STS) and Amazon Simple Storage Service (Amazon S3).
You can override this value by using the
AWS_REGION
environment variable,AWS_DEFAULT_REGION
environment variable, or the--region
command line option.region =
us-west-2
-
retry_mode
-
Specifies which retry mode AWS CLI uses. There are three retry modes available: legacy (default), standard, and adaptive. For more information on retries, see AWS CLI retries in the AWS CLI.
You can override this value by using the
AWS_RETRY_MODE
environment variable.retry_mode =
standard
role_arn
-
Specifies the Amazon Resource Name (ARN) of an IAM role that you want to use to run the AWS CLI commands. You must also specify one of the following parameters to identify the credentials that have permission to assume this role:
-
source_profile
-
credential_source
role_arn = arn:aws:iam::
123456789012
:role/role-name
The environment variable AWS_ROLE_ARN overrides this setting.
For more information on using web identities, see Assume role with web identity.
-
role_session_name
-
Specifies the name to attach to the role session. This value is provided to the
RoleSessionName
parameter when the AWS CLI calls theAssumeRole
operation, and becomes part of the assumed role user ARN:arn:aws:sts::
. This is an optional parameter. If you do not provide this value, a session name is generated automatically. This name appears in AWS CloudTrail logs for entries associated with this session.123456789012
:assumed-role/role_name
/role_session_name
role_session_name =
maria_garcia_role
The environment variable AWS_ROLE_SESSION_NAME overrides this setting.
For more information on using web identities, see Assume role with web identity.
services
-
Specifies the service configuration to use for your profile.
[profile
dev-s3-specific-and-global
] endpoint_url =http://localhost:1234
services =s3-specific
[servicess3-specific
] s3 = endpoint_url =http://localhost:4567
For more information on the
services
section, see Section type: services.The environment variable AWS_ROLE_SESSION_NAME overrides this setting.
For more information on using web identities, see Assume role with web identity.
sdk_ua_app_id
-
A single AWS account can be used by multiple customer applications to make calls to AWS services. Application ID identifies which source application made a set of calls using an AWS service. AWS SDKs and services don't use or interpret this value other than to surface it back in customer communications. For example, this value can be included in operational emails to uniquely identify which of your applications is associated with the notification.
The Application ID is a string with maximum length of 50 characters. Letters, numbers and the following special characters are allowed:
! $ % & * + - . , ^ _ ` | ~
By default, no value is assigned.sdk_ua_app_id =
prod1
This setting can be overwritten by using the AWS_SDK_UA_APP_ID environment variable. You can't set this value as a command line parameter.
source_profile
-
Specifies a named profile with long-term credentials that the AWS CLI can use to assume a role that you specified with the
role_arn
parameter. You cannot specify bothsource_profile
andcredential_source
in the same profile.source_profile =
production-profile
sso_account_id
-
Specifies the AWS account ID that contains the IAM role with the permission that you want to grant to the associated IAM Identity Center user.
This setting does not have an environment variable or command line option.
sso_account_id = 123456789012
sso_region
-
Specifies the AWS Region that contains the AWS access portal host. This is separate from, and can be a different Region than the default CLI
region
parameter.This setting does not have an environment variable or command line option.
sso_region = us_west-2
sso_registration_scopes
-
A comma-delimited list of scopes to be authorized for the
sso-session
. Scopes authorize access to IAM Identity Center bearer token authorized endpoints. A valid scope is a string, such assso:account:access
. This setting isn't applicable to the legacy non-refreshable configuration.sso_registration_scopes = sso:account:access
sso_role_name
-
Specifies the friendly name of the IAM role that defines the user's permissions when using this profile.
This setting does not have an environment variable or command line option.
sso_role_name = ReadAccess
sso_start_url
-
Specifies the URL that points to the organization's AWS access portal. The AWS CLI uses this URL to establish a session with the IAM Identity Center service to authenticate its users. To find your AWS access portal URL, use one of the following:
-
Open your invitation email, the AWS access portal URL is listed.
-
Open the AWS IAM Identity Center console at https://console.aws.amazon.com/singlesignon/
. The AWS access portal URL is listed in your settings.
This setting does not have an environment variable or command line option.
sso_start_url =
https://my-sso-portal.awsapps.com/start
-
use_dualstack_endpoint
-
Enables the use of dual-stack endpoints to send AWS requests. To learn more about dual-stack endpoints, which support both IPv4 and IPv6 traffic, see Using Amazon S3 dual-stack endpoints in the Amazon Simple Storage Service User Guide. Dual-stack endpoints are available for some services in some regions. If a dual-stack endpoint does not exist for the service or AWS Region, the request fails. This is disabled by default.
This is mutually exclusive with the
use_accelerate_endpoint
setting.Endpoint configuration settings are located in multiple places, such as the system or user environment variables, local AWS configuration files, or explicitly declared on the command line as a parameter. The AWS CLI endpoint configuration settings take precedence in the following order:
-
The
--endpoint-url
command line option. -
If enabled, the
AWS_IGNORE_CONFIGURED_ENDPOINT_URLS
global endpoint environment variable or profile settingignore_configure_endpoint_urls
to ignore custom endpoints. -
The value provided by a service-specific environment variable
AWS_ENDPOINT_URL_<SERVICE>
, such asAWS_ENDPOINT_URL_DYNAMODB
. -
The values provided by the
AWS_USE_DUALSTACK_ENDPOINT
,AWS_USE_FIPS_ENDPOINT
, andAWS_ENDPOINT_URL
environment variables. -
The service-specific endpoint value provided by the
endpoint_url
setting within aservices
section of the sharedconfig
file. -
The value provided by the
endpoint_url
setting within aprofile
of the sharedconfig
file. -
use_dualstack_endpoint
,use_fips_endpoint
, andendpoint_url
settings. -
Any default endpoint URL for the respective AWS service is used last. For a list of the standard service endpoints available in each Region, see AWS Regions and Endpoints in the Amazon Web Services General Reference.
-
use_fips_endpoint
-
Some AWS services offer endpoints that support Federal Information Processing Standard (FIPS) 140-2
in some AWS Regions. When the AWS service supports FIPS, this setting specifies what FIPS endpoint the AWS CLI should use . Unlike standard AWS endpoints, FIPS endpoints use a TLS software library that complies with FIPS 140-2. These endpoints might be required by enterprises that interact with the United States government. If this setting is enabled, but a FIPS endpoint does not exist for the service in your AWS Region, the AWS command may fail. In this case, manually specify the endpoint to use in the command using the
--endpoint-url
option or use service-specific endpoints.For more information on specifying FIPS endpoints by AWS Region, see FIPS Endpoints by Service
. Endpoint configuration settings are located in multiple places, such as the system or user environment variables, local AWS configuration files, or explicitly declared on the command line as a parameter. The AWS CLI endpoint configuration settings take precedence in the following order:
-
The
--endpoint-url
command line option. -
If enabled, the
AWS_IGNORE_CONFIGURED_ENDPOINT_URLS
global endpoint environment variable or profile settingignore_configure_endpoint_urls
to ignore custom endpoints. -
The value provided by a service-specific environment variable
AWS_ENDPOINT_URL_<SERVICE>
, such asAWS_ENDPOINT_URL_DYNAMODB
. -
The values provided by the
AWS_USE_DUALSTACK_ENDPOINT
,AWS_USE_FIPS_ENDPOINT
, andAWS_ENDPOINT_URL
environment variables. -
The service-specific endpoint value provided by the
endpoint_url
setting within aservices
section of the sharedconfig
file. -
The value provided by the
endpoint_url
setting within aprofile
of the sharedconfig
file. -
use_dualstack_endpoint
,use_fips_endpoint
, andendpoint_url
settings. -
Any default endpoint URL for the respective AWS service is used last. For a list of the standard service endpoints available in each Region, see AWS Regions and Endpoints in the Amazon Web Services General Reference.
-
web_identity_token_file
-
Specifies the path to a file that contains an OAuth 2.0 access token or OpenID Connect ID token that is provided by an identity provider. The AWS CLI loads the contents of this file and passes it as the
WebIdentityToken
argument to theAssumeRoleWithWebIdentity
operation.The environment variable
AWS_WEB_IDENTITY_TOKEN_FILE
overrides this setting.For more information on using web identities, see Assume role with web identity.
tcp_keepalive
-
Specifies whether the AWS CLI client uses TCP keep-alive packets.
This entry does not have an equivalent environment variable or command line option.
tcp_keepalive = false
S3 Custom command settings
Amazon S3 supports several settings that configure how the AWS CLI performs Amazon S3
operations. Some apply to all S3 commands in both the s3api
and
s3
namespaces. Others are specifically for the S3 "custom" commands
that abstract common operations and do more than a one-to-one mapping to an API
operation. The aws s3
transfer commands cp
,
sync
, mv
, and rm
have additional settings
you can use to control S3 transfers.
All of these options can be configured by specifying the s3
nested
setting in your config
file. Each setting is then indented on
its own line.
Note
These settings are entirely optional. You should be able to successfully use
the aws s3
transfer commands without configuring any of these
settings. These settings are provided to enable you to tune for performance or
to account for the specific environment where you are running these aws
s3
commands.
These settings are all set under a top-level s3
key in the
config
file, as shown in the following example for the
development
profile.
[profile development] s3 = max_concurrent_requests = 20 max_queue_size = 10000 multipart_threshold = 64MB multipart_chunksize = 16MB max_bandwidth = 50MB/s use_accelerate_endpoint = true addressing_style = path
The following settings apply to any S3 command in the s3
or
s3api
namespaces.
addressing_style
-
Specifies which addressing style to use. This controls whether the bucket name is in the hostname or is part of the URL. Valid values are:
path
,virtual
, andauto
. The default value isauto
.There are two styles of constructing an Amazon S3 endpoint. The first is called
virtual
and includes the bucket name as part of the hostname. For example:https://
. Alternatively, with thebucketname
.s3.amazonaws.compath
style, you treat the bucket name as if it is a path in the URI; for example,https://s3.amazonaws.com/
. The default value in the CLI is to usebucketname
auto
, which attempts to use thevirtual
style where it can, but will fall back topath
style when required. For example, if your bucket name is not DNS compatible, the bucket name cannot be part of the hostname and must be in the path. Withauto
, the CLI will detect this condition and automatically switch topath
style for you. If you set the addressing style topath
, you must then ensure that the AWS Region you configured in the AWS CLI matches the Region of your bucket. payload_signing_enabled
-
Specifies whether to SHA256 sign sigv4 payloads. By default, this is disabled for streaming uploads (
UploadPart
andPutObject
) when using HTTPS. By default, this is set tofalse
for streaming uploads (UploadPart
andPutObject
), but only if aContentMD5
is present (it is generated by default) and the endpoint uses HTTPS.If set to true, S3 requests receive additional content validation in the form of a SHA256 checksum which is calculated for you and included in the request signature. If set to false, the checksum isn't calculated. Disabling this can be useful to reduce the performance overhead created by the checksum calculation.
use_accelerate_endpoint
-
Use the Amazon S3 Accelerate endpoint for all
s3
ands3api
commands. The default value is false. This is mutually exclusive with theuse_dualstack_endpoint
setting.If set to true, the AWS CLI directs all Amazon S3 requests to the
S3 Accelerate
endpoint ats3-accelerate.amazonaws.com
. To use this endpoint, you must enable your bucket to useS3 Accelerate
. All requests are sent using the virtual style of bucket addressing:
. Anymy-bucket
.s3-accelerate.amazonaws.comListBuckets
,CreateBucket
, andDeleteBucket
requests aren't sent to the S3 Accelerate endpoint as that endpoint doesn't support those operations. This behavior can also be set if the--endpoint-url
parameter is set tohttps://s3-accelerate.amazonaws.com
orhttp://s3-accelerate.amazonaws.com
for anys3
ors3api
command.
The following settings apply only to commands in the s3
namespace
command set.
max_bandwidth
-
Specifies the maximum bandwidth that can be consumed for uploading and downloading data to and from Amazon S3. The default is no limit.
This limits the maximum bandwidth that the S3 commands can use to transfer data to and from Amazon S3. This value applies to only uploads and downloads; it doesn't apply to copies or deletes. The value is expressed as bytes per second. The value can be specified as:
-
An integer. For example,
1048576
sets the maximum bandwidth usage to 1 megabyte per second. -
An integer followed by a rate suffix. You can specify rate suffixes using:
KB/s
,MB/s
, orGB/s
. For example,300KB/s
,10MB/s
.
In general, we recommend that you first try to lower bandwidth consumption by lowering
max_concurrent_requests
. If that doesn't adequately limit bandwidth consumption to the desired rate, you can use themax_bandwidth
setting to further limit bandwidth consumption. This is becausemax_concurrent_requests
controls how many threads are currently running. If you instead first lowermax_bandwidth
but leave a highmax_concurrent_requests
setting, it can result in threads having to wait unnecessarily. This can lead to excess resource consumption and connection timeouts. -
max_concurrent_requests
-
Specifies the maximum number of concurrent requests. The default value is 10.
The
aws s3
transfer commands are multithreaded. At any given time, multiple Amazon S3 requests can be running. For example, when you use the commandaws s3 cp localdir s3://bucket/ --recursive
to upload files to an S3 bucket, the AWS CLI can upload the fileslocaldir/file1
,localdir/file2
, andlocaldir/file3
in parallel. The settingmax_concurrent_requests
specifies the maximum number of transfer operations that can run at the same time.You might need to change this value for a few reasons:
-
Decreasing this value – On some environments, the default of 10 concurrent requests can overwhelm a system. This can cause connection timeouts or slow the responsiveness of the system. Lowering this value makes the S3 transfer commands less resource intensive. The tradeoff is that S3 transfers can take longer to complete. Lowering this value might be necessary if you use a tool to limit bandwidth.
-
Increasing this value – In some scenarios, you might want the Amazon S3 transfers to complete as quickly as possible, using as much network bandwidth as necessary. In this scenario, the default number of concurrent requests might not be sufficient to use all of the available network bandwidth. Increasing this value can improve the time it takes to complete an Amazon S3 transfer.
-
max_queue_size
-
Specifies the maximum number of tasks in the task queue. The default value is 1000.
The AWS CLI internally uses a model where it queues up Amazon S3 tasks that are then executed by consumers whose numbers are limited by
max_concurrent_requests
. A task generally maps to a single Amazon S3 operation. For example, a task could be aPutObjectTask
, or aGetObjectTask
, or anUploadPartTask
. The rate at which tasks are added to the queue can be much faster than the rate at which consumers finish the tasks. To avoid unbounded growth, the task queue size is capped to a specific size. This setting changes the value of that maximum number.You generally don't need to change this setting. This setting also corresponds to the number of tasks that the AWS CLI is aware of that need to be run. This means that by default the AWS CLI can only see 1000 tasks ahead. Increasing this value means that the AWS CLI can more quickly know the total number of tasks needed, assuming that the queuing rate is quicker than the rate of task completion. The tradeoff is that a larger max_queue_size requires more memory.
multipart_chunksize
-
Specifies the chunk size that the AWS CLI uses for multipart transfers of individual files. The default value is 8 MB, with a minimum of 5 MB.
When a file transfer exceeds the
multipart_threshold
, the AWS CLI divides the file into chunks of this size. This value can be specified using the same syntax asmultipart_threshold
, either as the number of bytes as an integer, or by using a size and a suffix. multipart_threshold
-
Specifies the size threshold the AWS CLI uses for multipart transfers of individual files. The default value is 8 MB.
When uploading, downloading, or copying a file, the Amazon S3 commands switch to multipart operations if the file exceeds this size. You can specify this value in one of two ways:
-
The file size in bytes. For example,
1048576
. -
The file size with a size suffix. You can use
KB
,MB
,GB
, orTB
. For example:10MB
,1GB
.Note
S3 can impose constraints on valid values that can be used for multipart operations. For more information, see the S3 Multipart Upload documentation in the Amazon Simple Storage Service User Guide.
-