> For the complete documentation index, see [llms.txt](https://docs.sendman.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sendman.com/admin-portal/settings/network-connections/wireguard.md).

# WireGuard

Connect a local network to Sendman with a WireGuard tunnel

This guide uses the example address plan from [Network Connections](/admin-portal/settings/network-connections.md#address-plan):

| Purpose                        | Example              |
| ------------------------------ | -------------------- |
| Sendman tunnel address         | `169.254.100.5/30`   |
| Your gateway's tunnel address  | `169.254.100.6/30`   |
| Your local network             | `10.20.0.0/24`       |
| Your gateway's public endpoint | `203.0.113.20:51820` |

## Prepare the keys

A WireGuard tunnel needs two key pairs: one for your gateway and one for Sendman's side of this connection. Generate both with trusted WireGuard tooling on your own system, for example:

```bash
wg genkey | tee sendman.key | wg pubkey > sendman.pub
```

* `sendman.key` is **Sendman's private key**. You enter it in the portal.
* `sendman.pub` is **Sendman's public key**. You enter it on your gateway.
* Your gateway's own key pair stays on your gateway. Only its public key is entered in the portal.

{% hint style="warning" %}
Use a separate key pair for every connection. Delete the private key file once it has been entered in the portal; it is stored as a secret and never displayed again.
{% endhint %}

## Choose how the tunnel is set up

| Connection setup                             | Requirements                                                                                                                                                                                       |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sendman dials your gateway** (recommended) | Your gateway has a public IPv4 address and a UDP port that is reachable from the internet. Nothing has to be opened towards Sendman.                                                               |
| **Your gateway dials Sendman**               | Your gateway connects to Sendman's public address on a listen port assigned to this connection. Useful if your gateway has no public address. Only available if your instance offers listen ports. |

## Create the connection in the portal

1. Go to **Settings → Network Connections**, click **Add connection** and choose **WireGuard**.
2. **General:** enter a **Name**, e.g. `Headquarters`. The connection id is generated from it and cannot be changed later.
3. **Tunnel:**

   * **Tunnel address:** Sendman's tunnel address, e.g. `169.254.100.5/30`
   * **Connection setup:** see above
   * **Listen port:** only for *Your gateway dials Sendman*. Select one of the free UDP ports.
   * **MTU:** keep the default of `1420` unless your uplink requires a smaller value.
   * **WireGuard private key:** the content of `sendman.key`

   <figure><img src="https://1641814212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4EVg4twS3gtObqtkynsm%2Fuploads%2Fgit-blob-1d6d4b730096b028e025ab53d3253124ec1e180c%2Fnetwork-connections-wizard-tunnel.png?alt=media" alt="WireGuard wizard, tunnel step" width="563"><figcaption></figcaption></figure>
4. **Routing:**

   * **Peer setup:** **Single peer** for one site
   * **Peer public key:** the public key of your gateway
   * **Peer endpoint:** your gateway's public address and port, e.g. `203.0.113.20:51820`. Required if Sendman dials your gateway, optional otherwise.
   * **Customer subnets:** your local networks that shall reach Sendman, comma-separated, e.g. `10.20.0.0/24`

   <figure><img src="https://1641814212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4EVg4twS3gtObqtkynsm%2Fuploads%2Fgit-blob-0100624c4a591579f6cb3d354a0edb6a254230e3%2Fnetwork-connections-wizard-routing.png?alt=media" alt="WireGuard wizard, routing step" width="563"><figcaption></figcaption></figure>
5. Save the connection.

{% hint style="info" %}
With **Multiple sites**, one connection serves several sites with their own peers. For each peer, enter its **Public key**, **Allowed IPs** (the site's networks) and optionally its **Endpoint**. A network must not be listed for more than one peer.
{% endhint %}

## Configure your gateway

Configure the WireGuard peer on your gateway. The following example shows the settings in `wg-quick` notation; use the corresponding fields of your firewall or router.

{% tabs %}
{% tab title="Sendman dials your gateway" %}

```ini
[Interface]
PrivateKey = <your gateway's private key>
Address = 169.254.100.6/30
ListenPort = 51820
MTU = 1420

[Peer]
PublicKey = <content of sendman.pub>
AllowedIPs = 169.254.100.5/32
```

Do not configure an endpoint for the Sendman peer. Sendman establishes the connection and keeps it alive.
{% endtab %}

{% tab title="Your gateway dials Sendman" %}

```ini
[Interface]
PrivateKey = <your gateway's private key>
Address = 169.254.100.6/30
MTU = 1420

[Peer]
PublicKey = <content of sendman.pub>
AllowedIPs = 169.254.100.5/32
Endpoint = <address:port shown in the connection details>
PersistentKeepalive = 25
```

The endpoint to dial is shown in the details of the connection in the portal. Keep the persistent keepalive so the tunnel stays up while idle.
{% endtab %}
{% endtabs %}

In addition:

* Route Sendman's tunnel address `169.254.100.5/32` through the WireGuard interface. Do not route anything else through it.
* Allow your clients to reach `169.254.100.5` on TCP 25, 465 and 587 as needed.
* Do not apply NAT to this traffic.

## Enable and test

1. In **Settings → Network Connections**, tick the connection under **Sendman ingress** and click **Save selection**.
2. Add your local network, e.g. `10.20.0.0`–`10.20.0.255`, to the [IP Allow List](/admin-portal/sendman/ip-allow-list.md).
3. Check on your gateway that the WireGuard handshake succeeds.
4. From a client in your local network, send a test message to `169.254.100.5` on port 587 or 25, and check [Logs](/admin-portal/insights/logs.md) for the client's local address.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sendman.com/admin-portal/settings/network-connections/wireguard.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.