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.

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

• Desktop
  • Windows
  • MacOS
  • Linux
• Mobile
  • iOS
  • Android

Troubleshooting

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

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.