Wg-Easy on Citizix, The Best blog for Linux, Opensource, Devops, Cloud and all things awesome tech.

Automate WireGuard VPN on AlmaLinux 10 With SaltStack

Tue, 03 Feb 2026 09:00:00 +0300

In our previous guide, we manually set up a WireGuard VPN server with wg-easy on AlmaLinux 10. While that approach works great for a single server, what if you need to deploy WireGuard to multiple servers? Or ensure consistent configuration across your infrastructure? This is where SaltStack (Salt) comes in.

In this comprehensive guide, you’ll learn how to automate the entire WireGuard VPN setup using Salt configuration management, turning hours of manual work into a single command.

What You’ll Learn

Setting up Salt Master and Minions architecture
Creating reusable Salt states for WireGuard
Automating firewall configuration with Salt
Managing Docker and wg-easy deployment via Salt
Using Salt Pillars for secure configuration data
Deploying to multiple servers with one command
Version controlling your infrastructure configuration
Troubleshooting Salt state applications

Why Use SaltStack for WireGuard?

Benefits of Infrastructure as Code

Manual Setup Pain Points:

❌ Time-consuming to deploy to multiple servers
❌ Configuration drift between servers
❌ No version control for server configurations
❌ Difficult to audit what was changed and when
❌ Manual errors during repetitive tasks
❌ No easy rollback mechanism

SaltStack Advantages:

✅ Deploy to 100 servers as easily as one
✅ Consistent configuration across all servers
✅ Git-based version control for all configs
✅ Complete audit trail of changes
✅ Automated, tested deployments
✅ Easy rollback to previous configurations
✅ Self-documenting infrastructure
✅ Idempotent operations (safe to run multiple times)

Prerequisites

Before we begin, ensure you have:

Salt Master Server: A server running Salt Master (can be your existing infrastructure)
WireGuard Server(s): One or more AlmaLinux 10 servers as Salt Minions
Root access to all servers
Git repository for storing Salt configurations (recommended)
Basic understanding of YAML syntax
Familiarity with manual WireGuard setup

Architecture Overview

Our Salt infrastructure will consist of:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


┌─────────────────────┐
│ Salt Master │
│ (Configuration) │
│ - Salt States │
│ - Pillar Data │
│ - Git Repo │
└──────────┬──────────┘
 │
 │ (Salt Protocol: 4505, 4506)
 │
 ┌──────┴─────────┬─────────────┐
 │ │ │
┌───▼────┐ ┌───▼────┐ ┌───▼────┐
│Minion 1│ │Minion 2│ │Minion 3│
│(VPN-1) │ │(VPN-2) │ │(VPN-3) │
└────────┘ └────────┘ └────────┘

Part 1: Setting Up Salt Infrastructure

Step 1: Install Salt Master

On your Salt Master server:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# Update system
sudo dnf update -y

# Add the official Salt Project repository
curl -fsSL https://github.com/saltstack/salt-install-guide/releases/latest/download/salt.repo \
 | sudo tee /etc/yum.repos.d/salt.repo
sudo dnf clean expire-cache

# Install Salt Master
sudo dnf install -y salt-master

# Start and enable Salt Master
sudo systemctl enable --now salt-master

# Verify installation
salt --version

Don’t install Salt from EPEL on AlmaLinux 10. Older guides (including earlier versions of this one) start with dnf install -y epel-release and then pull salt-master from EPEL. That no longer works: EPEL ships the classic (non-onedir) Salt packages only up to EPEL 9, and there is no Salt package in EPEL 10 at all — the install simply fails. The salt.repo file above is the supported path and is what the Salt install guide publishes. It ships one section per release branch; 3008 LTS is the newest branch enabled by default, so that is what dnf installs. To hold a host on a different branch (3006 LTS or 3007 STS), edit /etc/yum.repos.d/salt.repo and enable only that section. Pin a specific build with dnf install -y salt-master-3008.2.

Configure Salt Master:

1
2


# Edit master configuration
sudo vim /etc/salt/master

Add or modify these settings:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# Accept all minion keys automatically (dev only - remove for production)
auto_accept: False

# File server backend
fileserver_backend:
 - roots
 - git

# Git fileserver configuration (if using Git)
gitfs_remotes:
 - https://github.com/your-org/salt-configs.git

# File roots - where Salt states are stored
file_roots:
 base:
 - /srv/salt

# Pillar roots - where sensitive data is stored
pillar_roots:
 base:
 - /srv/pillar

1
2
3
4
5
6
7


# Restart Salt Master
sudo systemctl restart salt-master

# Open firewall ports
sudo firewall-cmd --permanent --add-port=4505/tcp
sudo firewall-cmd --permanent --add-port=4506/tcp
sudo firewall-cmd --reload

Step 2: Install Salt Minion on WireGuard Server(s)

On each WireGuard server:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# Update system
sudo dnf update -y

# Add the official Salt Project repository (same file as on the master)
curl -fsSL https://github.com/saltstack/salt-install-guide/releases/latest/download/salt.repo \
 | sudo tee /etc/yum.repos.d/salt.repo
sudo dnf clean expire-cache

# Install Salt Minion
sudo dnf install -y salt-minion

# Configure minion
sudo vim /etc/salt/minion

Keep the master and its minions on the same Salt release branch. A minion may run an older version than the master, but mixing 3006 and 3008 across a fleet is a good way to hit subtle state-rendering differences.

Add configuration:

1
2
3
4
5
6
7
8


# Salt Master IP or hostname
master: 192.168.1.100 # Replace with your Salt Master IP

# Unique minion ID
id: wireguard-srv

# Log level for troubleshooting
log_level: info

1
2
3
4
5


# Start and enable Salt Minion
sudo systemctl enable --now salt-minion

# Check minion status
sudo systemctl status salt-minion

Step 3: Accept Minion Keys

Back on the Salt Master:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# List pending minion keys
sudo salt-key -L

# Accept specific minion
sudo salt-key -a wireguard-srv

# Or accept all pending keys
sudo salt-key -A

# Verify minion is connected
sudo salt 'wireguard-srv' test.ping

Expected output:

1

wireguard-srv: True

Step 4: Create Salt Directory Structure

On the Salt Master, create the directory structure:

1
2
3
4
5
6
7


# Create base directories
sudo mkdir -p /srv/salt/{wireguard,firewall,hardening}
sudo mkdir -p /srv/pillar

# Set proper permissions
sudo chmod 755 /srv/salt
sudo chmod 700 /srv/pillar # Pillar contains sensitive data

Part 2: Creating Salt States for WireGuard

Understanding Salt States

Salt States are YAML files that describe the desired state of your system. They’re:

Declarative: You describe what you want, not how to do it
Idempotent: Safe to run multiple times
Modular: Reusable across different servers

State 1: WireGuard Installation and Configuration

Create /srv/salt/wireguard/init.sls:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343


# WireGuard VPN Server Configuration
# Manages WireGuard installation, configuration, and peer management

# Install WireGuard and required packages
wireguard-packages:
 pkg.installed:
 - pkgs:
 - wireguard-tools
 - qrencode # For generating QR codes for mobile clients
 - reload_modules: True

# Enable IP forwarding (required for VPN routing)
enable-ip-forwarding-sysctl:
 sysctl.present:
 - name: net.ipv4.ip_forward
 - value: 1

enable-ipv6-forwarding-sysctl:
 sysctl.present:
 - name: net.ipv6.conf.all.forwarding
 - value: 1

# Enable source address validation mark (needed for WireGuard with fwmark)
enable-src-valid-mark-sysctl:
 sysctl.present:
 - name: net.ipv4.conf.all.src_valid_mark
 - value: 1

# Ensure /etc/wireguard directory exists with proper permissions
wireguard-config-dir:
 file.directory:
 - name: /etc/wireguard
 - user: root
 - group: root
 - mode: 700
 - require:
 - pkg: wireguard-packages

# Generate server private key if it doesn't exist
wireguard-server-privkey:
 cmd.run:
 - name: wg genkey > /etc/wireguard/server_private.key
 - unless: test -f /etc/wireguard/server_private.key
 - require:
 - file: wireguard-config-dir

# Set proper permissions on private key
wireguard-server-privkey-perms:
 file.managed:
 - name: /etc/wireguard/server_private.key
 - user: root
 - group: root
 - mode: 600
 - replace: False
 - require:
 - cmd: wireguard-server-privkey

# Generate server public key from private key
wireguard-server-pubkey:
 cmd.run:
 - name: cat /etc/wireguard/server_private.key | wg pubkey > /etc/wireguard/server_public.key
 - unless: test -f /etc/wireguard/server_public.key
 - require:
 - cmd: wireguard-server-privkey

# Create peers directory for storing peer configurations
wireguard-peers-dir:
 file.directory:
 - name: /etc/wireguard/peers
 - user: root
 - group: root
 - mode: 700
 - require:
 - file: wireguard-config-dir

# Create helper scripts directory
wireguard-scripts-dir:
 file.directory:
 - name: /etc/wireguard/scripts
 - user: root
 - group: root
 - mode: 755
 - require:
 - file: wireguard-config-dir

# Deploy WireGuard server configuration
wireguard-server-config:
 file.managed:
 - name: /etc/wireguard/wg0.conf
 - user: root
 - group: root
 - mode: 600
 - contents: |
 [Interface]
 # Server configuration
 Address = {{ salt['pillar.get']('wireguard:server:address', '10.99.0.1/24') }}
 ListenPort = {{ salt['pillar.get']('wireguard:server:port', 51820) }}
 PrivateKey = __PRIVATE_KEY__

 # No PostUp/PostDown firewall hooks here on purpose.
 # firewall/wireguard.sls already applies masquerading, the `wireguard`
 # zone and the wg-to-public policy with --permanent, so they survive
 # reboots and firewalld reloads. Re-adding them as interface hooks would
 # only give you two sets of rules fighting over the same traffic.

 # Peer configurations will be added below
 # Use /etc/wireguard/scripts/add-peer.sh to add new peers
 - require:
 - file: wireguard-config-dir
 - file: wireguard-server-privkey-perms

# Replace placeholder with actual private key
wireguard-inject-privkey:
 cmd.run:
 - name: sed -i "s|__PRIVATE_KEY__|$(cat /etc/wireguard/server_private.key)|" /etc/wireguard/wg0.conf
 - onchanges:
 - file: wireguard-server-config
 - require:
 - file: wireguard-server-config
 - file: wireguard-server-privkey-perms

