From b0ddd85c3e0e7b888467094e0641c9de2221e6c9 Mon Sep 17 00:00:00 2001 From: SPetrakis Date: Sun, 28 Jun 2026 21:48:54 +0300 Subject: [PATCH] docs: document client groups --- README.md | 1 + docs/content/guides/admin.md | 4 + docs/content/guides/client-groups.md | 150 +++++++++++++++++++++++++++ docs/content/guides/clients.md | 10 ++ docs/zensical.toml | 3 + 5 files changed, 168 insertions(+) create mode 100644 docs/content/guides/client-groups.md diff --git a/README.md b/README.md index 7da64f43..05eadddc 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ You have found the easiest way to install & manage WireGuard on any Linux host! - CIDR support - 2FA support - Per-client firewall filtering (requires iptables) +- Client groups with composable Allowed IP, DNS, and firewall policies. > [!NOTE] > To better manage documentation for this project, it has its own site here: [https://wg-easy.github.io/wg-easy/latest](https://wg-easy.github.io/wg-easy/latest) diff --git a/docs/content/guides/admin.md b/docs/content/guides/admin.md index 5f3d0572..a3001b3a 100644 --- a/docs/content/guides/admin.md +++ b/docs/content/guides/admin.md @@ -10,6 +10,8 @@ Enable server-side firewall filtering to enforce network access restrictions per When enabled, each client can have custom "Firewall Allowed IPs" configured that restrict which destinations they can access through the VPN. These restrictions are enforced by the server using iptables/ip6tables and cannot be bypassed by the client. +Client Groups can also define Firewall IP policies. Group Firewall IP policies use the same Per-Client Firewall setting and are ignored while this feature is disabled. + /// warning | Experimental Feature This feature is currently experimental. While functional, it should be thoroughly tested in your environment before relying on it for production security requirements. Always verify that firewall rules are working as expected using test traffic or by manually inspecting the rules. @@ -42,4 +44,6 @@ Most Linux distributions include iptables by default. If you're running in a min 3. Specify allowed destinations (IPs, subnets, ports) for that client 4. Server enforces these rules automatically +See [Client Groups](./client-groups.md) for grouped policy behavior. + See [Edit Client → Firewall Allowed IPs](./clients.md#firewall-allowed-ips) for detailed configuration syntax and examples. diff --git a/docs/content/guides/client-groups.md b/docs/content/guides/client-groups.md new file mode 100644 index 00000000..82f25eac --- /dev/null +++ b/docs/content/guides/client-groups.md @@ -0,0 +1,150 @@ +--- +title: Client Groups +--- + +Client Groups allow administrators to assign a client to zero, one, or multiple groups and manage shared client policy values centrally. + +Groups can define policy values for: + +- **Allowed IPs** +- **DNS** +- **Firewall IPs** + +Each policy field is resolved independently. A group can manage one field without managing the others. + +## Supported Policies + +### Allowed IPs + +Allowed IPs control the routes written into the generated client configuration. + +They affect the `AllowedIPs` value that the WireGuard client receives. They do not, by themselves, prevent a user from editing their local WireGuard configuration. + +### DNS + +DNS controls the DNS servers written into the generated client configuration. + +### Firewall IPs + +Firewall IPs are enforced by the `wg-easy` server using firewall rules. + +/// note | Per-Client Firewall Required + +Firewall IP group policies are only available when **Per-Client Firewall** is enabled in the Admin Panel -> Interface settings. + +/// + +Use Firewall IPs when server-side access enforcement is required. + +## Policy Resolution + +A client can belong to multiple groups. For each policy field, `wg-easy` resolves the effective value as follows: + +1. Values from all assigned groups that define that field are combined. +2. Duplicate values are removed. +3. Group membership order and each group's internal value order determine the final order. +4. Global/default configuration is used only when none of the assigned groups defines that field. +5. Global values are not added to a non-empty group result. +6. While a client belongs to at least one group, its individual Allowed IPs, DNS, and Firewall IP values are not used. +7. Individual client values remain stored and become active again when all groups are removed. + +Example: + +```text +Customers group: +Allowed IPs: 10.77.0.0/16 +DNS: 1.1.1.1, 9.9.9.9 + +NAS Access group: +Allowed IPs: 172.20.1.33/32, 10.77.0.0/16 +DNS: 9.9.9.9, 8.8.8.8 +``` + +If the client is assigned to `Customers` first and `NAS Access` second, the generated configuration uses: + +```text +AllowedIPs = 10.77.0.0/16, 172.20.1.33/32 +DNS = 1.1.1.1, 9.9.9.9, 8.8.8.8 +``` + +`10.77.0.0/16` and `9.9.9.9` appear in both groups, but each duplicate is included only once. + +## Creating a Group + +Open **Groups** from the user menu. + +To create a group: + +1. Click **Create**. +2. Enter a group name. +3. Optionally enter a description. +4. Enable any policy field the group should manage. +5. Add at least one valid entry for each enabled policy field. +6. Save the group. + +If a policy field is disabled, that group does not contribute to that field. + +/// warning | Enabled Policies Require Values + +An enabled group policy must contain at least one valid entry. There is no separate "enabled but empty" policy state. + +/// + +## Editing a Group + +Open **Groups**, then select the group you want to edit. + +You can change the name, description, and policy values. Saving the group updates the effective policy for assigned clients the next time their configuration or firewall rules are generated. + +## Assigning Clients + +You can assign groups from two places. + +### While Creating a Client + +When creating a client, select one or more groups in the **Client Groups** section. + +The selected group order controls the order used when policy values are combined. + +### From the Client Edit Page + +Open a client and use the **Client Groups** section to add or remove groups. + +When a client belongs to at least one group, the individual Allowed IPs, DNS, and Firewall IP fields become read-only. The page shows the effective value from the assigned groups or, when no assigned group defines that field, the global/default value. + +Use **Save** to persist membership changes. Use **Revert** to return to the last saved client values and group assignments. + +## Group Membership Page + +Each group detail page includes a membership section. + +From this page you can: + +- Assign an existing client to the group. +- Remove a client from that group. + +Removing a client from one group only removes that one membership. It does not remove the client from other groups, and it never deletes the client. + +## Deleting Groups + +Deleting a group deletes the group and its memberships. + +Assigned clients remain intact. Memberships to other groups remain intact. After the group is deleted, each affected client's effective policy is recalculated from its remaining groups. If no remaining group defines a policy field, `wg-easy` uses the global/default value for that field. + +## Generated Configurations + +The effective policy is used consistently for: + +- Normal configuration downloads +- QR-code configurations +- One-time configuration links + +## Security Note + +/// warning | Use Firewall IPs for Server-Side Enforcement + +Allowed IPs in the client configuration are not a complete access-control mechanism because users may edit their local WireGuard configuration. + +Use Firewall IPs when server-side enforcement is required. The **Per-Client Firewall** feature must be enabled in the Admin Panel -> Interface settings, and you should verify that firewall rules work as expected in your deployment environment. + +/// diff --git a/docs/content/guides/clients.md b/docs/content/guides/clients.md index edb514e1..60ce2ac3 100644 --- a/docs/content/guides/clients.md +++ b/docs/content/guides/clients.md @@ -82,6 +82,16 @@ Which IPs will be routed to the client. The DNS server that the client will use. +## Client Groups + +Administrators can assign a client to one or more Client Groups. + +When a client belongs to at least one group, the client's individual **Allowed IPs**, **DNS**, and **Firewall Allowed IPs** fields may become read-only. The page shows the effective value from the assigned groups, or the global/default value when none of the assigned groups defines that field. + +Individual client values remain stored and become active again when all groups are removed. + +See [Client Groups](./client-groups.md) for group creation, assignment, ordering, and policy resolution details. + ## Advanced - **MTU**: The maximum transmission unit for the client. diff --git a/docs/zensical.toml b/docs/zensical.toml index 98a3a977..78741100 100644 --- a/docs/zensical.toml +++ b/docs/zensical.toml @@ -18,6 +18,9 @@ edit_uri = "edit/master/docs/content" docs_dir = "content/" +# Guide navigation is generated from docs/content/guides. +# Keep the Client Groups guide next to the Edit Client guide. + site_url = "https://wg-easy.github.io/wg-easy" [project.theme]