A strongSwan IKEv2 VPN gateway in a Docker image, built from the official
release tarball, configured with swanctl, and shipped with a Prometheus
exporter. Every change is built, scanned with Trivy, and tested end to end
against Debian and Ubuntu clients before it is merged.
| Component | Version |
|---|---|
| strongSwan | 6.1.0 |
| strongswan-exporter | v1.0.0 |
| Go (exporter build) | 1.27.2 |
| Base image | Ubuntu 26.04 LTS |
The versions above are defined in versions.sh, the single
source of truth for builds and tests. See the changelog.
- strongSwan 6.1.0 built from source – the release tarball is verified by SHA-256 before it is built.
- Explicit plugin set – every plugin is enabled or disabled on purpose in
server/configure-strongswan.sh; OpenSSL is the only crypto provider. - swanctl / VICI configuration – no legacy
ipsec.conf/ stroke. - Prometheus exporter built in, listening on port 9234.
- Container-friendly runtime –
tinias PID 1, clean shutdown ondocker stop, logs on stdout, Docker healthcheck. - Small attack surface – multi-stage build, no compilers or headers in the final image, unused binaries removed.
- Tested on every change – Trivy scan plus an end-to-end suite with five client distributions; results are published per test in GitHub.
- Automated version updates – a weekly workflow proposes pull requests for new strongSwan, exporter and Go releases.
docker build -t strongswan-server:latest -f server/strongswan.dockerfile .The image is not published to a registry; build it from this repository.
Build arguments (STRONGSWAN_VERSION, STRONGSWAN_SHA256,
EXPORTER_VERSION, GO_VERSION, UBUNTU_VERSION) default to the values in
versions.sh.
The container reads a standard swanctl directory, /etc/swanctl by default:
swanctl/
├── swanctl.conf # connections and pools
├── x509/ # server certificate (PEM)
├── x509ca/ # CA certificates (PEM)
└── private/ # server private key (PEM) - keep mode 0700
A minimal road-warrior configuration (clients authenticate with
certificates and receive an address from 10.0.70.0/24):
connections {
rw {
version = 2
proposals = aes256gcm16-prfsha256-x25519-ecp256
pools = rw_pool
send_cert = always
local {
auth = pubkey
certs = server.crt
id = vpn.example.com
}
remote {
auth = pubkey
cacerts = ca.crt
}
children {
protected {
local_ts = 10.10.10.0/24
esp_proposals = aes256gcm16
dpd_action = clear
}
}
}
}
pools {
rw_pool {
addrs = 10.0.70.0/24
}
}
strongSwan matches IKE identities against the certificate's
subjectAltName, so id must appear there (for example DNS:vpn.example.com).
testing/generate_ca_and_certs.sh shows
how to create a matching Ed25519 test PKI with OpenSSL.
docker run -d --name strongswan \
--cap-add NET_ADMIN \
--sysctl net.ipv4.ip_forward=1 \
-p 500:500/udp -p 4500:4500/udp -p 9234:9234/tcp \
-v /path/to/swanctl:/etc/swanctl:ro \
strongswan-server:latestNET_ADMINis required to manage IPsec (XFRM) state and policies.net.ipv4.ip_forward=1is required if clients reach networks behind the gateway.- Hosts on the protected network need a route back to the VPN pool through the gateway.
Check the result:
docker logs strongswan
docker exec strongswan swanctl --list-conns
docker exec strongswan swanctl --list-sas| Variable | Default | Description |
|---|---|---|
SWANCTL_DIR |
/etc/swanctl |
swanctl configuration directory to load at startup. |
VICI_TIMEOUT |
30 |
Seconds to wait for charon's control socket before giving up. |
EXPORTER_ENABLED |
true |
Set to false to not start the Prometheus exporter. |
CHARON_STOP_TIMEOUT |
8 |
Seconds charon gets to shut down before it is killed. Keep it below the docker stop timeout (10 s by default). |
The entrypoint starts charon, waits for the VICI socket
(/var/run/charon.vici), loads the configuration with
swanctl --load-all --noprompt and starts the exporter. The container exits
if the configuration fails to load, so mistakes are visible immediately.
On docker stop the exporter and charon are stopped cleanly and the
container exits with charon's exit code. To reload changed configuration
without a restart:
docker exec strongswan swanctl --load-all --nopromptcharon logs to stdout (docker logs) at level 1, configured in
server/charon-logging.conf. To change log
levels, mount your own file over
/etc/strongswan.d/charon-logging-container.conf.
The image's healthcheck runs swanctl --stats every 30 seconds; the
container is healthy while charon answers on its control socket.
| Port | Purpose |
|---|---|
| 500/udp | IKE |
| 4500/udp | IKE and ESP with NAT traversal |
| 9234/tcp | Prometheus exporter |
The bundled strongswan-exporter serves:
| Endpoint | Content |
|---|---|
/metrics |
Prometheus metrics |
/sessions |
Session list |
/sessions_local |
Local session list |
/static |
HTML overview of connected clients |
Main metrics:
| Metric | Description |
|---|---|
probe_success |
1 while the exporter can talk to charon |
strongswan_info |
strongSwan version |
strongswan_sessions_total |
Number of established IKE SAs |
strongswan_bytes_in_total / strongswan_bytes_out_total |
Traffic per client |
Data is refreshed every 15 seconds. Byte counters belong to the client's current tunnel, so they restart from 0 when a client reconnects or the tunnel is rekeyed.
The image is built with OpenSSL as the only crypto backend; strongSwan's native crypto plugins are disabled because they would only duplicate it. Highlights:
- Enabled: openssl, curve25519, ml (ML-KEM), x509, pem, pkcs1/7/8, pubkey, revocation, constraints, curl, eap-identity, eap-tls, eap-radius, attr, resolve, updown, counters, certexpire, kernel-netlink, vici, swanctl.
- Disabled: stroke (legacy
ipsec.conf), IKEv1-only plugins (xauth, unity), EAP-MD5/MSCHAPv2/PEAP/TTLS, MD4/MD5, pkcs12, kernel-libipsec, and the network helpers bypass-lan, farp, forecast and connmark.
bypass-lan in particular is disabled because it caused charon to hang on shutdown. See the script for the full, commented list.
Every push and pull request runs the Validation Workflow on a self-hosted runner:
- pre-clean-up – removes all Docker resources on the runner.
- Build – builds the image with the versions from
versions.sh. - Trivy – fails on unignored HIGH/CRITICAL vulnerabilities
(exceptions in
.trivyignore); the report is added to the job summary. - End-to-end tests –
testing/e2e.bats, run with bats. Results appear as a check with one entry per test; logs are uploaded as thee2e-test-resultsartifact. - post-clean-up – removes everything again, whatever the outcome.
The test topology:
clients (192.168.200.0/24) ──IPsec──> server ──> protected service (10.10.10.10)
One client runs on each supported release, using that distribution's own strongSwan package: Debian 12 and 13, Ubuntu 22.04, 24.04 and 26.04. The tests cover configuration loading, tunnel setup, virtual IP assignment, traffic through the tunnel (verified by IPsec packet counters), the exporter, container restart and clean shutdown.
To run the suite on a machine with Docker and bats:
docker build -t strongswan-server:latest -f server/strongswan.dockerfile .
testing/e2e.sh up
bats testing/e2e.bats
testing/e2e.sh downtesting/e2e.sh also has connect (reconnect all clients), traffic
(keep a slow ping running from every client) and logs <dir>.
The Weekly Version Check runs
every Wednesday at 06:00 UTC (or manually from the Actions tab). When a new
strongSwan, exporter or Go release is available,
scripts/check-updates.sh updates
versions.sh, the Dockerfile and the changelog, and opens a pull request,
on which the Validation Workflow then runs.
It needs a repository secret VERSION_UPDATE_TOKEN: a fine-grained personal
access token for this repository with Contents and Pull requests set to
read and write.
- Update
STRONGSWAN_VERSIONandSTRONGSWAN_SHA256inversions.shand the matchingARGdefaults inserver/strongswan.dockerfile. - Check strongSwan's
NEWSfor removed or renamed plugins and updateserver/configure-strongswan.sh. - Add a changelog entry and open a pull request; CI builds and tests it.
Running scripts/check-updates.sh locally does steps 1 and 3 for you.
server/ Dockerfile, configure script, entrypoint, logging and exporter config
testing/ e2e test suite, test topology and certificate/config generators
scripts/ maintenance scripts (weekly version check)
versions.sh component versions and test topology
- See CONTRIBUTING for the Git workflow and versioning.
- Contact the owner group: ThaseG.
MIT – see LICENSE.