Skip to content

Getting started

This page takes you from the AWS Marketplace listing to a running resolver: subscribe, launch, connect, and run your first validated queries. It takes about ten minutes.

You need: an AWS account with permission to subscribe to AWS Marketplace products and launch EC2 instances.

1. Subscribe

Open the Unbound DNS Resolver listing, review the pricing and terms, and subscribe.

2. Launch the instance

Launch from the listing with these settings:

  • Instance type: t3.medium.
  • Storage: at least 16 GiB, encrypted gp3.
  • Security group: no inbound rules are needed. Unbound listens on loopback only. If you want SSH, allow port 22 only from your own administrative address range.
  • IAM instance profile: to connect with AWS Systems Manager Session Manager, attach a role with the AWS managed policy AmazonSSMManagedInstanceCore. The resolver itself needs no AWS permissions.

3. Connect

Connect with Session Manager, from the EC2 console (Connect > Session Manager), and switch to the ubuntu user:

sudo -iu ubuntu

Wait for first boot to finish:

cloud-init status --wait

4. Run the walkthrough

The walkthrough must run as ubuntu:

bash /opt/sushi/docs/demo.sh

It first checks that sushi-unbound-firstboot, unbound-auth and unbound are all active. It does not start them for you: if one is inactive, it stops, so you can look at that service's log. It then:

  1. Resolves the test names and checks DNSSEC validation.
  2. Checks that a client other than 127.0.0.1 is refused.
  3. Adds a temporary forward zone with unbound-control, resolves a name through it, and removes it again.
  4. Checks that ubuntu cannot read the DNSSEC private keys.
  5. Runs the image's self-test.

It ends with SUSHI_CUSTOMER_DEMO_PASSED.

5. Run your own queries

Look up a name from local data:

dig @127.0.0.1 app.pilot.invalid A

The answer is 192.0.2.10.

Look up a signed name and check that it is validated:

dig @127.0.0.1 app.secure.test A +dnssec

The answer is 192.0.2.20, and the flags line includes ad (authenticated data).

Check that the resolver refuses other clients. 127.0.0.2 is a loopback address, but it is outside the allowed client list:

dig @127.0.0.1 -b 127.0.0.2 app.pilot.invalid A

The status is REFUSED.

The instance itself still uses the VPC resolver

Unbound does not replace systemd-resolved or change /etc/resolv.conf. The instance keeps using the Amazon VPC resolver for its own lookups. Query Unbound explicitly with dig @127.0.0.1.

Next steps

Forward your private zones or serve other hosts in Configuration.