# 1.1.0 - ami-0d28e9bb2e71915ff

# PowerDNS + PowerDNS-Admin

## AWS Marketplace AMI

A production-ready, self-hosted authoritative DNS server with a powerful web-based management interface.

---

## Overview

This AMI provides a complete DNS hosting solution with:

| Component | Description |
|-----------|-------------|
| **PowerDNS** | High-performance authoritative DNS server |
| **PowerDNS-Admin** | Modern web interface for DNS zone management |
| **PostgreSQL** | Reliable database backend |
| **Docker** | Containerized deployment for easy updates |

---

## Requirements

### Instance Size

| Size | vCPU | RAM | Recommended For |
|------|------|-----|-----------------|
| t3.small | 2 | 2 GB | Development, testing, small deployments |
| t3.medium | 2 | 4 GB | Production with moderate DNS traffic |
| t3.large | 2 | 8 GB | High-traffic production environments |

**Minimum**: t3.small (2 vCPU, 2 GB RAM)

### Storage

| Volume | Size | Purpose |
|--------|------|---------|
| Root (EBS) | 8 GB | Operating system and Docker |
| Data (EBS) | 10 GB+ | DNS data, database, certificates |

**Important**: Attach a separate EBS volume for persistent data storage. This ensures your DNS zones and configuration survive instance replacement.

### Network (Security Group)

