CLI53(1)

NAME
cli53 - command line tool for Amazon Route 53 DNS management

SYNOPSIS
cli53 [global options] command [command options] [arguments...]

DESCRIPTION
cli53 is a command line interface for managing DNS zones and records on Amazon Route 53. It is aimed at system administrators, DevOps engineers and developers who prefer scriptable, automation-friendly workflows over the AWS web console.

The tool uses the BIND zone file format as its native interchange format, making it straightforward to migrate existing DNS configurations to Route 53 or to keep local backups of hosted zones under version control.

Main features:

•   Import and export hosted zones in standard BIND format.

•   Create, list and delete hosted zones.

•   Create, update and delete individual resource records.

•   Support for AWS-specific record types: weighted, latency-based, geolocation, failover and ALIAS records.

•   Create, list and delete reusable delegation sets.

•   Support for VPC-associated private hosted zones.

•   Authentication via ~/.aws/credentials, environment variables or IAM instance roles.

COMMANDS

list, l
    List all hosted zones in the account. Supports multiple output formats via --format (text, json).

create
    Create a new hosted zone. Accepts an optional --comment and --delegation-set-id to associate a reusable delegation set. Use --vpc-id and --vpc-region to create a private zone.

delete
    Delete a hosted zone by domain name or zone ID.

validate
    Validate the syntax of a BIND zone file without making any changes to Route 53. Useful to check zone files before importing.

import
    Import a BIND zone file into a hosted zone. Supports dry-run mode, replace (full sync) and upsert (add or update without deleting).

export
    Export a hosted zone as a BIND zone file to standard output. Use --full to emit fully-qualified domain names.

rrcreate, rc
    Create one or more resource records. Records are specified as quoted BIND-format strings. Supports weighted, latency, geolocation, failover, multivalue and ALIAS routing policies via flags.

rrdelete, rd
    Delete a specific resource record by name and type.

rrpurge
    Delete all resource records in a zone except the SOA and the apex NS records. Use with caution.

instances
    Dynamically register EC2 instance names as DNS records by querying the EC2 API, keeping the zone in sync with running instances.

dslist
    List all reusable delegation sets in the account.

dscreate
    Create a new reusable delegation set. Optionally takes a caller-reference.

dsdelete
    Delete a reusable delegation set by its ID.

help, h
    Show the list of commands or help for a specific command.

GLOBAL OPTIONS

--profile name
    Use a named profile from ~/.aws/credentials. Equivalent to setting AWS_PROFILE.

--role-arn arn
    Assume the specified IAM role before making API calls. Can be combined with --profile.

--endpoint-url url
    Override the Route 53 endpoint. Accepts a hostname or a fully qualified URL. Useful for local testing (e.g. LocalStack).

--help, -h
    Show help.

--version, -v
    Print the version.

AUTHENTICATION
cli53 uses the standard AWS credential chain. Credentials are resolved in the following order:

1.  The file ~/.aws/credentials under the [default] profile or the profile named by --profile / AWS_PROFILE.

2.  The environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (and optionally AWS_SESSION_TOKEN).

3.  An IAM instance role attached to the EC2 instance (or ECS task) running the tool.

PRIVATE AND PUBLIC ZONES
When a domain has both a private and a public hosted zone, the domain name is ambiguous. In that case, pass the 13-character zone ID (shown after /hostedzone/ in the output of cli53 list) instead of the domain name:

        cli53 rrcreate ZZZZZZZZZZZZZ 'name A 127.0.0.1'

EXAMPLES

  Hosted zone management
List all hosted zones:

        cli53 list

List zones in JSON format (useful with jq):

        cli53 list --format json | jq '.[].Name'

Create a new hosted zone with a comment:

        cli53 create --comment 'production zone' example.com

Create a private zone associated with a VPC:

        cli53 create --vpc-id vpc-12345678 --vpc-region us-east-1 example.internal

Delete a hosted zone:

        cli53 delete example.com

  Importing and exporting zone files
Validate a zone file before importing:

        cli53 validate --file zonefile.txt

Import a BIND zone file:

        cli53 import --file zonefile.txt example.com

Dry-run import to preview changes without applying them:

        cli53 import --file zonefile.txt --replace --dry-run example.com

Full replace (sync) waiting for completion:

        cli53 import --file zonefile.txt --replace --wait example.com

Upsert: add new records and update existing ones without deleting:

        cli53 import --file zonefile.txt --upsert example.com

Export a zone to stdout in BIND format:

        cli53 export example.com

Export fully-qualified names, redirecting AWS debug output to a log file:

        cli53 export --full --debug example.com > zone.txt 2> debug.log

  Creating and managing resource records