# Deploy peer management script
wireguard-add-peer-script:
 file.managed:
 - name: /etc/wireguard/scripts/add-peer.sh
 - user: root
 - group: root
 - mode: 755
 - contents: |
 #!/bin/bash
 # WireGuard Peer Management Script
 # Usage: add-peer.sh <peer-name> [peer-ip]

 set -e

 if [ -z "$1" ]; then
 echo "Usage: $0 <peer-name> [peer-ip]"
 echo "Example: $0 john-laptop 10.99.0.10"
 exit 1
 fi

 PEER_NAME="$1"
 PEER_DIR="/etc/wireguard/peers"
 CONFIG_FILE="/etc/wireguard/wg0.conf"
 SERVER_PUBLIC_KEY=$(cat /etc/wireguard/server_public.key)
 SERVER_ENDPOINT="{{ salt['pillar.get']('wireguard:server:endpoint', '100.23.15.226') }}:{{ salt['pillar.get']('wireguard:server:port', 51820) }}"
 SERVER_ADDRESS="{{ salt['pillar.get']('wireguard:server:address', '10.99.0.1/24') }}"
 VPN_NETWORK="{{ salt['pillar.get']('wireguard:server:network', '10.99.0.0/24') }}"
 TUNNEL_MODE="{{ salt['pillar.get']('wireguard:server:tunnel_mode', 'full') }}"

 # Set AllowedIPs based on tunnel mode
 if [ "$TUNNEL_MODE" = "full" ]; then
 # Full tunnel: Route all traffic through VPN
 ALLOWED_IPS="0.0.0.0/0, ::/0"
 else
 # Split tunnel: Only route VPN network traffic
 ALLOWED_IPS="$VPN_NETWORK"
 fi

 # Auto-assign IP if not provided
 if [ -z "$2" ]; then
 # Find the next available IP
 LAST_IP=$(grep -oP 'AllowedIPs = \K[0-9.]+' "$CONFIG_FILE" | tail -1 | cut -d. -f4)
 if [ -z "$LAST_IP" ]; then
 NEXT_IP=10
 else
 NEXT_IP=$((LAST_IP + 1))
 fi
 PEER_IP="10.99.0.$NEXT_IP/32"
 else
 PEER_IP="$2/32"
 fi

 # Check if peer already exists
 if [ -d "$PEER_DIR/$PEER_NAME" ]; then
 echo "Error: Peer '$PEER_NAME' already exists!"
 exit 1
 fi

 # Create peer directory
 mkdir -p "$PEER_DIR/$PEER_NAME"

 # Generate peer keys
 wg genkey | tee "$PEER_DIR/$PEER_NAME/private.key" | wg pubkey > "$PEER_DIR/$PEER_NAME/public.key"
 chmod 600 "$PEER_DIR/$PEER_NAME/private.key"

 PEER_PRIVATE_KEY=$(cat "$PEER_DIR/$PEER_NAME/private.key")
 PEER_PUBLIC_KEY=$(cat "$PEER_DIR/$PEER_NAME/public.key")

 # Add peer to server configuration
 cat >> "$CONFIG_FILE" <<EOF

 # Peer: $PEER_NAME
 [Peer]
 PublicKey = $PEER_PUBLIC_KEY
 AllowedIPs = $PEER_IP
 EOF

 # Create client configuration
 cat > "$PEER_DIR/$PEER_NAME/client.conf" <<EOF
 [Interface]
 PrivateKey = $PEER_PRIVATE_KEY
 Address = ${PEER_IP%/*}/24
 DNS = 1.1.1.1, 8.8.8.8

 [Peer]
 PublicKey = $SERVER_PUBLIC_KEY
 Endpoint = $SERVER_ENDPOINT
 AllowedIPs = $ALLOWED_IPS
 PersistentKeepalive = 25
 EOF

 # Generate QR code for mobile clients
 qrencode -t ansiutf8 < "$PEER_DIR/$PEER_NAME/client.conf" > "$PEER_DIR/$PEER_NAME/qrcode.txt"
 qrencode -t png -o "$PEER_DIR/$PEER_NAME/qrcode.png" < "$PEER_DIR/$PEER_NAME/client.conf"

 # Restart WireGuard to apply changes
 systemctl restart wg-quick@wg0

 echo "✓ Peer '$PEER_NAME' created successfully!"
 echo ""
 echo "Peer IP: ${PEER_IP%/*}"
 echo "Tunnel Mode: $TUNNEL_MODE"
 if [ "$TUNNEL_MODE" = "full" ]; then
 echo " → All traffic will be routed through VPN"
 else
 echo " → Only VPN network ($VPN_NETWORK) will be routed through VPN"
 fi
 echo "Configuration saved to: $PEER_DIR/$PEER_NAME/client.conf"
 echo ""
 echo "QR Code (for mobile):"
 cat "$PEER_DIR/$PEER_NAME/qrcode.txt"
 echo ""
 echo "To provide configuration to client:"
 echo " 1. Copy the file: $PEER_DIR/$PEER_NAME/client.conf"
 echo " 2. Or scan the QR code: $PEER_DIR/$PEER_NAME/qrcode.png"
 - require:
 - file: wireguard-scripts-dir

# Deploy peer removal script
wireguard-remove-peer-script:
 file.managed:
 - name: /etc/wireguard/scripts/remove-peer.sh
 - user: root
 - group: root
 - mode: 755
 - contents: |
 #!/bin/bash
 # WireGuard Peer Removal Script
 # Usage: remove-peer.sh <peer-name>

 set -e

 if [ -z "$1" ]; then
 echo "Usage: $0 <peer-name>"
 exit 1
 fi

 PEER_NAME="$1"
 PEER_DIR="/etc/wireguard/peers"
 CONFIG_FILE="/etc/wireguard/wg0.conf"

 # Check if peer exists
 if [ ! -d "$PEER_DIR/$PEER_NAME" ]; then
 echo "Error: Peer '$PEER_NAME' does not exist!"
 exit 1
 fi

 # Get peer public key
 PEER_PUBLIC_KEY=$(cat "$PEER_DIR/$PEER_NAME/public.key")

 # Remove peer from WireGuard
 wg set wg0 peer "$PEER_PUBLIC_KEY" remove || true

 # Remove peer from config file
 sed -i "/# Peer: $PEER_NAME/,/^$/d" "$CONFIG_FILE"

 # Backup and remove peer directory
 mv "$PEER_DIR/$PEER_NAME" "$PEER_DIR/$PEER_NAME.removed-$(date +%Y%m%d-%H%M%S)"

 # Restart WireGuard
 systemctl restart wg-quick@wg0

 echo "✓ Peer '$PEER_NAME' removed successfully!"
 - require:
 - file: wireguard-scripts-dir

# Deploy peer listing script
wireguard-list-peers-script:
 file.managed:
 - name: /etc/wireguard/scripts/list-peers.sh
 - user: root
 - group: root
 - mode: 755
 - contents: |
 #!/bin/bash
 # WireGuard Peer Listing Script

 echo "=== WireGuard Peers ==="
 echo ""

 # Show active peers from wg command
 echo "Active Peers:"
 wg show wg0 peers 2>/dev/null | while read -r pubkey; do
 peer_name=$(grep -r "$pubkey" /etc/wireguard/peers/*/public.key 2>/dev/null | cut -d/ -f5)
 peer_ip=$(wg show wg0 allowed-ips | grep "$pubkey" | awk '{print $2}')
 last_handshake=$(wg show wg0 latest-handshakes | grep "$pubkey" | awk '{print $2}')

 if [ -n "$last_handshake" ] && [ "$last_handshake" != "0" ]; then
 last_seen=$(date -d @"$last_handshake" "+%Y-%m-%d %H:%M:%S" 2>/dev/null || date -r "$last_handshake" "+%Y-%m-%d %H:%M:%S")
 else
 last_seen="Never"
 fi

 echo " - Name: ${peer_name:-Unknown}"
 echo " IP: $peer_ip"
 echo " Last Seen: $last_seen"
 echo ""
 done

 # Show configured peers
 echo "Configured Peers:"
 ls -1 /etc/wireguard/peers/ 2>/dev/null | while read -r peer; do
 if [ -f "/etc/wireguard/peers/$peer/public.key" ]; then
 peer_ip=$(grep "Address" "/etc/wireguard/peers/$peer/client.conf" 2>/dev/null | awk '{print $3}')
 echo " - $peer ($peer_ip)"
 fi
 done
 - require:
 - file: wireguard-scripts-dir

# Enable and start WireGuard service
wireguard-service:
 service.running:
 - name: wg-quick@wg0
 - enable: True
 - require:
 - pkg: wireguard-packages
 - file: wireguard-server-config
 - cmd: wireguard-inject-privkey
 - sysctl: enable-ip-forwarding-sysctl
 - watch:
 - file: wireguard-server-config

Use salt['pillar.get'], not pillar.get. This is the single most expensive typo in Salt, and earlier versions of this guide had it. Inside a template, pillar is just a Python dictionary — so pillar.get('wireguard:server:port', 51820) calls plain dict.get(), looks for a literal key named wireguard:server:port, never finds one, and cheerfully returns the default. Colon-delimited traversal into nested pillar data is a feature of the execution module, which you reach as salt['pillar.get']('wireguard:server:port', 51820).

The failure mode is nasty precisely because nothing errors: your states render, the highstate goes green, and every value silently comes from the defaults baked into the template. You only notice when you change something in pillar, re-apply, and the server keeps using the old value. If you have Salt states in the wild, this is worth grepping for today:
1
grep -rn "{{ pillar\.get(" /srv/salt/

State 2: Firewall Configuration

Create /srv/salt/firewall/init.sls:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


# Common firewall configuration for ALL minions
# This state provides the base firewall setup that every server needs

# Install firewalld package
firewalld:
 pkg.installed:
 - name: firewalld
 - reload_modules: True

# Ensure firewalld service is running and enabled
firewalld-service:
 service.running:
 - name: firewalld
 - enable: True
 - require:
 - pkg: firewalld

# Allow SSH (required for management of all servers)
allow-ssh:
 firewalld.present:
 - name: public
 - services:
 - ssh
 - require:
 - service: firewalld-service

# Reload firewall to apply common changes
firewall-reload-common:
 cmd.run:
 - name: firewall-cmd --reload
 - onchanges:
 - firewalld: allow-ssh

Create /srv/salt/firewall/wireguard.sls:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


# Firewall configuration for wireguard-srv
# This state adds ADDITIONAL rules beyond the common firewall (firewall/init.sls)

# Allow WireGuard UDP port
wireguard_allow_port:
 cmd.run:
 - name: firewall-cmd --permanent --add-port=51820/udp
 - unless: firewall-cmd --list-ports | grep -q "51820/udp"
 - require:
 - service: firewalld-service