| Port | Protocol | Purpose |
|------|----------|---------|
| 22 | TCP | SSH access |
| 53 | TCP/UDP | DNS queries |
| 80 | TCP | HTTP (Let's Encrypt validation or HTTPS mode) |
| 443 | TCP | HTTPS (if enabled) |
| 8081 | TCP | PowerDNS API (restrict to trusted IPs) |
| 9191 | TCP | PowerDNS-Admin web UI (HTTP mode only) |

---

## Quick Start

### Step 1: Launch and Configure

1. **Launch the instance** with an attached EBS volume for data

2. **Connect via SSH**:
   ```bash
   ssh -i your-key.pem ubuntu@your-instance-ip
   ```

3. **Run the configuration script**:
   ```bash
   sudo /opt/powerdns/configure-powerdns.sh
   ```

4. **Follow the prompts** to configure:
   - Domain or IP address
   - HTTPS with Let's Encrypt (optional, requires domain)

### Step 2: Create Admin Account

1. Open PowerDNS-Admin in your browser:
   - HTTP mode: `http://YOUR-IP:9191`
   - HTTPS mode: `https://YOUR-DOMAIN`

2. Click **"Create an account"** to register your admin user

3. Log in with your new credentials

### Step 3: Connect to PowerDNS API

1. Go to **Settings** > **PDNS**

2. Configure the following:
   | Setting | Value |
   |---------|-------|
   | PowerDNS API URL | `http://powerdns:8081` |
   | PowerDNS API Key | (shown after configuration, see below) |
   | PowerDNS Version | `4.1.1` |

3. Click **Save Settings**

### Finding Your API Key

The API key is displayed after running the configuration script. You can also retrieve it anytime:

```bash
sudo cat /opt/powerdns/.credentials
```

---

## Automated Configuration (User-Data)

For automated deployments, launch with JSON user-data:

```json
{
  "host": "dns.example.com",
  "https": true,
  "letsencrypt_email": "admin@example.com"
}
```

**Parameters**:

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| host | No | Public IP | Domain or IP for web interface |
| https | No | false | Enable Let's Encrypt SSL |
| letsencrypt_email | If https=true | - | Email for SSL certificates |

After automated setup, create your admin account through the web UI and configure the API connection as described above.

---

## Management Commands

Use the `powerdns-cli` command for day-to-day management:

```bash
# Check service status
powerdns-cli status

# View logs
powerdns-cli logs              # All services
powerdns-cli logs powerdns     # PowerDNS only
powerdns-cli logs powerdns-admin   # Admin interface only

# Service control
sudo powerdns-cli start
sudo powerdns-cli stop
sudo powerdns-cli restart

# View configuration and credentials
powerdns-cli info
sudo powerdns-cli credentials

# Update to latest versions
sudo powerdns-cli update

# Backup and restore
sudo powerdns-cli backup
sudo powerdns-cli restore /path/to/backup.tar.gz

# Testing
powerdns-cli dns-test
powerdns-cli api-test
powerdns-cli zones
powerdns-cli version
```

---

## Using PowerDNS-Admin

### Creating DNS Zones

1. Click **Create Zone** in the left menu
2. Enter the domain name (e.g., `example.com`)
3. Select zone type:
   - **Native**: Standard authoritative zone
   - **Master**: Primary server for zone transfers
   - **Slave**: Secondary server receiving transfers
4. Click **Create**

### Adding DNS Records

1. Select a domain from the dashboard
2. Click **Add Record**
3. Choose record type (A, AAAA, CNAME, MX, TXT, SRV, CAA, etc.)
4. Enter name, content, and TTL
5. Click **Save**

### User Management

1. Go to **Users** in the left menu
2. Create additional user accounts as needed
3. Assign appropriate permissions

---

## HTTPS Setup

### With Let's Encrypt (Recommended for Production)

During configuration, enter a domain name (not IP) and choose to enable HTTPS:

**Requirements**:
- Domain must point to this server's IP before configuration
- Ports 80 and 443 must be accessible from the internet
- Provide a valid email for certificate notifications

Certificates renew automatically every 60 days.

### Without HTTPS

When using an IP address or declining HTTPS, the web interface runs on port 9191 over HTTP. This is suitable for:
- Internal/private networks
- Development and testing
- Deployments behind a separate load balancer or proxy

---

## Data Storage

### Location

All persistent data is stored on the EBS volume at `/mnt/powerdns-data/`:

| Directory | Contents |
|-----------|----------|
| `postgres/` | PostgreSQL database files |
| `pdns/` | PowerDNS configuration file |
| `certs/` | SSL certificates (if HTTPS enabled) |
| `acme/` | Let's Encrypt account data |

### Backup Strategy

**Create backup**:
```bash
sudo powerdns-cli backup
```

**Download backup**:
```bash
scp ubuntu@your-server:/tmp/powerdns-backup-*.tar.gz .
```

**Restore from backup**:
```bash
sudo powerdns-cli restore /path/to/backup.tar.gz
```

### EBS Recommendations

- Use `gp3` volume type for best performance/cost ratio
- Enable encryption for data at rest
- Create regular EBS snapshots for disaster recovery
- Size appropriately: 10-20 GB for most deployments

---

## Troubleshooting

### Cannot Create Zone (HTTP 400 Error)

Verify the API connection in Settings > PDNS:
- API URL must be `http://powerdns:8081` (container name, not IP)
- API Key must match the one from credentials file
- Version must be `4.1.1`

### Services Not Starting

```bash
powerdns-cli status
powerdns-cli logs
sudo powerdns-cli restart
```

### DNS Not Resolving

```bash
# Test DNS server
powerdns-cli dns-test

# Check if port 53 is listening
sudo ss -ulnp | grep 53

# Verify zones exist
powerdns-cli zones
```

### API Connection Failed

```bash
# Test API directly
powerdns-cli api-test

# View API key
sudo cat /opt/powerdns/.credentials | grep "API Key"

# Check PowerDNS logs
docker logs powerdns
```

---

## Security Recommendations

1. **Restrict port 8081** (API) to trusted IPs in your Security Group
2. **Use strong passwords** for your admin account (minimum 12 characters)
3. **Enable HTTPS** for production deployments
4. **Regular updates**: Run `sudo powerdns-cli update` periodically
5. **Backup regularly**: Use EBS snapshots and `powerdns-cli backup`
6. **Monitor logs**: Check for suspicious DNS queries or API access

---

## Configuration Files

| File | Purpose |
|------|---------|
| `/opt/powerdns/docker-compose.yml` | Container configuration |
| `/mnt/powerdns-data/pdns/pdns.conf` | PowerDNS server configuration |
| `/opt/powerdns/.credentials` | Saved API key and database password |
| `/opt/powerdns/config-info.txt` | Quick reference URLs |

---

## Version Information

| Component | Version |
|-----------|---------|
| PowerDNS | 4.9.x (API version 4.1.1) |
| PowerDNS-Admin | Latest |
| PostgreSQL | 15 |
| Ubuntu | 24.04 LTS |

Check current versions:
```bash
powerdns-cli version
```