Create an A record with TTL of 60 seconds:

        cli53 rrcreate example.com 'www 60 A 192.168.0.1'

Update (replace) an existing A record:

        cli53 rrcreate --replace example.com 'www 60 A 192.168.0.2'

Delete an A record:

        cli53 rrdelete example.com www A

Create MX records:

        cli53 rrcreate example.com '@ MX 10 mail1.' '@ MX 20 mail2.'

Create a round-robin A record (multiple values):

        cli53 rrcreate example.com '@ A 192.168.0.1' '@ A 192.168.0.2'

Create CNAME records (relative and absolute):

        cli53 rrcreate example.com 'login CNAME www'
        cli53 rrcreate example.com 'mail CNAME ghs.googlehosted.com.'

Delete all records in a zone (dangerous):

        cli53 rrpurge --confirm example.com

  AWS routing policies
Create weighted records:

        cli53 rrcreate --identifier server1 --weight 10 example.com 'www A 192.168.0.1'
        cli53 rrcreate --identifier server2 --weight 20 example.com 'www A 192.168.0.2'

Create geolocation records (continent and subdivision):

        cli53 rrcreate -i Africa --continent-code AF example.com 'geo 300 IN A 10.0.0.1'
        cli53 rrcreate -i California --country-code US --subdivision-code CA     example.com 'geo 300 IN A 10.0.0.2'

Create primary/secondary failover records with a health check:

        cli53 rrcreate -i Primary --failover PRIMARY     --health-check 2e668584-4352-4890-8ffe-6d3644702a1b     example.com 'ha 300 IN A 10.0.0.1'
        cli53 rrcreate -i Secondary --failover SECONDARY     example.com 'ha 300 IN A 10.0.0.2'

Create multivalue answer records with health checks:

        cli53 rrcreate -i One --multivalue     --health-check 2e668584-4352-4890-8ffe-6d3644702a1b     example.com 'ha 300 IN A 10.0.0.1'
        cli53 rrcreate -i Two --multivalue     --health-check 7c90445d-ad67-47bd-9649-3ca0985e1f88     example.com 'ha 300 IN A 10.0.0.2'

  ALIAS records
Create an ALIAS pointing to an ELB:

        cli53 rrcreate example.com     'www AWS ALIAS A dns-name.elb.amazonaws.com. ABCDEFABCDE false'

Create an ALIAS pointing to another record in the same zone:

        cli53 rrcreate example.com 'www AWS ALIAS A server1 $self false'

  EC2 instances
Register all running EC2 instances as A records in the zone, using each instance Name tag as the hostname (requires EC2 read permissions):

        cli53 instances example.com

Dry-run to preview the records that would be created:

        cli53 instances --dry-run example.com

Use a specific AWS profile and region:

        cli53 instances --profile production example.com

  Reusable delegation sets
Create, list and delete a reusable delegation set:

        cli53 dscreate
        cli53 dslist
        cli53 dsdelete NA24DEGBDGB32

Create a hosted zone using an existing delegation set:

        cli53 create --delegation-set-id NA24DEGBDGB32 example.com

  Profile and role switching
Use a non-default credentials profile:

        cli53 list --profile staging

Assume an IAM role:

        cli53 list --role-arn arn:aws:iam::123456789012:role/dns-manager

Combine profile and role:

        cli53 list --profile staging     --role-arn arn:aws:iam::123456789012:role/dns-manager

CAVEATS
Amazon Route 53 limits change requests to a maximum of 100 resource record changes per API call. When an operation exceeds this limit, cli53 automatically splits it into multiple requests. A replace-style import involves deletes followed by creates, which may briefly leave the zone in an inconsistent state.

ENVIRONMENT

AWS_ACCESS_KEY_ID
    AWS access key ID.

AWS_SECRET_ACCESS_KEY
    AWS secret access key.

AWS_SESSION_TOKEN
    AWS session token (required when using temporary credentials).

AWS_PROFILE
    Name of the profile to use from ~/.aws/credentials.

AWS_REGION
    AWS region. Route 53 is a global service but some operations (e.g. VPC association) require a region to be set.

FILES

~/.aws/credentials
    AWS credentials file. See aws-config(5) for the format.

~/.aws/config
    AWS configuration file for region and output format defaults.

SEE ALSO
aws(1), bind(8), named-checkzone(8)

Amazon Route 53 documentation: https://docs.aws.amazon.com/route53/

Upstream source: https://github.com/barnybug/cli53

AUTHOR
Barnaby Gray <barnaby@pickle.me.uk>

This manual page was written by Josenilson Ferreira da Silva <nilsonfsilva@hotmail.com> for the Debian project.