# Enable masquerading for NAT (required for VPN traffic routing)
wireguard_enable_masquerade:
 cmd.run:
 - name: firewall-cmd --permanent --zone=public --add-masquerade
 - unless: firewall-cmd --zone=public --query-masquerade
 - require:
 - service: firewalld-service

# Give the tunnel its own zone
wireguard_zone:
 cmd.run:
 - name: firewall-cmd --permanent --new-zone=wireguard
 - unless: firewall-cmd --permanent --get-zones | grep -qw wireguard
 - require:
 - service: firewalld-service

wireguard_zone_interface:
 cmd.run:
 - name: firewall-cmd --permanent --zone=wireguard --add-interface=wg0
 - unless: firewall-cmd --permanent --zone=wireguard --query-interface=wg0
 - require:
 - cmd: wireguard_zone

# Allow the tunnel to forward OUT to the public zone. wg0 and the public NIC are
# in different zones, so this is INTER-zone forwarding and needs a policy object.
# (--add-forward would only cover intra-zone forwarding — see the note below.)
wireguard_policy:
 cmd.run:
 - name: firewall-cmd --permanent --new-policy=wg-to-public
 - unless: firewall-cmd --permanent --get-policies | grep -qw wg-to-public
 - require:
 - service: firewalld-service

wireguard_policy_config:
 cmd.run:
 - name: |
 firewall-cmd --permanent --policy=wg-to-public --add-ingress-zone=wireguard
 firewall-cmd --permanent --policy=wg-to-public --add-egress-zone=public
 firewall-cmd --permanent --policy=wg-to-public --set-target=ACCEPT
 - unless: firewall-cmd --permanent --policy=wg-to-public --get-target | grep -qw ACCEPT
 - require:
 - cmd: wireguard_policy
 - cmd: wireguard_zone

# Reload firewall to apply all WireGuard changes
wireguard_firewall_reload:
 cmd.run:
 - name: firewall-cmd --reload
 - onchanges:
 - cmd: wireguard_allow_port
 - cmd: wireguard_enable_masquerade
 - cmd: wireguard_zone_interface
 - cmd: wireguard_policy_config

Why a policy object instead of --direct FORWARD rules? Earlier versions of this guide used firewall-cmd --direct --add-rule ipv4 filter FORWARD 0 -i wg0 -j ACCEPT. Those rules do work, but firewalld’s direct interface has been deprecated since firewalld 1.0, and the states above are the supported replacement.

The trap when converting is reaching for --add-forward instead. That option enables intra-zone forwarding — between interfaces within one zone. A full-tunnel VPN is the opposite case: packets arrive on wg0 (the wireguard zone) and leave via your NIC (the public zone), which is inter-zone. A zone whose target is default will not forward across zones, so putting wg0 in internal and calling --add-forward reloads cleanly and still leaves clients with a tunnel and no internet. Inter-zone forwarding is what policy objects exist for.

The blunt alternative is to put wg0 in the built-in trusted zone, whose target is ACCEPT — that forwards to other zones too, but it also exposes every port on the VPN server itself to your VPN clients. The policy above does not.

State 3: wg-easy Web UI Deployment

Create /srv/salt/wireguard/wg-easy.sls:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187


# WireGuard Web UI (wg-easy) Configuration
# Provides a web-based interface for managing WireGuard peers

# Resolve pillar values once, up front. Doing the tunnel-mode branch here, in a
# Jinja variable, keeps conditional tags out of the compose file below — Jinja
# branching inside a YAML block scalar is an easy way to mangle your indentation.
{%- set wg = salt['pillar.get']('wireguard:server', {}) %}
{%- set ui = salt['pillar.get']('wireguard:ui', {}) %}
{%- set wg_endpoint = wg.get('endpoint', '100.23.15.226') %}
{%- set wg_port = wg.get('port', 51820) %}
{%- set wg_net = wg.get('network', '10.99.0.0/24') %}
{%- set wg_net6 = wg.get('network6', 'fdcc:ad94:bacf:61a3::/64') %}
{%- set wg_dns = wg.get('dns', '1.1.1.1,8.8.8.8') %}
{%- set ui_user = ui.get('username', 'admin') %}
{%- set ui_pass = ui.get('password', 'changeme123') %}
{%- set allowed_ips = '0.0.0.0/0,::/0' if wg.get('tunnel_mode', 'full') == 'full' else wg_net %}

# Add the Docker CE repository by writing the repo file directly.
# AlmaLinux 10 ships dnf5, where `dnf config-manager --add-repo <url>` no longer
# exists (it became `dnf config-manager addrepo --from-repofile=<url>`), so we
# skip the plugin entirely — curl works the same on dnf4 and dnf5 hosts.
docker-repo:
 cmd.run:
 - name: curl -fsSL https://download.docker.com/linux/rhel/docker-ce.repo -o /etc/yum.repos.d/docker-ce.repo
 - creates: /etc/yum.repos.d/docker-ce.repo

# Install Docker CE and related packages
docker-packages:
 pkg.installed:
 - pkgs:
 - docker-ce
 - docker-ce-cli
 - containerd.io
 - docker-buildx-plugin
 - docker-compose-plugin
 - require:
 - cmd: docker-repo

# Ensure Docker service is running.
#
# NOTE: there is deliberately no /etc/docker/daemon.json here. Earlier versions of
# this guide set "iptables": false on the theory that firewalld should own all
# networking. That only holds when every container runs with network_mode: host.
# wg-easy v15 runs on a BRIDGE network with published ports, and turning off
# Docker's firewall management breaks NAT and port publishing outright. On
# AlmaLinux 10 Docker's iptables commands are symlinked to iptables-nft, so its
# rules are translated into nftables for you — the default is correct as-is.
docker-service:
 service.running:
 - name: docker
 - enable: True
 - require:
 - pkg: docker-packages

# Create directory for wg-easy data
wg-easy-data-dir:
 file.directory:
 - name: /opt/wg-easy
 - user: root
 - group: root
 - mode: 755

# Deploy the compose file directly. No generator script, no bcrypt pre-hashing,
# no $-escaping: v15 takes its entire first-run configuration from INIT_*
# variables, which Salt renders straight from pillar.
wg-easy-compose:
 file.managed:
 - name: /opt/wg-easy/docker-compose.yml
 - user: root
 - group: root
 - mode: 600 # contains INIT_PASSWORD — keep it root-only
 - contents: |
 volumes:
 etc_wireguard:

 services:
 wg-easy:
 image: ghcr.io/wg-easy/wg-easy:15
 container_name: wg-easy
 environment:
 # Allow logging in over plain HTTP. Drop this and front the UI with
 # a TLS reverse proxy for anything you care about.
 - INSECURE=true
 # --- Unattended setup: read on FIRST START only ---
 - INIT_ENABLED=true
 - INIT_USERNAME={{ ui_user }}
 - INIT_PASSWORD={{ ui_pass }}
 - INIT_HOST={{ wg_endpoint }}
 - INIT_PORT={{ wg_port }}
 - INIT_DNS={{ wg_dns }}
 - INIT_IPV4_CIDR={{ wg_net }}
 - INIT_IPV6_CIDR={{ wg_net6 }}
 - INIT_ALLOWED_IPS={{ allowed_ips }}
 networks:
 wg:
 ipv4_address: 10.42.42.42
 ipv6_address: fdcc:ad94:bacf:61a3::2a
 volumes:
 - etc_wireguard:/etc/wireguard
 - /lib/modules:/lib/modules:ro
 ports:
 - "{{ wg_port }}:{{ wg_port }}/udp"
 - "51821:51821/tcp"
 restart: unless-stopped
 cap_add:
 - NET_ADMIN
 - SYS_MODULE
 sysctls:
 - net.ipv4.ip_forward=1
 - net.ipv4.conf.all.src_valid_mark=1
 - net.ipv6.conf.all.disable_ipv6=0
 - net.ipv6.conf.all.forwarding=1
 - net.ipv6.conf.default.forwarding=1

 networks:
 wg:
 driver: bridge
 enable_ipv6: true
 ipam:
 driver: default
 config:
 - subnet: 10.42.42.0/24
 - subnet: fdcc:ad94:bacf:61a3::/64
 - require:
 - file: wg-easy-data-dir

# Create systemd service for wg-easy
wg-easy-systemd:
 file.managed:
 - name: /etc/systemd/system/wg-easy.service
 - user: root
 - group: root
 - mode: 644
 - contents: |
 [Unit]
 Description=WireGuard Easy Web UI
 Requires=docker.service
 After=docker.service

 [Service]
 Type=oneshot
 RemainAfterExit=yes
 WorkingDirectory=/opt/wg-easy
 ExecStart=/usr/bin/docker compose up -d
 ExecStop=/usr/bin/docker compose down
 TimeoutStartSec=0

 [Install]
 WantedBy=multi-user.target
 - require:
 - file: wg-easy-compose

# Reload systemd to recognize new service
wg-easy-systemd-reload:
 cmd.run:
 - name: systemctl daemon-reload
 - onchanges:
 - file: wg-easy-systemd

# Allow wg-easy web UI port through firewall
wg-easy-firewall-port:
 cmd.run:
 - name: firewall-cmd --permanent --add-port=51821/tcp
 - unless: firewall-cmd --list-ports | grep -q "51821/tcp"
 - require:
 - service: firewalld-service

# Reload firewall
wg-easy-firewall-reload:
 cmd.run:
 - name: firewall-cmd --reload
 - onchanges:
 - cmd: wg-easy-firewall-port

# Start wg-easy service
wg-easy-service:
 service.running:
 - name: wg-easy
 - enable: True
 - require:
 - service: docker-service
 - file: wg-easy-compose
 - file: wg-easy-systemd
 - cmd: wg-easy-systemd-reload
 - watch:
 - file: wg-easy-compose
 - file: wg-easy-systemd

Four things in that state are worth calling out, because they are the parts most likely to bite you.

This targets wg-easy v15, and v15 is a different program. The rewrite threw out the configuration model every older wg-easy tutorial depends on: PASSWORD_HASH (and the wgpw command that produced it), WG_HOST, WG_PORT, WG_DEFAULT_ADDRESS, WG_ALLOWED_IPS and the rest are gone. They are not errors — they are silently ignored, which is a much worse way to fail. Config now lives in a SQLite database under /etc/wireguard, and the container runs on a bridge network with published ports instead of network_mode: host.

INIT_* is what makes v15 automatable at all. At first glance the rewrite looks hostile to config management: you’re supposed to click through a setup wizard in a browser. But upstream ships an unattended setup path for exactly this case, and it is a straight improvement over v14 — Salt renders INIT_USERNAME, INIT_PASSWORD, INIT_HOST, INIT_PORT and the CIDRs directly from pillar, and the whole generate-compose.sh dance (run a container just to bcrypt a password, then double every $ so Compose doesn’t eat it) disappears. Two rules come with it:

The variables are read only on first start. Once the SQLite DB exists, wg-easy ignores them. Changing INIT_PASSWORD in pillar and re-running state.apply will rewrite docker-compose.yml and restart the container, but it will not change the admin password — do that in the UI, or wipe the volume and re-init.
They must be set as a group. INIT_USERNAME, INIT_PASSWORD, INIT_HOST and INIT_PORT go together, and INIT_IPV4_CIDR requires INIT_IPV6_CIDR. Set half a group and setup won’t be skipped. Upstream also recommends removing the variables once setup is done, since the password sits in plain text in the compose file — which is why the file.managed above is mode 600.

Do not set "iptables": false in daemon.json. Plenty of AlmaLinux guides tell you to, on the grounds that the host is pure nftables. That advice is only sound when every container uses network_mode: host, which was true for v14 and is not true here. v15 publishes ports on a bridge network, and disabling Docker’s firewall management breaks NAT and port publishing. Docker’s iptables binary is symlinked to iptables-nft on AlmaLinux 10, so its rules land in nftables anyway. Leave the default alone — this state ships no daemon.json at all.

wg-easy replaces the wireguard state; it does not complement it. See the top file in Part 4.

Part 3: Salt Pillar Configuration

Pillar data stores sensitive configuration separate from states.

Create Pillar Data

Create /srv/pillar/common.sls:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


# Common pillar data shared across all minions

# WireGuard VPN Configuration
wireguard:
 server:
 # VPN network address for the server
 address: "10.99.0.1/24"

 # UDP port for WireGuard (default: 51820)
 port: 51820

 # Public endpoint that clients will connect to
 # This should be your server's public IP or domain
 endpoint: "100.23.15.226"

 # VPN network CIDR (used by clients to route traffic through VPN)
 network: "10.99.0.0/24"

 # IPv6 VPN network. wg-easy v15 requires this whenever INIT_IPV4_CIDR is set —
 # the two belong to the same INIT_* group and must be supplied together.
 network6: "fdcc:ad94:bacf:61a3::/64"

 # DNS servers pushed to clients
 dns: "1.1.1.1,8.8.8.8"

 # Tunnel mode: 'full' or 'split'
 # - 'full': Route ALL traffic through VPN (client appears to have VPN server's public IP)
 # - 'split': Only route VPN network traffic (10.99.0.0/24) through VPN
 tunnel_mode: "full"

 # Web UI Configuration (wg-easy)
 # Used ONLY by the wireguard.wg-easy state, and ONLY on the container's first
 # start — see Part 2, State 3. Changing these later does not rotate the admin
 # credentials; do that in the UI.
 ui:
 username: "admin"
 # ⚠️ SECURITY: Change this before deploying, and keep it in an encrypted
 # pillar (GPG renderer) rather than in plain text — it is written verbatim
 # into /opt/wg-easy/docker-compose.yml.
 password: "YourSecurePasswordHere123!"
 # Web UI will be accessible at: http://100.23.15.226:51821

Create /srv/pillar/top.sls:

1
2
3
4


base:
 # Common pillar data for all minions
 "*":
 - common

Refresh Pillar Data

1
2
3
4
5


# Refresh pillar data on all minions
sudo salt '*' saltutil.refresh_pillar

# Verify pillar data
sudo salt 'wireguard-srv' pillar.get wireguard

Part 4: Salt Top File Configuration

The top file tells Salt which states to apply to which minions.

Create /srv/salt/top.sls:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


base:
 # Apply base firewall to ALL minions
 "*":
 - firewall

 # WireGuard VPN server
 # Gets common firewall from '*', plus WireGuard installation and configuration
 "wireguard-srv":
 - wireguard # WireGuard VPN server setup and peer management
 - firewall.wireguard # WireGuard-specific firewall rules

Pick one: `wireguard` or `wireguard.wg-easy`

These two states are alternatives, not layers — assigning both to the same minion will break the deployment, and it is worth being explicit about why.

The wireguard state runs WireGuard natively on the host: wg-quick@wg0 owns the wg0 interface and binds UDP 51820. The wireguard.wg-easy state runs WireGuard inside a container, which creates its own wg0 in the container’s network namespace and publishes UDP 51820 on the host. Both want the same host port, so whichever starts second fails to bind. They also disagree about who owns peer state: the wireguard state manages peers through /etc/wireguard/wg0.conf and the shell scripts from State 1, while wg-easy keeps peers in its own SQLite database and knows nothing about that file.

So choose the model that fits:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


base:
 "*":
 - firewall

 # Model A — host-native WireGuard, peers managed by Salt + shell scripts.
 # CLI-driven, no web UI, everything is a file you can put in Git.
 "wireguard-srv":
 - wireguard
 - firewall.wireguard

 # Model B — wg-easy, peers managed through the web UI (or its API).
 # Salt provisions Docker and does an unattended first-run setup; day-2 peer
 # management happens in the UI, not in pillar.
 #
 # "wireguard-ui-srv":
 # - wireguard.wg-easy
 # - firewall.wireguard

Model B still wants firewall.wireguard for the masquerade rules and the open UDP port, but not the host wg0 zone assignment — the container’s wg0 never appears on the host, so that part is simply inert.

Everything from Part 5 onward assumes Model A. If you’re running Model B, the peer scripts (add-peer.sh, remove-peer.sh, list-peers.sh) and the custom execution module in Part 7 don’t apply — wg-easy owns peers, and you’d drive it through its API instead.

Part 5: Deploying WireGuard with Salt

Now comes the magic moment - deploying everything with a single command!

Test Configuration First (Dry-Run)

Always test before applying:

1
2
3
4
5


# Test all minions (dry-run)
sudo salt '*' state.apply test=True

# Test specific minion
sudo salt 'wireguard-srv' state.apply test=True

This shows what would change without actually changing anything.

Apply Configuration

1
2
3
4
5


# Apply to all minions
sudo salt '*' state.apply

# Or apply to specific minion
sudo salt 'wireguard-srv' state.apply

Expected output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


wireguard-srv:
----------
 ID: wireguard-packages
 Function: pkg.installed
 Result: True
 Comment: All specified packages are already installed
----------
 ID: wireguard-service
 Function: service.running
 Name: wg-quick@wg0
 Result: True
 Comment: Service wg-quick@wg0 is already enabled, and is running
----------

Summary for wireguard-srv
-------------
Succeeded: 45 (changed=20)
Failed: 0
-------------
Total states run: 45
Total run time: 45.123 s

Verify Deployment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# Check WireGuard is running
sudo salt 'wireguard-srv' cmd.run 'systemctl status wg-quick@wg0 --no-pager'

# Check WireGuard interface
sudo salt 'wireguard-srv' cmd.run 'wg show'

# Check firewall rules
sudo salt 'wireguard-srv' cmd.run 'firewall-cmd --list-all'

# Check wg-easy container (if deployed)
sudo salt 'wireguard-srv' cmd.run 'docker ps | grep wg-easy'

# Get server public key
sudo salt 'wireguard-srv' cmd.run 'cat /etc/wireguard/server_public.key'

Part 6: Managing Configuration Changes

Making Changes to Configuration

Change Tunnel Mode

Edit /srv/pillar/common.sls:

1
2
3


wireguard:
 server:
 tunnel_mode: "split" # Changed from 'full' to 'split'

Apply changes:

1
2
3
4
5
6
7
8


# Refresh pillar
sudo salt 'wireguard-srv' saltutil.refresh_pillar

# Reapply states
sudo salt 'wireguard-srv' state.apply

# Regenerate peer configs (if needed)
sudo salt 'wireguard-srv' cmd.run 'cd /etc/wireguard/scripts && ./add-peer.sh new-client'

Change VPN Network

Edit /srv/pillar/common.sls:

1
2
3
4


wireguard:
 server:
 address: "10.88.0.1/24"
 network: "10.88.0.0/24"

Apply and restart:

1
2
3


sudo salt 'wireguard-srv' saltutil.refresh_pillar
sudo salt 'wireguard-srv' state.apply
sudo salt 'wireguard-srv' cmd.run 'systemctl restart wg-quick@wg0'

Version Control with Git

Store your Salt configurations in Git:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# Initialize Git repository
cd /srv/salt
git init
git add .
git commit -m "Initial WireGuard Salt configuration"

# Add remote (GitHub, GitLab, etc.)
git remote add origin git@github.com:your-org/salt-wireguard.git
git push -u origin main

# After making changes
git add .
git commit -m "Change tunnel mode to split tunnel"
git push

# On Salt Master, pull changes
git pull origin main

# Apply to minions
sudo salt '*' state.apply

Part 7: Advanced Salt Techniques

Targeting Specific Minions

Salt supports sophisticated targeting:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# By minion ID
sudo salt 'wireguard-*' state.apply

# By grain (OS, CPU, etc.)
sudo salt -G 'os:AlmaLinux' state.apply

# By pillar data
sudo salt -I 'wireguard:server:tunnel_mode:full' state.apply

# Compound matching
sudo salt -C 'G@os:AlmaLinux and wireguard-*' state.apply

Using Salt Orchestration

Create /srv/salt/orchestrate/deploy-wireguard.sls:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


# Orchestration: Deploy WireGuard to multiple servers in order

# Step 1: Update all minions
update_system:
 salt.state:
 - tgt: "wireguard-*"
 - sls:
 - system.updates

# Step 2: Deploy base firewall
deploy_firewall:
 salt.state:
 - tgt: "wireguard-*"
 - sls:
 - firewall
 - require:
 - salt: update_system

# Step 3: Deploy WireGuard
deploy_wireguard:
 salt.state:
 - tgt: "wireguard-*"
 - sls:
 - wireguard
 - firewall.wireguard
 - require:
 - salt: deploy_firewall

# Step 4: Verify deployment
verify_deployment:
 salt.function:
 - name: cmd.run
 - tgt: "wireguard-*"
 - arg:
 - wg show
 - require:
 - salt: deploy_wireguard

Run orchestration:

1

sudo salt-run state.orchestrate orchestrate.deploy-wireguard

This orchestrates Model A hosts. There is deliberately no wireguard.wg-easy step in the chain — as Part 4 explains, wg-easy is an alternative to the host-native wireguard state, not a layer on top of it, so applying both to the same target would leave two processes fighting over UDP 51820. If you run wg-easy hosts, give them their own target (vpn-ui-*) and their own orchestration.

Salt Reactor for Auto-Healing

Create /srv/salt/reactor/wireguard-monitor.sls:

1
2
3
4
5
6


