Initial Startup

The first boot takes a few minutes longer than a stock AMI because the gateway provisions itself on first launch: the easy-rsa PKI is generated, a server certificate is issued, the OpenVPN service is configured against the VPC's network layout, and the runtime services are started. Subsequent reboots are fast — these one-time steps are skipped.

Server Connection

Using SSM

All of our products are designed to support AWS Systems Manager (SSM) right out of the box. We strongly believe in security, and the fewer ports exposed to the public, the better. The SSM service provided by AWS perfectly aligns with this approach.

When you need to connect to an instance, opt for connecting through the Session Manager. Once you've gained access, execute the command sudo su ec2-user to switch to the user account where all of our tools are located. This ensures you have the appropriate permissions and access to the necessary resources.

Using SSH

SSH is also available, but is not the recommended path. The AMI ships without any pre-installed SSH keys: you must attach a key pair at instance launch and open port 22 on the security group yourself. The default user is ec2-user. Prefer SSM Session Manager whenever possible — it requires no inbound ports and produces an audit trail.

User Management

Creating a User

To create a new VPN user, all parameters are required:

sudo ov_user_add --first-name John \
                 --last-name Doe \
                 --email john.doe@example.com \
                 --traffic all \
                 --expiration-date 2026-12-31 \
                 --creation-reason "Remote access for Q4 project"

For routing only remote network traffic via the VPN:

sudo ov_user_add --first-name Jane \
                 --last-name Smith \
                 --email jane.smith@example.com \
                 --traffic partial \
                 --expiration-date 2026-06-30 \
                 --creation-reason "Access to private subnet"

Required Parameters

  • --first-name: User's first name
  • --last-name: User's last name
  • --email: User's email address
  • --traffic: Traffic routing mode (all or partial)
    • all: Routes all traffic through the VPN
    • partial: Routes only traffic to the remote network through the VPN
  • --expiration-date: Profile expiration date in YYYY-MM-DD format
  • --creation-reason: Justification for creating the profile (for audit purposes)

The .ovpn profile is emailed to the address specified — see Email Delivery below for the required SES setup.

Deleting a User

To delete a user, specify their email and traffic type:

sudo ov_user_delete --email john.doe@example.com --traffic all

This will revoke the user's certificate and update the Certificate Revocation List (CRL).

Listing All Users

To view all VPN users:

sudo ov_user_list

Lists every user with their email, traffic mode, full name, expiration date, and creation timestamp.

Listing Expired Users

To view all users with expired profiles:

sudo ov_user_list_expired

This command is report-only: it identifies profiles whose expiration date has passed, but does not revoke or disable them. Expired profiles continue to work until you explicitly run ov_user_delete. Use this command as part of a regular review cadence to renew or remove stale accounts.

Backup and Restore

From v1.0.3 the gateway ships two CLI tools — ov_backup and ov_restore — that capture and re-apply every operator-unique piece of state in a single command. Use them to migrate to a new instance, to roll forward onto a new AMI version, or to keep a disaster-recovery archive off the box.

What is in the archive

A single .tar.gz file containing:

  • The user database (/opt/0x4447/db/users.db).
  • The full easy-rsa PKI — CA certificate and private key, every client certificate and private key, the certificate database, and the revocation list (/usr/share/easy-rsa/pki/).
  • The operational OpenVPN state — ta.key, the active crl.pem, and the client-IP persistence file (/etc/openvpn/server/).
  • DNS, email, and mutt configuration files (/opt/0x4447/configs/).
  • The VPN profile email template (/opt/0x4447/templates/vpn_profile_email.txt).

Everything else — the generated OpenVPN server config, iptables state, the .done first-boot sentinel — is deliberately excluded, because those files are regenerated against the local VPC at first boot. Restoring them onto a different gateway would push the old gateway's DNS resolvers and routes to your clients.

Creating a backup

SSH into the gateway and run:

sudo ov_backup

