Skip to main content

Groups Management

This guide provides detailed information about managing groups in the WireGuard network management system.

What are Groups?​

Groups are logical collections of peers that share common characteristics, policies, or access requirements. They serve as the primary organizational unit for applying network policies and routes.

Key Concepts​

Group Membership​

  • Peers can belong to multiple groups simultaneously
  • Group membership is managed by administrators only
  • Adding/removing peers from groups is non-destructive (peers are not deleted)

Group Attachments​

Groups can have:

  • Policies: Traffic filtering rules applied on jump peers
  • Routes: External network destinations added to peer configurations

Automatic Application​

When a peer joins a group:

  • All attached policies are automatically applied
  • All attached routes are added to the peer's WireGuard configuration
  • Changes take effect within seconds via WebSocket notifications

Creating Groups​

Basic Group Creation​

curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "engineering-team",
    "description": "Engineering team members with full network access"
  }'

Naming Best Practices​

Good Names:

  • engineering-team
  • sales-department
  • database-servers
  • trusted-devices
  • guest-network

Avoid:

  • group1, group2 (not descriptive)
  • temp (unclear purpose)
  • test (ambiguous)

Description Guidelines​

Write clear descriptions that explain:

  • Purpose of the group
  • Who should be in it
  • What access it provides

Example:

{
  "name": "remote-developers",
  "description": "Remote development team with access to staging environment and office VPN"
}

Managing Group Membership​

Adding Peers​

Single Peer:

curl -X POST "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID/peers/$PEER_ID" \
  -H "Authorization: Bearer $TOKEN"

Multiple Peers:

#!/bin/bash
PEERS=("peer-1" "peer-2" "peer-3" "peer-4")

for PEER_ID in "${PEERS[@]}"; do
  echo "Adding $PEER_ID to group..."
  curl -X POST "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID/peers/$PEER_ID" \
    -H "Authorization: Bearer $TOKEN"
done

Removing Peers​

curl -X DELETE "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID/peers/$PEER_ID" \
  -H "Authorization: Bearer $TOKEN"

Important: Removing a peer from a group:

  • Removes attached policies from the peer
  • Removes attached routes from the peer's configuration
  • Does NOT delete the peer itself

Viewing Group Members​

# Get group details with member list
curl -H "Authorization: Bearer $TOKEN" \
  "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID" \
  | jq '.peer_ids'

Attaching Policies to Groups​

Attach a Policy​

curl -X POST "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID/policies/$POLICY_ID" \
  -H "Authorization: Bearer $TOKEN"

View Attached Policies​

curl -H "Authorization: Bearer $TOKEN" \
  "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID/policies"

Detach a Policy​

curl -X DELETE "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID/policies/$POLICY_ID" \
  -H "Authorization: Bearer $TOKEN"

Policy Order Matters​

When multiple policies are attached to a group:

  1. Rules are applied in the order policies were attached
  2. First matching rule wins
  3. Default deny applies if no rules match

Example:

# Attach policies in order
curl -X POST "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID/policies/$ALLOW_POLICY" \
  -H "Authorization: Bearer $TOKEN"

curl -X POST "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID/policies/$DENY_POLICY" \
  -H "Authorization: Bearer $TOKEN"

Attaching Routes to Groups​

Attach a Route​

curl -X POST "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID/routes/$ROUTE_ID" \
  -H "Authorization: Bearer $TOKEN"

View Attached Routes​

curl -H "Authorization: Bearer $TOKEN" \
  "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID/routes"

Detach a Route​

curl -X DELETE "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID/routes/$ROUTE_ID" \
  -H "Authorization: Bearer $TOKEN"

Common Group Patterns​

Pattern 1: Department-Based Groups​

Organize by organizational structure:

# Create department groups
curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -d '{"name": "engineering", "description": "Engineering department"}'

curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -d '{"name": "sales", "description": "Sales department"}'

curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -d '{"name": "support", "description": "Customer support"}'

Pattern 2: Role-Based Groups​

Organize by job function:

# Create role groups
curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -d '{"name": "developers", "description": "Software developers"}'

curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -d '{"name": "admins", "description": "System administrators"}'

curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -d '{"name": "viewers", "description": "Read-only access"}'

Pattern 3: Environment-Based Groups​

Organize by environment access:

# Create environment groups
curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -d '{"name": "production-access", "description": "Production environment access"}'

curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -d '{"name": "staging-access", "description": "Staging environment access"}'

curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -d '{"name": "development-access", "description": "Development environment access"}'

Pattern 4: Security Level Groups​

Organize by trust level:

# Create security level groups
curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -d '{"name": "trusted", "description": "Fully trusted devices"}'

curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -d '{"name": "standard", "description": "Standard security devices"}'

curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -d '{"name": "restricted", "description": "Restricted access devices"}'

curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
  -d '{"name": "quarantine", "description": "Isolated/compromised devices"}'

Advanced Group Management​

Bulk Operations Script​

#!/bin/bash
# bulk-group-operations.sh