# Restart WireGuard if it fails
restart_wireguard:
 local.cmd.run:
 - tgt: {{ data['id'] }}
 - arg:
 - systemctl restart wg-quick@wg0

Configure reactor in /etc/salt/master:

1
2
3


reactor:
 - "salt/service/wg-quick@wg0/stopped":
 - /srv/salt/reactor/wireguard-monitor.sls

Custom Salt Modules

Create /srv/salt/_modules/wireguard.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


#!/usr/bin/env python3
"""
Custom Salt module for WireGuard management
"""

import subprocess


def add_peer(name, ip=None):
 """
 Add a WireGuard peer

 CLI Example:
 salt 'wireguard-srv' wireguard.add_peer john-laptop
 """
 cmd = ['/etc/wireguard/scripts/add-peer.sh', name]
 if ip:
 cmd.append(ip)

 result = subprocess.run(cmd, capture_output=True, text=True)
 return {
 'success': result.returncode == 0,
 'stdout': result.stdout,
 'stderr': result.stderr
 }


def list_peers():
 """
 List all WireGuard peers

 CLI Example:
 salt 'wireguard-srv' wireguard.list_peers
 """
 result = subprocess.run(
 ['/etc/wireguard/scripts/list-peers.sh'],
 capture_output=True,
 text=True
 )
 return result.stdout


def remove_peer(name):
 """
 Remove a WireGuard peer

 CLI Example:
 salt 'wireguard-srv' wireguard.remove_peer john-laptop
 """
 result = subprocess.run(
 ['/etc/wireguard/scripts/remove-peer.sh', name],
 capture_output=True,
 text=True
 )
 return {
 'success': result.returncode == 0,
 'stdout': result.stdout,
 'stderr': result.stderr
 }

Sync modules to minions:

1
2
3
4
5


sudo salt '*' saltutil.sync_modules

# Use custom module
sudo salt 'wireguard-srv' wireguard.add_peer john-laptop
sudo salt 'wireguard-srv' wireguard.list_peers

Part 8: Monitoring and Maintenance

Salt-Based Monitoring

Create /srv/salt/monitoring/wireguard-check.sls:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# Monitoring state - checks WireGuard health

wireguard_health_check:
 cmd.run:
 - name: |
 echo "=== WireGuard Health Check ==="
 echo "Service Status:"
 systemctl is-active wg-quick@wg0

 echo ""
 echo "Interface Status:"
 wg show wg0

 echo ""
 echo "Firewall Rules:"
 firewall-cmd --list-ports | grep 51820

 echo ""
 echo "Active Connections:"
 wg show wg0 latest-handshakes | wc -l

Run health check:

1

sudo salt 'wireguard-srv' state.sls monitoring.wireguard-check

Automated Backups with Salt

Create /srv/salt/backup/wireguard.sls:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# Backup WireGuard configuration

wireguard_backup:
 cmd.run:
 - name: |
 BACKUP_DIR="/root/wireguard-backups"
 DATE=$(date +%Y%m%d-%H%M%S)
 mkdir -p $BACKUP_DIR
 tar -czf $BACKUP_DIR/wireguard-$DATE.tar.gz \
 /etc/wireguard/ \
 /opt/wg-easy/ \
 /etc/docker/daemon.json
 # Keep only last 7 backups
 cd $BACKUP_DIR && ls -t | tail -n +8 | xargs -r rm
 echo "Backup created: wireguard-$DATE.tar.gz"

Schedule backups:

1
2
3
4
5


# Add to Salt scheduler
sudo salt 'wireguard-srv' schedule.add wireguard_backup \
 function='state.sls' \
 job_args='["backup.wireguard"]' \
 seconds=86400 # Daily

Part 9: Troubleshooting Salt Deployments

Common Salt Issues

Issue 1: Minion Can’t Connect to Master

Symptoms: salt-key -L doesn’t show minion.

Solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# On minion, check logs
sudo journalctl -u salt-minion -f

# Common fixes:
# 1. Check firewall on master
sudo firewall-cmd --list-ports | grep -E "4505|4506"

# 2. Verify minion config
sudo cat /etc/salt/minion | grep master

# 3. Restart minion
sudo systemctl restart salt-minion

# 4. Check connectivity (telnet is not installed by default on AlmaLinux 10)
nc -zv <master-ip> 4505
nc -zv <master-ip> 4506

Issue 2: State Application Fails

Symptoms: State returns Failed: X.

Solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# View detailed output
sudo salt 'wireguard-srv' state.apply -l debug

# Check specific state
sudo salt 'wireguard-srv' state.sls wireguard test=True

# Verify pillar data
sudo salt 'wireguard-srv' pillar.get wireguard

# Check for syntax errors in states
python3 -c "import yaml; yaml.safe_load(open('/srv/salt/wireguard/init.sls'))"

Issue 3: Pillar Data Not Updating

Symptoms: Changes to pillar not reflected.

Solution:

1
2
3
4
5
6
7
8


# Refresh pillar on minions
sudo salt '*' saltutil.refresh_pillar

# Clear pillar cache
sudo salt '*' saltutil.clear_cache

# Verify pillar gets updated
sudo salt 'wireguard-srv' pillar.items

Issue 4: Docker State Fails on AlmaLinux 10

Symptoms: Docker won’t start or iptables errors.

Solution:

Ensure /etc/docker/daemon.json has:

1
2
3
4
5


{
 "iptables": false,
 "ip6tables": false,
 "storage-driver": "overlay2"
}

Then:

1
2


sudo salt 'wireguard-srv' service.restart docker
sudo salt 'wireguard-srv' cmd.run 'docker ps'

Salt Best Practices

Always test first: Use test=True before applying
Use version control: Store states in Git
Modular states: Keep states small and focused
Use pillars for sensitive data: Never hardcode passwords in states
Document your states: Add comments explaining what and why
Use requisites: Ensure proper ordering with require, watch, onchanges
Idempotent states: States should be safe to run multiple times
Monitor state runs: Set up logging and alerting

Part 10: Scaling to Multiple VPN Servers

One of Salt’s biggest advantages is easy scaling.

Deploy to Multiple Servers

Target multiple minions with patterns:

1
2
3
4
5
6
7
8


# Deploy to all VPN servers
sudo salt 'vpn-*' state.apply

# Deploy to servers in specific datacenter (using grains)
sudo salt -G 'datacenter:us-east' state.apply

# Deploy in batches (10 at a time)
sudo salt 'vpn-*' state.apply --batch-size 10

Load Balancing with Salt

Create /srv/pillar/vpn-servers.sls:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


vpn_servers:
 vpn-us-east-1:
 endpoint: "100.23.15.226"
 network: "10.99.0.0/24"
 vpn-us-west-1:
 endpoint: "198.51.100.50"
 network: "10.98.0.0/24"
 vpn-eu-central-1:
 endpoint: "203.0.113.75"
 network: "10.97.0.0/24"

Update states to use per-server pillar data:

1
2


# In wireguard/init.sls
Address = {{ salt['pillar.get']('vpn_servers:' + grains['id'] + ':network').split('/')[0] }}/24

Conclusion

Congratulations! You’ve mastered automating WireGuard VPN deployment with SaltStack. You can now:

✅ Deploy VPN servers with a single command ✅ Maintain consistent configuration across multiple servers ✅ Version control your infrastructure ✅ Scale to hundreds of VPN servers effortlessly ✅ Implement automated monitoring and backups ✅ Quickly respond to security updates ✅ Reduce human error in deployment

Key Advantages Recap

Manual Setup:

⏱️ 1-2 hours per server
🔄 Prone to configuration drift
📝 No audit trail
🚫 Difficult to scale

Salt Automation:

⏱️ 5-10 minutes for any number of servers
✅ Guaranteed consistency
📜 Complete version history
🚀 Infinitely scalable

Next Steps

Set up GitLab/GitHub CI/CD for automated testing of Salt states
Implement Salt monitoring with Prometheus and Grafana
Create custom execution modules for complex WireGuard operations
Set up Salt reactors for auto-healing
Explore Salt Cloud for automated cloud provisioning
Integrate with your existing configuration management workflow

Additional Resources

SaltStack Documentation
Salt Formulas Repository
Manual WireGuard Setup Guide (previous article)
WireGuard Official Docs
SaltStack Best Practices

Complete Repository Structure

Here’s the final directory structure for your Salt repository:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


/srv/salt/
├── top.sls
├── wireguard/
│ ├── init.sls
│ └── wg-easy.sls
├── firewall/
│ ├── init.sls
│ └── wireguard.sls
├── monitoring/
│ └── wireguard-check.sls
├── backup/
│ └── wireguard.sls
└── orchestrate/
 └── deploy-wireguard.sls

/srv/pillar/
├── top.sls
└── common.sls

You can find the complete Salt configuration examples in this article ready to use in production!

This guide was originally written and tested against Salt 3006 on AlmaLinux 10.1. It was updated in July 2026: Salt now installs from the Salt Project repositories (it is no longer available from EPEL on EL10, and 3008 is the current LTS branch); the Docker repo is added in a way that works under dnf5; the firewall states use a zone and a policy object instead of deprecated --direct rules; and the wg-easy state targets v15 using its INIT_* unattended-setup variables instead of the v14 PASSWORD_HASH model, which no longer exists.

Related Articles:

How to Setup and Secure WireGuard VPN with wg-easy on AlmaLinux 10 — the manual setup this article automates
Production-Grade SaltStack: Multi-Environment Setup with GitOps on AlmaLinux 10 — take the Salt tree here and give it environments and a GitOps workflow

Have questions about Salt or WireGuard automation? Drop a comment below!

Setup a Secure WireGuard VPN With wg-easy on AlmaLinux 10

Mon, 02 Feb 2026 18:00:00 +0300

WireGuard is a modern, fast, and secure VPN protocol that’s significantly simpler than traditional VPN solutions like OpenVPN or IPSec. In this comprehensive guide, you’ll learn how to set up a production-ready WireGuard VPN server on AlmaLinux 10, complete with the wg-easy web interface for easy peer management, proper firewall hardening, and configuration for both split tunnel and full tunnel modes.

What You’ll Learn

Installing and configuring WireGuard on AlmaLinux 10
Setting up firewalld for secure VPN operations
Deploying wg-easy web UI for graphical peer management
Understanding split tunnel vs full tunnel VPN configurations
Hardening your VPN server for production use
Managing VPN clients across different platforms

Prerequisites

Before we begin, ensure you have:

A server running AlmaLinux 10.1 or later
Root access to the server
A public IP address (e.g., 100.23.15.226)
Basic knowledge of Linux command line
Firewall port 51820/UDP accessible from the internet