No flags, no arguments. The command:

  1. Runs an all-or-nothing pre-flight check. If any required file is missing, it lists every missing path and exits without writing anything.
  2. Writes the archive to /home/ec2-user/backup-<hostname>-<UTC-timestamp>.tar.gz, owned by ec2-user, mode 600.
  3. Prints a summary block (users in the database, issued certificates, revoked profiles) so you can sanity-check the contents before copying it off the box.
  4. Prints ready-to-paste scp commands using both the public and private IPs of the gateway, discovered via IMDSv2.
  5. Prints a security warning — the archive contains the CA private key, every client's private key, the TLS-auth PSK, and your SES SMTP credentials.

Copy the archive off the gateway with one of the printed scp commands. Encrypt it at rest. Never email it, never put it in chat, never commit it to git.

Restoring onto a new gateway

Launch a fresh v1.0.3+ instance from the AMI and wait for first boot to complete (/opt/0x4447/.done exists). Then copy the archive up and run:

sudo ov_restore backup-<hostname>-<timestamp>.tar.gz

ov_restore is also all-or-nothing. Three pre-flight checks run against the archive itself before any file is touched on disk:

  • Whitelist — every entry inside the archive must be in the known set of paths. Tampered or hand-rolled archives are rejected.
  • Presence — every required file must be there. Partial archives are rejected.
  • CA certificate sanity — the bundled CA certificate must be a parseable X.509 certificate.

If any check fails, the gateway disk and the OpenVPN service are left untouched.

On success the tool stops the OpenVPN service, extracts the archive, re-asserts owner and mode 600 on every secret file, re-applies the split-DNS rules from the restored dns.conf, restarts the service, waits for it to settle, and prints a restore summary in the same shape as the backup summary — so you can visually diff the two and confirm nothing was lost.

After a restore

Move the Elastic IP from the old gateway to the new one before users reconnect. Existing .ovpn profiles bake in the public IP at issue time: same IP and every existing profile keeps working with no client-side change; different IP and every profile must be reissued with ov_user_add.

Verify:

sudo ov_user_list
sudo openssl crl -in /etc/openvpn/server/crl.pem -text -noout | grep -c 'Serial Number'

The user list and revoked-profile count must match the old gateway. Then connect a test client to confirm the new gateway is serving the restored PKI. Once verified, stop and terminate the old instance.

Caveats

  • Run as root. Both commands refuse to run without sudo.
  • Same major version only. Archives produced on v1.0.3 are restorable on any v1.0.3+ gateway. Restoring onto v1.0.2 or older is not supported.
  • The archive is a master secret. Treat it like a root password — if it ever leaks, rotate the CA and reissue every user.
  • No automatic schedule. ov_backup runs on demand only. If you want periodic snapshots, schedule it via cron or Systems Manager and copy the resulting file to S3 (with KMS encryption).

Email Delivery

When you create a user, their .ovpn profile is emailed automatically via Amazon SES. Configure SES credentials in /opt/0x4447/configs/email.conf:

AWS_REGION=us-east-1
SMTP_USERNAME=REPLACE_WITH_YOUR_SES_SMTP_USERNAME
SMTP_PASSWORD=REPLACE_WITH_YOUR_SES_SMTP_PASSWORD
FROM_EMAIL=no_reply@example.com
ENVIRONMENT_NAME=VPN Server

Notes:

  • SMTP_USERNAME and SMTP_PASSWORD are SES SMTP credentials, not your AWS access key/secret. Generate them in the SES console: Account dashboard → SMTP settings → Create SMTP credentials.
  • FROM_EMAIL must be a verified identity in the SES region you configured (a verified address or a verified domain).
  • While your SES account is in sandbox mode, recipient addresses must also be verified. Request production access in the SES console to send to arbitrary recipients.
  • ENVIRONMENT_NAME appears in the email body to help recipients identify which gateway issued the profile.

VPN Clients

Troubleshooting

The OpenVPN service runs as openvpn@0x4447-udp.service.

