# PowerDNS

PowerDNS with PowerDNS-Admin provides a complete, production ready DNS hosting solution that you can deploy in minutes. This AMI combines the high performance PowerDNS authoritative server with an intuitive web based management interface, giving you full control over your DNS infrastructure.

# 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
```