AWS Command Line Interface
Guia do usuário

Arquivos de configuração e credencial

Você pode salvar as definições de configuração usadas com frequência e credenciais em arquivos que são mantidos pela AWS CLI. Os arquivos são divididos em seções que podem ser referenciadas por nome. Elas são chamadas de "perfis". A menos que você especifique o contrário, a CLI usa as configurações encontradas no perfil chamado default. Para usar outras configurações, você pode criar e fazer referência a perfis adicionais. Você também pode substituir uma configuração definindo uma das variáveis de ambiente com suporte ou usando um parâmetro de linha de comando.

Onde as definições de configuração ficam armazenadas?

A AWS CLI armazena credenciais especificadas com aws configure em um arquivo local chamado credentials em uma pasta chamada .aws em seu diretório inicial. As outras opções de configuração que você especifica com aws configure são armazenadas em um arquivo local chamado config, também armazenado na pasta .aws no seu diretório inicial. O local do diretório inicial varia de acordo com o sistema operacional, mas é acessado usando as variáveis de ambiente %UserProfile% no Windows e $HOME ou ~ (til) em sistemas baseados em Unix.

Por exemplo, os seguintes comandos relacionam o conteúdo da pasta .aws.

Linux, macOS, or Unix

$ ls ~/.aws

Windows

C:\> dir "%UserProfile%\.aws"

A AWS CLI usa dois arquivos para armazenar as informações confidenciais de credenciais (em ~/.aws/credentials) separadas das opções de configuração menos confidenciais (em ~/.aws/config).

Você pode especificar um local não padrão para o arquivo config definindo a variável de ambiente AWS_CONFIG_FILE para outro caminho local. Para mais detalhes, consulte Variáveis de ambiente.

Armazenar credenciais no arquivo de configuração

A AWS CLI também pode ler credenciais a partir do arquivo config. É possível manter todas as suas configurações de perfil em um único arquivo. Se houver credenciais em dois locais para um perfil (por exemplo, que você usou aws configure para atualizar as chaves do perfil), as chaves no arquivo de credenciais terão precedência.

Esses arquivos também são usados pelos vários kits de desenvolvimento de software de linguagem (SDKs). Se você usar um dos SDKs, além da AWS CLI, poderá receber avisos adicionais se as credenciais não forem armazenadas em seu próprio arquivo.

Os arquivos gerados pela CLI para o perfil configurado na seção anterior são semelhantes a este.

~/.aws/credentials

[default] aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

~/.aws/config

[default] region=us-west-2 output=json

nota

Os exemplos anteriores mostram os arquivos com um único perfil padrão. Para obter exemplos dos arquivos com vários perfis nomeados, consulte Perfis nomeados.

Configurações de arquivo config com suporte

As configurações a seguir têm suporte no arquivo config. Os valores listados no perfil especificado (ou padrão) serão usados, a menos que eles sejam ignorados pela presença de uma variável de ambiente ou uma opção de linha de comando com o mesmo nome.

Você pode definir essas configurações editando o arquivo config diretamente com um editor de texto ou usando o comando aws configure set. Especifique o perfil que você deseja modificar com a configuração --profile. Por exemplo, o comando a seguir define a configuração region no perfil chamado integ.

aws configure set region us-west-2 --profile integ

Você também pode recuperar o valor para qualquer configuração usando o subcomando get.

$ aws configure get region --profile default us-west-2

Se a saída estiver vazia, a configuração não estará explicitamente definida e usará o valor padrão.

Configurações globais

aws_access_key_id

Especifica a chave de acesso da AWS usada como parte das credenciais para autenticar a solicitação do comando. Embora ela possa ser armazenada no arquivo config, recomendamos armazená-la no arquivo credentials.

Pode ser substituída pela variável de ambiente AWS_ACCESS_KEY_ID. Você não pode especificar o ID de chave de acesso como uma opção de linha de comando.

aws_access_key_id = 123456789012
aws_secret_access_key

Especifica a chave secreta da AWS usada como parte das credenciais para autenticar a solicitação do comando. Embora ela possa ser armazenada no arquivo config, recomendamos armazená-la no arquivo credentials.

Pode ser substituída pela variável de ambiente AWS_SECRET_ACCESS_KEY. Você não pode especificar a chave de acesso secreta como uma opção de linha de comando.

aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token

Especifica um token de sessão da AWS. Um token de sessão só será necessário se você estiver usando credenciais de segurança temporárias. Embora ela possa ser armazenada no arquivo config, recomendamos armazená-la no arquivo credentials.

Pode ser substituída pela variável de ambiente AWS_SESSION_TOKEN. Você não pode especificar o token de sessão como uma opção de linha de comando.

aws_session_token = AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4Olgk
ca_bundle

Especifica um pacote de certificado CA (um arquivo com a extensão .pem) que é usado para verificar certificados SSL.