This guide targets wg-easy v15, which is a ground-up rewrite. If you’re following an older tutorial that has you generating a bcrypt PASSWORD_HASH or setting WG_HOST and friends as environment variables, that’s v14 — those variables no longer do anything. Step 8 covers the difference and the migration path.

Understanding VPN Tunnel Modes

Before diving into installation, it’s crucial to understand the two main VPN tunnel modes and choose the right one for your use case.

Full Tunnel VPN

What it does: Routes ALL your internet traffic through the VPN server.

Benefits:

Your public IP appears as the VPN server’s IP address
All internet traffic is encrypted end-to-end
Ideal for privacy and security on public WiFi
Bypass geo-restrictions and censorship
Complete traffic anonymization

Use cases:

Working from coffee shops or airports
Accessing region-locked content
Maximum privacy protection
Protecting all device traffic

Configuration: Client uses AllowedIPs = 0.0.0.0/0, ::/0

Drawbacks:

Slightly slower internet speeds (all traffic routes through VPN)
Increased data usage on VPN server
May interfere with local network access

Split Tunnel VPN

What it does: Only routes specific network traffic through the VPN.

Benefits:

Faster general internet browsing (direct connection)
Lower data usage on VPN server
Access local network resources simultaneously
Better for accessing internal company resources

Use cases:

Accessing internal network services remotely
Connecting to private databases or applications
Maintaining local network printer/scanner access
Optimized performance for specific resources

Configuration: Client uses AllowedIPs = 10.99.0.0/24 (VPN network only)

Drawbacks:

Your public IP remains unchanged for non-VPN traffic
Less privacy protection for general internet usage
Requires careful routing configuration

Step 1: Update System and Install WireGuard

First, ensure your AlmaLinux 10 system is up to date and install WireGuard tools.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Update system packages
sudo dnf update -y

# Install EPEL repository (if not already installed)
sudo dnf install -y epel-release

# Install WireGuard and related tools
sudo dnf install -y wireguard-tools qrencode

# Verify installation
wg --version

Expected output (the exact version depends on what your repos currently ship — anything from the v1.0.x series is fine):

1

wireguard-tools v1.0.20250521

WireGuard itself is in the kernel on AlmaLinux 10, so wireguard-tools is the only userspace piece you need.

Step 2: Enable IP Forwarding

For VPN traffic routing to work, enable IP forwarding at the kernel level.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Enable IPv4 forwarding
echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.d/99-wireguard.conf

# Enable IPv6 forwarding (optional)
echo "net.ipv6.conf.all.forwarding=1" | sudo tee -a /etc/sysctl.d/99-wireguard.conf

# Enable source address validation (required for WireGuard)
echo "net.ipv4.conf.all.src_valid_mark=1" | sudo tee -a /etc/sysctl.d/99-wireguard.conf

# Apply changes
sudo sysctl -p /etc/sysctl.d/99-wireguard.conf

Verify settings:

1
2


sysctl net.ipv4.ip_forward
# Should return: net.ipv4.ip_forward = 1

Step 3: Configure Firewalld Security

AlmaLinux 10 uses firewalld for firewall management. Let’s configure it securely for WireGuard.

Install and Enable Firewalld

1
2
3
4
5
6
7
8
9


# Install firewalld (usually pre-installed)
sudo dnf install -y firewalld

# Start and enable firewalld
sudo systemctl enable --now firewalld

# Check status
sudo firewall-cmd --state
# Should return: running

Configure Firewall Rules

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


# Allow SSH (if not already allowed)
sudo firewall-cmd --permanent --add-service=ssh

# Allow WireGuard UDP port
sudo firewall-cmd --permanent --add-port=51820/udp

# Enable masquerading for NAT (required for VPN routing)
sudo firewall-cmd --permanent --zone=public --add-masquerade

# Give the tunnel its own zone rather than lumping it in with your LAN
sudo firewall-cmd --permanent --new-zone=wireguard
sudo firewall-cmd --permanent --zone=wireguard --add-interface=wg0

# Allow the tunnel to forward OUT to the public zone. This crosses zones, so it
# needs a policy object — see the note below.
sudo firewall-cmd --permanent --new-policy=wg-to-public
sudo firewall-cmd --permanent --policy=wg-to-public --add-ingress-zone=wireguard
sudo firewall-cmd --permanent --policy=wg-to-public --add-egress-zone=public
sudo firewall-cmd --permanent --policy=wg-to-public --set-target=ACCEPT

# Reload firewall to apply changes
sudo firewall-cmd --reload

# Verify rules
sudo firewall-cmd --list-all
sudo firewall-cmd --info-policy=wg-to-public

Why a policy object, and not --add-forward? This is the single easiest thing to get wrong. --add-forward enables intra-zone forwarding only — traffic between interfaces that are in the same zone. A full-tunnel VPN is the other case: packets arrive on wg0 (the wireguard zone) and leave on your NIC (the public zone), which is inter-zone. --add-forward does not cover that, and a zone whose target is default will not forward across zones — so a setup that puts wg0 in internal and calls --add-forward looks right, reloads cleanly, and still leaves your clients with a tunnel but no internet. Inter-zone forwarding is exactly what policy objects are for.

The older way to force this through was firewall-cmd --direct --add-rule ipv4 filter FORWARD .... Those rules still work, but the direct interface has been deprecated since firewalld 1.0 and is superseded by exactly the zones-and-policies model above. Only fall back to --direct on firewalld releases too old to have policy objects (pre-0.9).

A blunter alternative, if you don’t want a policy: put wg0 in the built-in trusted zone, whose target is ACCEPT — and per the firewalld man page, ACCEPT “allows traffic to be forwarded from the zone, either to the same zone or other zones.” It works, but it also means VPN clients can reach every port on the VPN server itself, which the policy above does not.

Expected output:

1
2
3
4
5


public (active)
 target: default
 services: ssh
 ports: 51820/udp
 masquerade: yes

Step 4: Generate WireGuard Server Keys

WireGuard uses asymmetric cryptography. Generate server keys securely.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# Create WireGuard configuration directory
sudo mkdir -p /etc/wireguard
sudo chmod 700 /etc/wireguard

# Generate server private key
wg genkey | sudo tee /etc/wireguard/server_private.key
sudo chmod 600 /etc/wireguard/server_private.key

# Generate server public key from private key
sudo cat /etc/wireguard/server_private.key | wg pubkey | sudo tee /etc/wireguard/server_public.key

# Display public key (save this - clients will need it)
cat /etc/wireguard/server_public.key

Step 5: Create WireGuard Server Configuration

Now create the main server configuration file. We’ll configure it for full tunnel mode by default.

1
2


# Create base configuration
sudo vim /etc/wireguard/wg0.conf

For Full Tunnel VPN (routes all client traffic):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


[Interface]
# Server VPN IP address
Address = 10.99.0.1/24

# UDP port WireGuard listens on
ListenPort = 51820

# Server private key
PrivateKey = <paste your server private key here>

# PostUp/PostDown rules for firewalld integration (runtime, zone-based)
PostUp = firewall-cmd --zone=public --add-masquerade
PostUp = firewall-cmd --zone=internal --add-interface=wg0
PostUp = firewall-cmd --zone=internal --add-forward
PostDown = firewall-cmd --zone=internal --remove-forward
PostDown = firewall-cmd --zone=internal --remove-interface=wg0
PostDown = firewall-cmd --zone=public --remove-masquerade

# Peer configurations will be added below
# Each client is a peer

Because Step 3 already wrote the equivalent rules with --permanent, these hooks are belt-and-braces — they keep the runtime firewall correct if someone reloads firewalld while the tunnel is down. Drop them if you prefer to manage the firewall purely declaratively.

Replace <paste your server private key here> with the contents of /etc/wireguard/server_private.key.

Set proper permissions:

1

sudo chmod 600 /etc/wireguard/wg0.conf

Step 6: Enable and Start WireGuard Service

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Enable WireGuard service
sudo systemctl enable wg-quick@wg0

# Start WireGuard service
sudo systemctl start wg-quick@wg0

# Check status
sudo systemctl status wg-quick@wg0

# Verify WireGuard interface
sudo wg show

Expected output:

1
2
3
4


interface: wg0
 public key: <your server public key>
 private key: (hidden)
 listening port: 51820

Step 7: Install Docker for wg-easy Web UI

wg-easy provides a modern web interface for managing WireGuard peers. We’ll install Docker to run it.

Important — pick one WireGuard server, not two. wg-easy runs its own WireGuard interface inside the container and binds UDP/51820 itself. If you completed Steps 4–6, the host’s wg-quick@wg0 already owns that port, and the container will fail to start with an “address already in use” error. Before continuing, stop and disable the manual tunnel:
1
sudo systemctl disable --now wg-quick@wg0
Steps 4–6 are still worth reading — they show what wg-easy automates for you, and they’re the path to take if you’d rather manage peers by hand. Just don’t run both at once. (If you genuinely need both, give each a different ListenPort.)

Install Docker CE on AlmaLinux 10

AlmaLinux 10 requires Docker CE from the official Docker repository.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# Install the config-manager plugin (AlmaLinux 10 ships dnf5)
sudo dnf install -y dnf5-plugins

# Add Docker CE repository
sudo dnf config-manager addrepo --from-repofile=https://download.docker.com/linux/centos/docker-ce.repo

# Install Docker packages
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Start and enable Docker
sudo systemctl enable --now docker

# Verify Docker installation
sudo docker --version

--add-repo is gone on AlmaLinux 10. AlmaLinux 10 ships dnf5, where config-manager grew a proper addrepo subcommand and the old dnf config-manager --add-repo <url> flag was removed — it now fails with Unknown argument "--add-repo". Older guides (and Docker’s own EL instructions) still show the DNF 4 form. If you’d rather skip the plugin entirely, dropping the repo file in place works on any release:
1
2
sudo curl -fsSL https://download.docker.com/linux/centos/docker-ce.repo \
 -o /etc/yum.repos.d/docker-ce.repo

A word on Docker and nftables

AlmaLinux 10 uses nftables, and you’ll find plenty of guides telling you to set "iptables": false in /etc/docker/daemon.json on that basis. Don’t — not for this setup. Docker’s iptables and ip6tables commands are symlinked to iptables-nft, so its rules are translated into nftables for you and everything works out of the box. Turning Docker’s firewall management off only makes sense when every container runs with network_mode: host; it breaks NAT and published ports for containers on a bridge network, which is exactly what the wg-easy compose file below uses. Leave the default alone and you don’t need a daemon.json at all.

1
2


# Verify Docker is running
sudo docker ps

If you’re on Docker Engine 29 or newer and want to skip the iptables compatibility layer, there is now an experimental native nftables backend ("firewall-backend": "nftables" in daemon.json). It’s optional, and not required for anything in this guide — see the Docker nftables documentation.

