Warpgate on Ubuntu 24.04 on Azure User Guide

Overview

Warpgate is a self-hosted, transparent bastion / access gateway that gives your team one recorded, audited entry point into SSH, HTTPS, MySQL and PostgreSQL infrastructure - without installing any client-side software. Administrators manage targets (the servers and services your users connect to), roles and users from Warpgate's own built-in web console, and every session - SSH, web, or database - is logged and can be recorded and played back later. The cloudimg image installs the pinned Warpgate 0.26.1 binary, runs it as a dedicated warpgate system user under systemd with its own native HTTPS admin console (a self-signed TLS certificate generated fresh on every VM), and generates a unique per-VM admin password on first boot. Warpgate's audit database, session recordings, TLS certificate and SSH keys all live on a dedicated Azure data disk. Backed by 24/7 cloudimg support.

What is included:

• Warpgate 0.26.1 (single Rust binary) running as the warpgate systemd service
• A native HTTPS admin console on :443 (self-signed per-VM certificate) - login, targets, roles, users, and recorded sessions
• A separate SSH bastion gateway on :2222 for your recorded/audited targets, distinct from this VM's own management SSH on :22
• MySQL (:33306) and PostgreSQL (:55432) wire proxies for database targets
• A unique admin password generated on first boot, never stored in plaintext
• A dedicated Azure data disk at /var/lib/warpgate holding the audit database, session recordings, TLS certificate and SSH keys
• warpgate.service + nginx.service as systemd units, enabled and active
• An unauthenticated /healthz endpoint (nginx, :80) for Azure Load Balancer health probes
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point. NSG inbound: allow 22/tcp from your management network (this VM's own OS SSH), 443/tcp for the admin console and HTTPS targets, 2222/tcp for Warpgate's own SSH bastion gateway, and 33306/tcp / 55432/tcp if you plan to add MySQL or PostgreSQL targets. Keep :2222 and :22 separate in your NSG and firewall documentation - they are two different listeners on two different processes.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Warpgate by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22). After creation, add inbound NSG rules for 443 (admin console), 2222 (Warpgate's SSH bastion gateway), and 33306 / 55432 if you need the MySQL or PostgreSQL proxies. Review the dedicated data disk on the Disks tab, then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name warpgate \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name warpgate --port 443  --priority 1010
az vm open-port --resource-group <your-rg> --name warpgate --port 2222 --priority 1020

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

This is the box's own OS management SSH on port 22 - separate from the Warpgate bastion gateway you will configure below.

Step 4 - Confirm the services are running

systemctl is-active warpgate.service nginx.service

Both report active. Warpgate listens natively (with its own TLS certificate) on :443 for the admin console and HTTPS targets, on :2222 for its SSH bastion gateway, and on :33306 / :55432 for the MySQL and PostgreSQL wire proxies; nginx only serves an unauthenticated health check and a redirect on :80. Warpgate's audit database, session recordings, TLS certificate and SSH host/client keys live on the dedicated Azure data disk mounted at /var/lib/warpgate.

Step 5 - Retrieve your admin password

A unique admin password is generated on the first boot of your VM and written to a root-only file, along with the Warpgate version, the config file location and confirmation that a fresh TLS certificate and SSH keys were generated for this VM:

sudo cat /root/warpgate-credentials.txt

This file contains WARPGATE_ADMIN_USERNAME, WARPGATE_ADMIN_PASSWORD, the WARPGATE_URL to open in a browser, and the bastion/proxy ports. The password is only ever hashed (argon2id) inside Warpgate's own database - no plaintext password ships in the image. If WARPGATE_URL shows a private IP (an Azure Instance Metadata Service quirk on Standard SKU public IPs), use the VM's public IP address from the Azure Portal or az vm list-ip-addresses instead - the admin console itself works identically either way. Store the password somewhere safe.

Step 6 - Confirm the health endpoint and the login round-trip

nginx serves an unauthenticated health endpoint for load balancers and probes, and Warpgate ships its own healthcheck subcommand:

curl -s http://localhost/healthz
sudo warpgate --config /etc/warpgate.yaml healthcheck && echo "admin console healthy"

Because a password is set on first boot, the login API rejects a wrong password and accepts only the per-VM one - nobody reaches the console or your recorded sessions without it:

PW=$(sudo grep '^WARPGATE_ADMIN_PASSWORD=' /root/warpgate-credentials.txt | cut -d= -f2-)
curl -sk -o /dev/null -w 'wrong password  -> HTTP %{http_code}\n' -X POST -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"wrong-pw"}' https://127.0.0.1/@warpgate/api/auth/login
curl -sk -o /dev/null -w 'per-VM password -> HTTP %{http_code}\n' -X POST -H 'Content-Type: application/json' \
  -d "{\"username\":\"admin\",\"password\":\"$PW\"}" https://127.0.0.1/@warpgate/api/auth/login