GoalCommand
Check service statussudo systemctl status openvpn@0x4447-udp
Tail live logssudo journalctl -u openvpn@0x4447-udp -f
Restart the servicesudo systemctl restart openvpn@0x4447-udp
Inspect generated server configsudo cat /etc/openvpn/udp-server.conf

The server config (/etc/openvpn/udp-server.conf) is regenerated on every boot. Do not edit it directly.

DNS Routing (advanced)

By default the gateway pushes its own resolver (the VPC DNS) to every connected client, so all DNS queries flow through the VPN. Most customers do not need to change this.

For hybrid networks — where some domains live in AWS Route 53 Private Hosted Zones, and others must resolve against on-prem DNS — you can configure per-domain DNS routing (split-DNS). Clients send queries for the listed suffixes through the VPN's DNS, and use their own local resolver for everything else.

Configuring Domain Routes

Edit /opt/0x4447/configs/dns.conf:

VPN_DNS_DOMAIN_ROUTES="internal.acme.com corp.acme.local"

Apply the change without rebooting:

sudo /opt/0x4447/lib/dns_routes_apply.sh

The helper rewrites the DNS push directives in the OpenVPN server config and reloads the service. Already-connected clients pick up the new routes on their next reconnect.

Caveats

  • Only meaningful for --traffic partial profiles. Full-tunnel (all) profiles route every packet through the VPN, including DNS, so per-domain routing has no effect there.
  • Client compatibility: OpenVPN Connect 3.x (Windows, macOS, iOS, Android) and Tunnelblick honour DOMAIN-ROUTE. NetworkManager-openvpn honours it when paired with systemd-resolved. Older clients silently fall back to using the pushed DNS for every query.
  • Empty value = default behaviour. If VPN_DNS_DOMAIN_ROUTES="", no per-domain routes are pushed.

IAM Requirements

The instance profile attached to the gateway must allow:

  • ec2:DescribeRouteTables
  • AmazonSSMManagedInstanceCore (AWS-managed policy) — required if you want to connect via SSM Session Manager.

Features

  • Unlimited Users: Supports an unlimited number of users, ensuring scalability for your growing needs.
  • Flexible Traffic Routing: Route all or specific parts of your traffic through the VPN, giving you complete control over your data flow.
  • Multi-CIDR VPC Support: Secondary VPC CIDR blocks are auto-detected and pushed to clients — no manual configuration needed.
  • VPC Peering Support: CIDRs of peer VPCs reachable via active peering connections are auto-discovered and pushed to clients, so users transparently reach resources across peered VPCs.

Use Cases

Access to Private AWS Subnets:

AWS networks contain subnets, which can be public or private. Private subnets are secure areas not directly accessible from the public internet, housing critical servers and data. The most secure method to access these private subnets is through a VPN deployed in a public subnet. This setup encrypts your connection, allowing safe access to the private subnet and its servers as if they were local to your network, ensuring data security and integrity within AWS environments.

Secured Internet Connection for Remote Employees:

Beyond accessing private resources, this VPN also safeguards the internet connections of remote employees. By routing their traffic through the VPN, all online activities are encrypted, protecting company-sensitive data from potential interception by third parties. This ensures that employees can work securely from any location, preserving confidentiality and data integrity.

Inter-Office Connectivity:

For organizations with multiple office locations, maintaining a secure and reliable inter-office network is crucial. Our VPN solution facilitates the creation of a secure virtual network overlaying the public internet, linking different office locations. This secure network tunnel ensures that data exchanged between offices is encrypted and protected from external threats, enabling seamless collaboration and resource sharing across geographical locations.

Compliance and Data Protection:

Businesses subject to stringent regulatory requirements can benefit significantly from our VPN solution. By encrypting data in transit and providing secure access controls, the VPN helps organizations comply with data protection laws and industry standards. This is particularly important for sectors like healthcare, finance, and legal, where data privacy is paramount.

← Back to gate