Pode ser substituído pela variável de ambiente AWS_CA_BUNDLE ou pela opção de linha de comando --ca-bundle.

ca_bundle = dev/apps/ca-certs/cabundle-2019mar05.pem
cli_follow_urlparam

Especifica se a CLI tentará seguir links de URL em parâmetros de linha de comando que começam com http:// ou https://. Quando ativado, o conteúdo recuperado é usado como o valor do parâmetro, em vez do URL.

  • true: esse é o valor padrão. Quando configurado, todos os parâmetros de string que comecem com http:// ou https:// são extraídos e todo o conteúdo baixado é usado como o valor do parâmetro para o comando.

  • false: a CLI não trata valores de string de parâmetros que comecem com http:// ou https:// de forma diferente de outras strings.

Esta entrada não tem uma variável de ambiente equivalente nem uma opção de linha de comando.

cli_follow_urlparam = false
cli_timestamp_format

Especifica o formato dos valores de timestamp incluídos no resultado. Você pode especificar qualquer um dos seguintes valores:

  • none: esse é o valor padrão. Exibe o valor de timestamp exatamente conforme recebido na resposta de consulta HTTP.

  • iso8601: reformata o timestamp conforme especificado pelo ISO 8601.

Esta entrada não tem uma variável de ambiente equivalente nem uma opção de linha de comando.

cli_timestamp_format = iso8601
credential_process

Especifica um comando externo que a CLI executa para gerar ou recuperar credenciais de autenticação a serem usadas para esse comando. O comando deve retornar as credenciais em um formato específico. Para obter mais informações sobre como usar essa configuração, consulte Credenciais de fornecimento com um processo externo.

Esta entrada não tem uma variável de ambiente equivalente nem uma opção de linha de comando.

credential_process = /opt/bin/awscreds-retriever --username susan
output

Especifica o formato de saída padrão para comandos solicitados usando esse perfil. Você pode especificar qualquer um dos seguintes valores:

  • json: esse é o valor padrão. A saída é formatada como uma string JSON.

  • text: a saída é formatada como várias linhas de valores de string separadas por tabulação, o que poderá ser útil se você quiser transmitir a saída para um processador de texto, como grep, sed ou awk.

  • table: a saída é formatada como uma tabela usando os caracteres +|- para formar as bordas da célula. Geralmente, a informação é apresentada em um formato "amigável", que é muito mais fácil de ler do que outros, mas não tão útil programaticamente.

Pode ser substituído pela variável de ambiente AWS_DEFAULT_OUTPUT ou pela opção de linha de comando --output.

output = table
parameter_validation

Especifica se o cliente de CLI tentará validar os parâmetros antes de enviá-los para o endpoint de serviço da AWS.

  • true: esse é o valor padrão. Quando configurado, a CLI executa a validação local de parâmetros de linha de comando.

  • false: quando configurado, a CLI não valida parâmetros de linha de comando antes de enviá-los para o endpoint de serviço da AWS.

Esta entrada não tem uma variável de ambiente equivalente nem uma opção de linha de comando.

parameter_validation = false
region

Especifica a região padrão da AWS para a qual enviar solicitações para os comandos solicitados usando esse perfil. Você pode especificar qualquer um dos códigos de região disponíveis para o serviço escolhido, conforme listado em Regiões e endpoints da AWS no Referência geral do Amazon Web Services.

Pode ser substituído pela variável de ambiente AWS_DEFAULT_REGION ou pela opção de linha de comando --region.

region = us-west-2
tcp_keepalive

Especifica se o cliente de CLI usará pacotes keep-alive de TCP.

Esta entrada não tem uma variável de ambiente equivalente nem uma opção de linha de comando.

tcp_keepalive = false
api_versions

Alguns serviços da AWS mantêm várias versões de API para oferecer suporte à compatibilidade com versões anteriores. Por padrão, os comandos da CLI usam a versão de API mais recente disponível. Você pode especificar uma versão de API a ser usada para um perfil incluindo a configuração api_versions no arquivo config.

Essa é uma configuração "aninhada" que é seguida por uma ou mais linhas recuadas, cada uma identificando um serviço da AWS e a versão de API a ser usada. Consulte a documentação de cada serviço para saber quais versões de API estão disponíveis.

O exemplo a seguir mostra como especificar uma versão de API para dois serviços da AWS. Essas versões de API são usadas apenas para comandos que são executados sob o perfil que contém essas configurações.

api_versions = ec2 = 2015-03-01 cloudfront = 2015-09-017

Configurações de comando personalizadas do S3

O Amazon S3 oferece suporte a várias configurações que definem como a CLI executa operações do S3. Algumas se aplicam a todos os comandos do S3 nos namespaces s3api e s3. Outras são especificamente para o comandos "personalizados" do S3 que abstraem operações comuns e fazem mais do que um mapeamento individual para uma operação de API. Os comandos de transferência aws s3 cp, sync, mv e rm têm configurações adicionais que você pode usar para controlar as transferências do S3.