API_URL="https://your-server/api/v1"
TOKEN="your-token"
NETWORK_ID="your-network-id"

# Function to create group
create_group() {
  local name=$1
  local description=$2
  
  curl -X POST "$API_URL/networks/$NETWORK_ID/groups" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"name\": \"$name\", \"description\": \"$description\"}" \
    | jq -r '.id'
}

# Function to add peers to group
add_peers_to_group() {
  local group_id=$1
  shift
  local peers=("$@")
  
  for peer_id in "${peers[@]}"; do
    curl -X POST "$API_URL/networks/$NETWORK_ID/groups/$group_id/peers/$peer_id" \
      -H "Authorization: Bearer $TOKEN"
  done
}

# Example usage
ENGINEERING_GROUP=$(create_group "engineering" "Engineering team")
add_peers_to_group "$ENGINEERING_GROUP" "peer-1" "peer-2" "peer-3"

Group Audit Script​

#!/bin/bash
# audit-groups.sh

# List all groups with member counts
curl -H "Authorization: Bearer $TOKEN" \
  "$API_URL/networks/$NETWORK_ID/groups" \
  | jq -r '.[] | "\(.name): \(.peer_ids | length) members"'

# Detailed group report
curl -H "Authorization: Bearer $TOKEN" \
  "$API_URL/networks/$NETWORK_ID/groups" \
  | jq -r '.[] | "Group: \(.name)\nMembers: \(.peer_ids | length)\nPolicies: \(.policy_ids | length)\nRoutes: \(.route_ids | length)\n"'

Group Cleanup Script​

#!/bin/bash
# cleanup-empty-groups.sh

# Find and delete groups with no members
curl -H "Authorization: Bearer $TOKEN" \
  "$API_URL/networks/$NETWORK_ID/groups" \
  | jq -r '.[] | select(.peer_ids | length == 0) | .id' \
  | while read group_id; do
      echo "Deleting empty group: $group_id"
      curl -X DELETE "$API_URL/networks/$NETWORK_ID/groups/$group_id" \
        -H "Authorization: Bearer $TOKEN"
    done

Troubleshooting​

Problem: Can't Create Group​

Symptoms:

  • HTTP 400 Bad Request
  • Error: "group name already exists"

Solutions:

  1. Check for duplicate names:
curl -H "Authorization: Bearer $TOKEN" \
  "$API_URL/networks/$NETWORK_ID/groups" \
  | jq -r '.[].name'
  1. Use a different name or update existing group

Problem: Can't Add Peer to Group​

Symptoms:

  • HTTP 404 Not Found
  • Peer not appearing in group

Solutions:

  1. Verify peer exists:
curl -H "Authorization: Bearer $TOKEN" \
  "$API_URL/networks/$NETWORK_ID/peers/$PEER_ID"
  1. Verify group exists:
curl -H "Authorization: Bearer $TOKEN" \
  "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID"
  1. Check network ID matches

Problem: Policies Not Applied After Adding to Group​

Symptoms:

  • Peer added to group but traffic not filtered
  • iptables rules not present on jump peer

Solutions:

  1. Verify policy is attached to group:
curl -H "Authorization: Bearer $TOKEN" \
  "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID/policies"
  1. Check jump peer agent status:
systemctl status wireguard-agent
  1. Check iptables on jump peer:
iptables -L -n -v
  1. Check WebSocket connection:
journalctl -u wireguard-agent | grep -i websocket

Problem: Routes Not Applied After Adding to Group​

Symptoms:

  • Peer added to group but can't reach route destination
  • AllowedIPs not updated

Solutions:

  1. Verify route is attached to group:
curl -H "Authorization: Bearer $TOKEN" \
  "$API_URL/networks/$NETWORK_ID/groups/$GROUP_ID/routes"
  1. Check WireGuard configuration:
wg show

  1. Verify AllowedIPs includes route CIDR

  2. Check jump peer is online and reachable

Best Practices​

1. Plan Your Group Structure​

Before creating groups, plan:

  • How will you organize peers?
  • What access patterns do you need?
  • How will groups scale as you grow?

2. Use Consistent Naming​

Establish naming conventions:

  • Use lowercase with hyphens: engineering-team
  • Include purpose: prod-database-access
  • Avoid abbreviations unless standard

3. Document Group Purpose​

Always include descriptions:

  • What is the group for?
  • Who should be in it?
  • What access does it provide?

4. Regular Audits​

Schedule regular reviews:

  • Monthly: Review group memberships
  • Quarterly: Audit attached policies and routes
  • Annually: Restructure if needed

5. Principle of Least Privilege​

  • Start with minimal access
  • Add permissions as needed
  • Remove unused groups
  • Review and revoke unnecessary access

6. Use Default Groups Wisely​

  • Keep default groups simple
  • Provide baseline access only
  • Don't over-provision
  • Review default group policies regularly

7. Monitor Group Changes​

  • Log all group modifications
  • Track who makes changes
  • Review audit logs regularly
  • Alert on suspicious changes