The wrong password prints HTTP 401; the correct one prints HTTP 201.

Step 7 - Sign in to the web console

Browse to https://<vm-public-ip>/ (the TLS certificate is self-signed per VM, so accept the browser warning until you add a trusted domain and certificate - see Maintenance). You land on the Welcome screen: enter admin and the password from Step 5.

Step 8 - The Sessions dashboard

After signing in you land on the Sessions dashboard: a "getting started" checklist (check the docs, add a target, add a non-admin user) and the list of active sessions - every connection through Warpgate, including your own admin login, appears here in real time with its protocol, user and age.

Step 9 - Add your first target

Open Config -> Targets -> Add a target. Warpgate supports five target types: SSH (shell, SFTP and port forwarding), HTTP (Warpgate proxies as a reverse proxy), MySQL, PostgreSQL and Kubernetes (experimental). Pick the type that matches the server or service you want your team to reach through the gateway, then fill in its host, port and credentials.

Once a target exists, create an Access role and assign it to the target and to the users who should reach it, then have your users connect through the gateway - for example, for an SSH target:

ssh -p 2222 <your-warpgate-username>:<target-name>@<this-host>

Step 10 - Browse a recorded session

Click any session in the Sessions list to open its detail view: a timestamped, searchable log of every request Warpgate proxied for that session, plus a Close now control to terminate it immediately. This is the audit trail that makes Warpgate useful for compliance and incident response - every SSH, HTTP or database session your team makes through the gateway is recorded here.

Step 11 - Confirm data lives on the dedicated disk

Warpgate's audit database, session recordings, TLS certificate and SSH host/client keys are kept under /var/lib/warpgate on the dedicated Azure data disk, so they survive OS changes and the disk can be resized independently:

findmnt /var/lib/warpgate

The mount is backed by a separate Azure data disk captured into the image and re-provisioned on every VM.

Maintenance

• Password: the admin password is set on first boot and only ever stored hashed inside Warpgate's own database. To reset it, run sudo warpgate --config /etc/warpgate.yaml recover-access (interactive) from an SSH session.
• TLS: the admin console's certificate is self-signed per VM. For production, add a trusted domain and a certificate you control from Config -> Targets (Warpgate's HTTP target/reverse-proxy TLS settings) or place a certificate in front of :443 on your own domain.
• Users and roles: create separate non-admin accounts under Config -> Users, and scope what each can reach with Access roles, so day-to-day users never need the admin account.
• Ports: the SSH bastion gateway (:2222), MySQL proxy (:33306) and PostgreSQL proxy (:55432) are Warpgate's own listeners, independent of this VM's OS SSH (:22) - open only the ports you actually use in your NSG.
• Upgrades: Warpgate is a single binary at /usr/bin/warpgate; to upgrade, download a newer pinned release, verify its checksum, replace the binary and sudo systemctl restart warpgate. Your audit database, recordings and certificate under /var/lib/warpgate are preserved.
• Storage: all Warpgate state lives under /var/lib/warpgate on the data disk; back up that volume to protect your audit trail and session recordings.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.