Todas essas opções podem ser configuradas especificando a configuração s3 aninhada em seu arquivo config. Depois, cada configuração é recuada em sua própria linha.

nota

Essas configurações são totalmente opcionais. Você deve ser capaz de usar com êxito os comandos de transferência aws s3 sem definir nenhuma dessas configurações. Essas configurações são fornecidas para permitir que você ajuste o desempenho ou considere o ambiente específico no qual você está executando esses comandos aws s3.

As configurações a seguir se aplicam a qualquer comando do S3 nos namespaces s3 ou s3api.

use_accelerate_endpoint

Use o endpoint Amazon S3 Accelerate para todos os comandos s3 e s3api. O valor padrão é falso. Isso é mutuamente exclusivo com a configuração use_dualstack_endpoint.

Se for definido como true, a CLI direcionará todas as solicitações do Amazon S3 para o endpoint do S3 Accelerate em s3-accelerate.amazonaws.com. Para usar esse endpoint, você deve ativar o bucket para usar o S3 Accelerate. Todas as solicitações são enviadas usando o estilo virtual de endereçamento de bucket: my-bucket.s3-accelerate.amazonaws.com. As solicitações ListBuckets, CreateBucket e DeleteBucket não serão enviadas ao endpoint do Accelerate porque esse endpoint não oferece suporte a essas operações. Esse comportamento também poderá ser definido se o parâmetro --endpoint-url estiver definido como https://s3-accelerate.amazonaws.com ou http://s3-accelerate.amazonaws.com para qualquer comando s3 ou s3api.

use_dualstack_endpoint

Use o endpoint IPv4/IPv6 duplo do Amazon S3 para todos os comandos s3 e s3api. O valor padrão é falso. Isso é mutuamente exclusivo com a configuração use_accelerate_endpoint.

Se for definido como true, o CLI direcionará todas as solicitações do Amazon S3 para o endpoint IPv4/IPv6 duplo para a região configurada.

addressing_style

Especifica qual estilo de endereçamento usar. Isso controla se o nome do bucket está no nome do host ou em parte da URL. Os valores são: path, virtual e auto. O valor padrão é auto.

Há dois estilos de criação de um endpoint do S3. O primeiro é chamado virtual e inclui o nome do bucket como parte do nome do host. Por exemplo: https://bucketname.s3.amazonaws.com. Como alternativa, com o estilo path, você trata o nome do bucket como se fosse um caminho no URI. Por exemplo: https://s3.amazonaws.com/bucketname. O valor padrão na CLI é usar auto, que tentará empregar o estilo virtual onde puder, mas voltará para o estilo path quando necessário. Por exemplo, se o nome do bucket não for compatível com DNS, ele não poderá fazer parte do nome do host e deverá estar no caminho. Com auto, a CLI detectará essa condição e alternará automaticamente para o estilo path. Se você definir o estilo de endereçamento como path, garanta que a região da AWS que você configurou na AWS CLI corresponda à região do seu bucket.

payload_sigining_enabled

Especifica se o SHA256 deverá assinar cargas sigv4. Por padrão, ele fica desativado para uploads de streaming (UploadPart e PutObject) ao usar https. Por padrão, esse valor é definido como false para uploads de streaming (UploadPart e PutObject), mas somente se um ContentMD5 estiver presente (é gerado por padrão) e o endpoint usar HTTPS.

Se definido como true, as solicitações do S3 receberão validação de conteúdo adicional na forma de uma soma de verificação SHA256 que é calculada para você e será incluída na assinatura da solicitação. Se for definido como false, a soma de verificação não será calculada. Desativar essa opção poderá ser útil para reduzir a sobrecarga de desempenho criada pela soma da soma de verificação.

As seguintes configurações se aplicam somente ao conjunto de comandos do namespace s3:

max_concurrent_requests

Especifica o número máximo de solicitações simultâneas. O valor padrão é 10.

Os comandos de transferência aws s3 são multithread. Em um determinado momento, várias solicitações do Amazon S3 podem estar em execução. Por exemplo, quando você usa o comando aws s3 cp localdir s3://bucket/ --recursive para fazer upload de arquivos para um bucket do S3, a AWS CLI pode carregar os arquivos localdir/file1, localdir/file2 e localdir/file3 paralelamente. A configuração max_concurrent_requests especifica o número máximo de operações de transferência que podem ser executadas ao mesmo tempo.