Step 8: Deploy wg-easy Web UI

Now deploy the wg-easy container for graphical peer management.

First, know which wg-easy you’re running

This matters more than anything else in this step. wg-easy v15 is a complete rewrite, and it threw out the configuration model that every older tutorial (including the first version of this guide) depends on:

v14 and earlier	v15 and later
`PASSWORD_HASH` bcrypt hash, generated with `docker run ... wgpw`	Admin account created in a web setup wizard on first run
`WG_HOST`, `WG_PORT`, `WG_DEFAULT_ADDRESS`, `WG_DEFAULT_DNS`, `WG_ALLOWED_IPS`, `WG_MTU`, `WG_PERSISTENT_KEEPALIVE`	Configured in the Admin Panel, stored in a SQLite database
Config in `wg0.json`	Config in a SQLite DB under `/etc/wireguard`
`network_mode: host` typical	Bridge network with published ports

The wgpw subcommand and the WG_* environment variables are simply gone in v15 — they are silently ignored, which is a confusing way to fail.

Watch out for the latest tag here. At the time of writing it still resolves to v14, not v15 — upstream deliberately held it back because v15 breaks existing installs. So image: ghcr.io/wg-easy/wg-easy:latest does not mean “v15 today”, and it does not mean “v14 forever” either: the day that tag is moved, an unpinned docker compose pull silently swaps your VPN’s entire configuration model. That is the real argument for pinning. The instructions below pin 15 explicitly, so you get patch and minor updates within v15 and a future v16 can’t surprise you.

Create wg-easy Docker Compose File

1
2
3
4
5
6


# Create directory for wg-easy
sudo mkdir -p /opt/wg-easy
cd /opt/wg-easy

# Create docker-compose.yml
sudo vim docker-compose.yml

This is upstream’s recommended v15 compose file, with one addition (INSECURE, explained below):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


volumes:
 etc_wireguard:

services:
 wg-easy:
 image: ghcr.io/wg-easy/wg-easy:15
 container_name: wg-easy
 environment:
 # Allow logging in over plain HTTP. See the warning below.
 - INSECURE=true
 networks:
 wg:
 ipv4_address: 10.42.42.42
 ipv6_address: fdcc:ad94:bacf:61a3::2a
 volumes:
 - etc_wireguard:/etc/wireguard
 - /lib/modules:/lib/modules:ro
 ports:
 - "51820:51820/udp"
 - "51821:51821/tcp"
 restart: unless-stopped
 cap_add:
 - NET_ADMIN
 - SYS_MODULE
 sysctls:
 - net.ipv4.ip_forward=1
 - net.ipv4.conf.all.src_valid_mark=1
 - net.ipv6.conf.all.disable_ipv6=0
 - net.ipv6.conf.all.forwarding=1
 - net.ipv6.conf.default.forwarding=1

networks:
 wg:
 driver: bridge
 enable_ipv6: true
 ipam:
 driver: default
 config:
 - subnet: 10.42.42.0/24
 - subnet: fdcc:ad94:bacf:61a3::/64

Important notes:

There is no version: key. Compose v2 ignores it and warns that it’s obsolete.
There is no server IP, VPN subnet, or DNS setting here any more — you’ll set those in the setup wizard. The 10.42.42.0/24 block above is the container’s Docker network, not your VPN subnet.
The sysctls: block is what makes forwarding work inside the container. It does not replace the host-level forwarding you enabled in Step 2.

About `INSECURE=true`

v15 refuses to let you log in over plain HTTP — you’ll get “You can’t log in with an insecure connection. Use HTTPS.” Setting INSECURE=true re-enables HTTP so you can reach the UI at http://<server-ip>:51821 and finish the wizard.

That is fine for a first run on a trusted network, but your admin password crosses the internet in the clear. For anything long-lived, drop INSECURE and put the UI behind a reverse proxy with a real TLS certificate, or restrict port 51821 to your own IP (Step 11) and reach it over an SSH tunnel.

Allow wg-easy Web UI Port

1
2
3


# Allow web UI port through firewall
sudo firewall-cmd --permanent --add-port=51821/tcp
sudo firewall-cmd --reload

Start wg-easy

1
2
3
4
5
6
7
8


# Start wg-easy container
sudo docker compose up -d

# Check container status
sudo docker ps

# View logs
sudo docker logs wg-easy

Expected output:

1
2


CONTAINER ID IMAGE STATUS
abc123def456 ghcr.io/wg-easy/wg-easy:15 Up 30 seconds (healthy)

Use docker compose up / docker compose down to manage the container — upstream specifically warns against docker compose start / stop on v15, which can leave its state inconsistent.

Create Systemd Service for wg-easy

For automatic startup on boot:

1
2


# Create systemd service
sudo vim /etc/systemd/system/wg-easy.service

Add the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


[Unit]
Description=WireGuard Easy Web UI
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/wg-easy
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

Enable the service:

1
2
3
4
5
6
7
8


# Reload systemd
sudo systemctl daemon-reload

# Enable wg-easy service
sudo systemctl enable wg-easy

# Check status
sudo systemctl status wg-easy

Step 9: Access wg-easy Web Interface

Open your browser and navigate to:

1

http://100.23.15.226:51821

(Replace with your server’s IP)

Complete the Setup Wizard

On a fresh v15 install you are met by a setup wizard, not a login prompt. There is no pre-seeded password — you create the admin account here. Walk through it and set:

Admin username and password — this replaces the old PASSWORD_HASH variable
Host / public endpoint — your server’s public IP or DNS name (e.g. 100.23.15.226), which is what clients will connect to. This replaces WG_HOST.
VPN subnet — 10.99.0.0/24 to match the rest of this guide. This replaces WG_DEFAULT_ADDRESS.
Client DNS — e.g. 1.1.1.1. This replaces WG_DEFAULT_DNS.

Everything else (MTU, keepalive, allowed IPs) lives in Admin Panel → Settings once you’re in, and can be changed later without touching the compose file.

Migrating an existing v14 install? Back up its wg0.json first, then upload it when the wizard offers to import an existing configuration. v14 environment variables are not migrated automatically.

Add Your First VPN Client

Click "+ New" button
Enter a client name (e.g., “john-laptop”)
The web UI automatically:
- Generates client keys
- Assigns an IP address (10.99.0.10, 10.99.0.11, etc.)
- Creates the configuration
- Generates a QR code
For mobile devices: Scan the QR code with the WireGuard app
For desktop/laptop: Click “Download” to get the configuration file

Step 10: Configure VPN Clients

Mobile Clients (iOS/Android)

iOS:

Install WireGuard from App Store
Tap “+” → “Create from QR code”
Scan the QR code from wg-easy
Toggle connection on

Android:

Install WireGuard from Play Store
Tap “+” → “Scan from QR code”
Scan the QR code from wg-easy
Toggle connection on

Desktop/Laptop Clients

Linux:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


# Install WireGuard
sudo dnf install wireguard-tools # RHEL/AlmaLinux
sudo apt install wireguard # Ubuntu/Debian

# Copy configuration from wg-easy
sudo vim /etc/wireguard/wg0.conf
# Paste the downloaded configuration

# Set permissions
sudo chmod 600 /etc/wireguard/wg0.conf

# Start VPN
sudo wg-quick up wg0

# Enable on boot (optional)
sudo systemctl enable wg-quick@wg0

# Check status
sudo wg show

macOS:

Install WireGuard from App Store
Click “Import Tunnel(s) from File”
Select downloaded .conf file
Toggle connection on

Windows:

Download WireGuard for Windows
Click “Import Tunnel(s) from File”
Select downloaded .conf file
Click “Activate”

Verify VPN Connection

Once connected, verify your setup:

1
2
3
4
5
6
7
8
9


# Check your public IP (should show VPN server IP for full tunnel)
curl ifconfig.me

# Ping VPN server
ping 10.99.0.1

# Check VPN interface
ip addr show wg0 # Linux
ifconfig utun3 # macOS

For full tunnel: curl ifconfig.me should return your VPN server’s IP (100.23.15.226)

For split tunnel: curl ifconfig.me returns your original IP, but you can access VPN network (10.99.0.0/24)

Step 11: Security Hardening Best Practices

1. Use Strong Passwords

1
2


# Generate strong password for wg-easy
openssl rand -base64 32

2. Implement Fail2ban for SSH Protection

1
2
3
4
5
6
7
8


# Install fail2ban
sudo dnf install -y fail2ban

# Enable and start
sudo systemctl enable --now fail2ban

# Check status
sudo fail2ban-client status sshd

3. Regular Security Updates

1
2


# Create update script
sudo vim /usr/local/bin/security-updates.sh

Add:

1
2
3
4
5


#!/bin/bash
set -euo pipefail
dnf update -y
cd /opt/wg-easy && docker compose pull && docker compose up -d
docker image prune -f

Because the compose file pins wg-easy:15, this pulls patch and minor updates within v15 but will never jump you across a breaking major release. Read the release notes before bumping that tag.

1
2
3
4
5


# Make executable
sudo chmod +x /usr/local/bin/security-updates.sh

# Add to crontab (weekly updates)
sudo crontab -e

Add line:

1

0 3 * * 0 /usr/local/bin/security-updates.sh >> /var/log/security-updates.log 2>&1

4. Monitor VPN Activity

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Check active connections
sudo wg show

# View WireGuard logs
sudo journalctl -u wg-quick@wg0 -f

# View wg-easy logs
sudo docker logs -f wg-easy

# Check firewall logs
sudo journalctl -u firewalld -f

5. Backup WireGuard Configuration

1
2
3
4
5


# Create backup
sudo tar -czf wireguard-backup-$(date +%Y%m%d).tar.gz /etc/wireguard/ /opt/wg-easy/

# Copy to safe location
scp wireguard-backup-*.tar.gz user@backup-server:/backups/

6. Limit wg-easy Web UI Access

Only allow access from specific IPs:

1
2
3
4
5
6
7
8


# Allow only from specific IP
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="YOUR_IP/32" port protocol="tcp" port="51821" accept'

# Remove general port rule
sudo firewall-cmd --permanent --remove-port=51821/tcp

# Reload
sudo firewall-cmd --reload

Step 12: Switching Between Tunnel Modes

To switch from full tunnel to split tunnel (or vice versa):

Update wg-easy Configuration

On v15 this is a web-UI change, not a compose-file change — there is no WG_ALLOWED_IPS variable any more. Go to Admin Panel → Settings and edit the default Allowed IPs:

Full tunnel: 0.0.0.0/0, ::/0
Split tunnel: 10.99.0.0/24

Save, and no container restart is needed. Note that this sets the default for newly created clients; existing clients keep the value they were issued, so update them using one of the two options below.

Update Existing Clients

Option 1: Re-generate client configs in wg-easy

Delete old client from web UI
Re-add client (new config will use updated tunnel mode)
Re-deploy configuration to client

Option 2: Manually edit client configuration

Edit the AllowedIPs line in client config:

1
2
3
4
5
6
7


[Peer]
PublicKey = <server public key>
Endpoint = 100.23.15.226:51820
AllowedIPs = 0.0.0.0/0, ::/0 # Full tunnel
# OR
AllowedIPs = 10.99.0.0/24 # Split tunnel
PersistentKeepalive = 25

Reconnect to apply changes.

Troubleshooting Common Issues

Issue 1: VPN Connects but No Internet Access

Symptoms: Connected to VPN but can’t browse internet.

Solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# Check IP forwarding
sysctl net.ipv4.ip_forward
# Should return: net.ipv4.ip_forward = 1

# Check masquerading
sudo firewall-cmd --zone=public --query-masquerade
# Should return: yes

# Check forwarding is allowed in the zone holding wg0
sudo firewall-cmd --zone=internal --query-forward
# Should return: yes

# Restart WireGuard
sudo systemctl restart wg-quick@wg0

If you’re running wg-easy rather than the manual tunnel, the container handles its own forwarding via the sysctls: block — check sudo docker logs wg-easy instead, and confirm host forwarding is on (Step 2).

Issue 2: wg-easy Container Keeps Restarting

Symptoms: docker ps shows “Restarting” status.

Solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# Check container logs
sudo docker logs wg-easy

# Common issues on v15:
# - UDP/51820 already in use by a host wg-quick@wg0 (see Step 7)
# - Missing cap_add: NET_ADMIN / SYS_MODULE
# - /lib/modules not mounted read-only into the container
# - Following a v14 tutorial: PASSWORD_HASH and WG_* vars do nothing on v15

# Rebuild container
cd /opt/wg-easy
sudo docker compose down
sudo docker compose up -d

If the port is the problem, confirm what already holds it:

1

sudo ss -ulnp | grep 51820

Issue 3: Can’t Connect to wg-easy Web UI

Symptoms: Browser shows “connection refused” on port 51821.

Solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# Check if port is open
sudo firewall-cmd --list-ports | grep 51821

# If not, add it
sudo firewall-cmd --permanent --add-port=51821/tcp
sudo firewall-cmd --reload

# Check Docker is running
sudo docker ps | grep wg-easy

# Check if port is listening
sudo ss -tulnp | grep 51821

Issue 4: DNS Not Working on VPN

Symptoms: Can ping IP addresses but not domain names.

Solution:

Update the client DNS servers in Admin Panel → Settings (on v14 this was the WG_DEFAULT_DNS variable), then re-issue the client config — for example:

1

1.1.1.1, 8.8.8.8, 9.9.9.9

Or fix it directly in an existing client config:

1
2


[Interface]
DNS = 1.1.1.1, 8.8.8.8

Issue 5: Firewall Blocks VPN Traffic

Symptoms: VPN connects but traffic is blocked.

Solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# Check firewall rules
sudo firewall-cmd --list-all

# Re-apply WireGuard rules
sudo firewall-cmd --permanent --zone=public --add-masquerade
sudo firewall-cmd --permanent --zone=internal --add-interface=wg0
sudo firewall-cmd --permanent --zone=internal --add-forward
sudo firewall-cmd --reload

# Check SELinux (if enabled)
sudo getenforce
# If "Enforcing", check audit logs:
sudo ausearch -m avc -ts recent | grep wireguard

Performance Optimization

Optimize MTU Settings

MTU lives in Admin Panel → Settings on v15 (it was the WG_MTU variable on v14). The default is 1420. If you see packet loss or stalled TLS handshakes over the tunnel — the classic symptom of MTU trouble — try 1400, then 1380.

Enable BBR Congestion Control

1
2
3
4


# Enable BBR for better throughput
echo "net.core.default_qdisc=fq" | sudo tee -a /etc/sysctl.d/99-wireguard.conf
echo "net.ipv4.tcp_congestion_control=bbr" | sudo tee -a /etc/sysctl.d/99-wireguard.conf
sudo sysctl -p /etc/sysctl.d/99-wireguard.conf

Monitor Performance

1
2
3
4
5
6
7
8


# Check WireGuard statistics
sudo wg show wg0

# Monitor bandwidth
sudo iftop -i wg0

# Check connection quality
sudo wg show wg0 latest-handshakes

Maintenance Tasks

Daily/Weekly Checks

1
2
3
4
5
6
7
8
9


# Check service status
sudo systemctl status wg-quick@wg0
sudo systemctl status wg-easy

# View recent logs
sudo journalctl -u wg-quick@wg0 --since "1 hour ago"

# Check active peers
sudo wg show

Monthly Tasks

1
2
3
4
5
6
7
8
9


# Update system and Docker images
sudo dnf update -y
cd /opt/wg-easy && sudo docker compose pull && sudo docker compose up -d

# Review and remove unused peers
# (Via wg-easy web UI)

# Rotate logs (if needed)
sudo journalctl --vacuum-time=30d

Backup Configuration

Create automated backups:

1
2


# Create backup script
sudo vim /usr/local/bin/backup-wireguard.sh

Add:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


#!/bin/bash
BACKUP_DIR="/root/wireguard-backups"
DATE=$(date +%Y%m%d-%H%M%S)

mkdir -p $BACKUP_DIR
tar -czf $BACKUP_DIR/wireguard-$DATE.tar.gz \
 /etc/wireguard/ \
 /opt/wg-easy/ \
 /etc/docker/daemon.json

# Keep only last 7 backups
cd $BACKUP_DIR && ls -t | tail -n +8 | xargs -r rm

1
2
3
4
5


# Make executable
sudo chmod +x /usr/local/bin/backup-wireguard.sh

# Add to cron (daily at 2 AM)
echo "0 2 * * * /usr/local/bin/backup-wireguard.sh" | sudo crontab -

Conclusion

You now have a fully functional, secure WireGuard VPN server running on AlmaLinux 10 with:

✅ Modern WireGuard protocol for fast, secure VPN connections ✅ wg-easy web UI for easy peer management ✅ Firewalld hardening for production-grade security ✅ Flexible tunnel modes (full or split tunnel) ✅ Cross-platform support for all devices ✅ Automated management with systemd services

Key Takeaways

Full Tunnel: Best for privacy and security - routes all traffic through VPN
Split Tunnel: Best for performance - routes only specific traffic through VPN
Firewalld Integration: Essential for AlmaLinux 10 with nftables kernel
wg-easy Simplifies Management: Web UI makes peer management effortless
Regular Maintenance: Keep your VPN secure with updates and monitoring

Next Steps

Configure additional security measures (fail2ban, intrusion detection)
Set up automated monitoring and alerting
Implement log aggregation for better visibility
Consider setting up WireGuard on multiple servers for redundancy
Explore advanced routing configurations for specific use cases

Automate WireGuard VPN Setup on AlmaLinux 10 with SaltStack — once you’ve done this by hand, codify it
How to Self-Host NetBird VPN on AlmaLinux 10 With Caddy — a mesh-VPN alternative with SSO and proper TLS
How to Set Up a WireGuard VPN Server on Ubuntu 22.04 — the same tunnel on a Debian-family host

Resources

Have questions or run into issues? Drop a comment below, and I’ll be happy to help troubleshoot your WireGuard setup!

This guide was tested on AlmaLinux 10.1 (kernel 6.12) with wg-easy v15. Commands and configurations may vary slightly for other versions — in particular, wg-easy v14 and earlier use a completely different, environment-variable-based configuration model.

Wg-Easy on Citizix, The Best blog for Linux, Opensource, Devops, Cloud and all things awesome tech.

Automate WireGuard VPN on AlmaLinux 10 With SaltStack

What You’ll Learn

Why Use SaltStack for WireGuard?

Benefits of Infrastructure as Code

Prerequisites

Architecture Overview

Part 1: Setting Up Salt Infrastructure

Step 1: Install Salt Master

Step 2: Install Salt Minion on WireGuard Server(s)

Step 3: Accept Minion Keys

Step 4: Create Salt Directory Structure

Part 2: Creating Salt States for WireGuard

Understanding Salt States

State 1: WireGuard Installation and Configuration

State 2: Firewall Configuration

State 3: wg-easy Web UI Deployment

Part 3: Salt Pillar Configuration

Create Pillar Data

Refresh Pillar Data

Part 4: Salt Top File Configuration

Pick one: wireguard or wireguard.wg-easy

Part 5: Deploying WireGuard with Salt

Test Configuration First (Dry-Run)

Apply Configuration

Verify Deployment

Part 6: Managing Configuration Changes

Making Changes to Configuration

Change Tunnel Mode

Change VPN Network

Version Control with Git

Part 7: Advanced Salt Techniques

Targeting Specific Minions

Using Salt Orchestration

Salt Reactor for Auto-Healing

Custom Salt Modules

Part 8: Monitoring and Maintenance

Salt-Based Monitoring

Automated Backups with Salt

Part 9: Troubleshooting Salt Deployments

Common Salt Issues

Issue 1: Minion Can’t Connect to Master

Issue 2: State Application Fails

Issue 3: Pillar Data Not Updating

Issue 4: Docker State Fails on AlmaLinux 10

Salt Best Practices

Part 10: Scaling to Multiple VPN Servers

Deploy to Multiple Servers

Load Balancing with Salt

Conclusion

Key Advantages Recap

Next Steps

Additional Resources

Complete Repository Structure

Setup a Secure WireGuard VPN With wg-easy on AlmaLinux 10

What You’ll Learn

Prerequisites

Understanding VPN Tunnel Modes

Full Tunnel VPN

Split Tunnel VPN

Step 1: Update System and Install WireGuard

Step 2: Enable IP Forwarding

Step 3: Configure Firewalld Security

Install and Enable Firewalld

Configure Firewall Rules

Step 4: Generate WireGuard Server Keys

Step 5: Create WireGuard Server Configuration

Step 6: Enable and Start WireGuard Service

Step 7: Install Docker for wg-easy Web UI

Install Docker CE on AlmaLinux 10

A word on Docker and nftables

Step 8: Deploy wg-easy Web UI

First, know which wg-easy you’re running

Create wg-easy Docker Compose File

About INSECURE=true

Allow wg-easy Web UI Port

Start wg-easy

Create Systemd Service for wg-easy

Step 9: Access wg-easy Web Interface

Complete the Setup Wizard

Pick one: `wireguard` or `wireguard.wg-easy`

About `INSECURE=true`