Talvez você precise alterar esse valor por alguns motivos:

  • Diminuir esse valor – em alguns ambientes, o padrão de 10 solicitações simultâneas pode sobrecarregar um sistema. Isso pode causar erros de tempo limite de conexão ou diminuir a capacidade de resposta do sistema. Reduzir esse valor faz com que os comandos de transferência do S3 usem menos recursos. A desvantagem é que as transmissões do S3 podem levar mais tempo para serem concluídas. Reduzir esse valor poderá ser necessário se você usar uma ferramenta para limitar a largura de banda.

  • Aumentar esse valor – em alguns cenários, você pode querer que as transferências do S3 sejam concluídas com o máximo de rapidez possível, usando o máximo de largura de banda da rede necessária. Nesse cenário, o número padrão de solicitações simultâneas pode não ser suficiente para utilizar toda a largura de banda de rede disponível. O aumento desse valor pode melhorar o tempo necessário para concluir uma transferência do S3.

max_queue_size

Especifica o número máximo de tarefas na fila de tarefas. O valor padrão é 1000.

A AWS CLI usa internamente um modelo que coloca na fila as tarefas do S3 que, depois, são executadas por consumidores cujos números são limitados por max_concurrent_requests. Em geral, uma tarefa é mapeada para uma única operação do S3. Por exemplo, a tarefa pode ser uma PutObjectTask, GetObjectTask ou uma UploadPartTask. A taxa na qual as tarefas são adicionadas à fila pode ser muito mais rápida do que a taxa na qual os consumidores concluem as tarefas. Para evitar o crescimento não vinculado, o tamanho da fila de tarefas é limitada a um tamanho específico. Essa configuração altera o valor desse número máximo.

Em geral, você não precisa alterar essa configuração. Essa configuração também corresponde ao número de tarefas que a CLI está ciente de que precisam ser executadas. Isso significa que, por padrão, a CLI só pode ver 1.000 tarefas à frente. Até o comando do S3 saber o número total de tarefas executadas, a linha de andamento mostrará um total de... Aumentar esse valor significa que a CLI pode saber com mais rapidez o número total de tarefas necessárias, supondo-se que a taxa de enfileiramento seja mais rápida do que a taxa de conclusão de tarefas. A desvantagem é que um tamanho máximo maior da fila requer mais memória.

multipart_threshold

Especifica o limite de tamanho que a CLI usa para transferências multipart de arquivos individuais. O valor padrão é 8 MB.

Ao fazer upload, download ou copiar um arquivo, os comandos do S3 alternarão para operações multipart se o arquivo exceder esse tamanho. É possível especificar esse valor de duas formas:

  • O tamanho do arquivo em bytes. Por exemplo, 1048576.

  • O tamanho do arquivo com um sufixo de tamanho. Você pode usar KB, MB, GB ou TB. Por exemplo: 10MB, 1GB.

    nota

    O S3 pode impor restrições quanto a valores válidos que podem ser usados para operações multipart. Para obter mais informações, consulte a documentação sobre Multipart Upload do S3 no Guia do desenvolvedor do Amazon Simple Storage Service.

multipart_chunksize

Especifica o tamanho de bloco que a CLI usa para transferências multipart de arquivos individuais. O valor padrão é 8 MB, com um mínimo de 5 MB.

Quando uma transferência de arquivos excede o multipart_threshold, a CLI divide o arquivo em blocos desse tamanho. Esse valor pode ser especificado usando a mesma sintaxe que multipart_threshold, como o número de bytes como um número inteiro ou usando um tamanho e um sufixo.

max_bandwidth

Especifica a largura de banda máxima que pode ser consumida para upload e download de dados de e para o Amazon S3. O padrão é sem limite.

Isso limita a largura de banda máxima que os comandos do S3 podem usar para transferir dados de e para o S3. Esse valor se aplica apenas a uploads e downloads; ele não se aplica a cópias nem as exclui. O valor é expresso em bytes por segundo. O valor pode ser especificado como:

  • Um valor inteiro. Por exemplo, 1048576 define o uso máximo da largura de banda como 1 megabyte por segundo.

  • Um valor inteiro seguido por um sufixo de taxa. Você pode especificar sufixos de taxa usando: KB/s, MB/s ou GB/s. Por exemplo: 300KB/s, 10MB/s.

Em geral, recomendamos que você primeiro tente reduzir o consumo de largura de banda diminuindo max_concurrent_requests. Se isso não adequar o consumo de largura de banda limite para a taxa desejada, use a configuração max_bandwidth que poderá ser usada para limitar ainda mais o consumo de largura de banda. Isso ocorre porque max_concurrent_requests controla o número de threads em execução no momento. Se, em vez disso, você primeiro reduzir max_bandwidth, mas deixar uma configuração max_concurrent_requests alta, poderá fazer com que os threads aguardem desnecessariamente, o que poderá causar um consumo excessivo de recursos e tempos limite de conexão.

Essas configurações são todas definidas em uma chave s3 de nível superior no arquivo config, conforme mostrado no exemplo a seguir para o perfil development:

[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