# Create a WireGuard® Peer between a VDC and an on-premises Gateway
## Overview
This tutorial demonstrates configuring the VPN Gateway in IONOS Cloud to create a site-to-site setup between an IONOS Cloud VDC and a simulated on-premises installation. It uses a managed WireGuard® instance to provide secure, encrypted connectivity between an IONOS Cloud VDC and a simulated on-premises setup.
{% hint style="danger" %}
**Trademark notice:** All references to WireGuard in this guide refer to the WireGuard® protocol and software. WireGuard is a registered trademark of Jason A. Donenfeld.
{% endhint %}
This tutorial demonstrates the use of the following:
| **Components** | **Description** |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Two VDCs | - ionos-cloud-txl as IONOS Cloud's VDC.
- user-on-prem-lhr simulates a user-managed on-premises setup.
|
| Managed gateways | We use a single managed gateway in ionos-cloud-txl for the cloud side.
For a user-managed gateway, we use on-premises simulation, install the components, and manually configure WireGuard on a virtual server to complete the setup.
|
## Target audience
This tutorial is intended to help both developers and technical decision-makers.
## What you will learn
By following this tutorial, you will learn how to:
* Set up a managed WireGuard VPN Gateway in IONOS Cloud.
* Simulate an on-premises WireGuard gateway using a virtual server.
* Generate and manage WireGuard key pairs for secure connectivity.
* Configure VPN peers and endpoints for site-to-site communication.
* Deploy and configure WireGuard on a user-managed gateway.
* Manually add routing rules to enable traffic flow between cloud and on-premises LANs.
* Verify end-to-end connectivity between the two sites.
## Before you begin
{% hint style="info" %}
**Note:** Sample keys are used as example in this document. Do not use this key for real-world scenarios.
{% endhint %}
The following information is necessary to set up a connection between a WireGuard VDC and an on-premises VDC:
| **Components** | **IONOS Cloud (Left)** `ionos-cloud-txl` | **User On-Premises (Right)** `user-on-prem-lhr` |
| ----------------------------- | ---------------------------------------- | ----------------------------------------------- |
| **VDC Name** | `ionos-cloud-txl` | `user-on-prem-lhr` |
| **Gateway Public Address** | `203.0.113.10` | `203.0.113.20` |
| **LAN ID** | `1` | `2` (Not applicable in this use case) |
| **LAN Subnet** | `192.168.1.0/24` | `192.168.2.0/24` |
| **Gateway LAN Address** | `192.168.1.5` | `192.168.2.5` |
| **LAN Host 1** | `192.168.1.11` | `192.168.2.11` |
| **LAN Host 2** | `192.168.1.12` | `192.168.2.12` |
| **WireGuard Subnet** | `172.16.1.0/30` | `172.16.1.0/30` |
| **Gateway WireGuard Address** | `172.16.1.1/30` | `172.16.1.2/30` |
| **Gateway Private Key** | `abcdefABC12345=` | `kHKHABcC+67891=` |
| **Pre-Shared Key** | `defDEFhiH/98765=` | `lmnoLMNO/89762=` |
### Reserve IP addresses
Before proceeding, ensure you have an IP block with at least one free IP address to assign to each gateway. For more information, see [Reserve an IPv4 Address](https://docs.ionos.com/cloud/network-services/vdc-networking/how-tos/ip-addresses).
| **IONOS Cloud (Left) `ionos-cloud-txl` Gateway Public Address** | **User On-Premises (Right) `user-on-prem-lhr` Gateway Public Address** |
| --------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `203.0.113.10` | `203.0.113.20` |
### Configure LAN
This tutorial uses `192.168.1.0/24` for the private LAN in IONOS Cloud (Left) and `192.168.2.0/24` for User On-Premises (Right). Assign an IP address from each subnet to its respective gateway. For example, use `192.168.1.5` for the VPN Gateway, as it is not DHCP-aware.
The chosen IP address must be outside the DHCP pool and should be in the range from `.2` to `.9`. `user-on-prem-lhr` is a simulating user-managed gateway that uses its LAN host address of `192.168.2.5` instead. Hence, the above statement does not apply to this data center.
| **Components** | **IONOS Cloud (Left)** `ionos-cloud-txl` | **User On-Premises (Right)** `user-on-prem-lhr` |
| ----------------------- | ---------------------------------------- | ----------------------------------------------- |
| **LAN ID** | `1` | `2` (Not applicable here) |
| **LAN Subnet** | `192.168.1.0/24` | `192.168.2.0/24` |
| **Gateway LAN Address** | `192.168.1.5` | `192.168.2.5` |
### WireGuard interface IP address and subnet information
Each participant in a WireGuard VPN setup requires its own WireGuard interface address and subnet, which are unrelated to the networks you use in the cloud. It should be a subnet that does not conflict with anything already in the cloud or on the client side.
| **Components** | **IONOS Cloud (Left)** `ionos-cloud-txl` | **User On-Premises (Right)** `user-on-prem-lhr` |
| ----------------------------- | ---------------------------------------- | ----------------------------------------------- |
| **WireGuard Subnet** | `172.16.1.0/30` | `172.16.1.0/30` |
| **Gateway WireGuard Address** | `172.16.1.1/30` | `172.16.1.2/30` |
### Generate Keypairs
WireGuard requires a key pair for the gateway and each connected peer. You can generate them using the WireGuard utilities or the OpenSSL command-line tools. Although we describe both approaches below, we recommend the former because it is a more straightforward procedure.
| **Components** | **IONOS Cloud (Left)** `ionos-cloud-txl` | **User On-Premises (Right)** `user-on-prem-lhr` |
| ----------------------- | ---------------------------------------- | ----------------------------------------------- |
| **Gateway Private Key** | `abcdefABC12345=` | `kHKHABcC+67891=` |
| **Gateway Public Key** | `defDEFhiH/98765=` | `lmnoLMNO/89762=` |
{% tabs %}
{% tab title="Use wg utilities" %}
Use `wg genkey` to create the private key and `wg pubkey` to derive the public key content from the private key. You can also perform it via a single command, as shown below. Repeat the process for the gateway and each peer.
```bash
demo: wg genkey |tee gateway_private_key | wg pubkey > gateway_public_key
demo: cat gateway_private_key
abcdefABC12345=
demo: cat gateway_public_key
defDEFhiH/98765=
```
{% endtab %}
{% tab title="Use OpenSSL" %}
Use `openssl` to generate `der` keys and convert them to the required format for WireGuard. We will use this to create the keypair:
```bash
demo: openssl genpkey -algorithm X25519 -outform der -out user_private.der
demo: openssl pkey -inform der -in user_private.der -pubout -outform der -out user_public.der
demo: cat user_private.der |tail -c 32 | base64 > user_private_key
demo: cat user_public.der |tail -c 32 | base64 > user_public_key
demo: rm *.der
demo: cat user_private_key
kHKHABcC+67891=
demo: cat user_public_key
lmnoLMNO/89762=
```
With both these tools available locally, we can verify the OpenSSL-generated key by using the WireGuard tools to derive the public key from the OpenSSL-generated private key.
```bash
demo: wg pubkey < user_private_key
lmnoLMNO/89762=
```
As we can see, the public key content matches the one generated by OpenSSL.
{% endtab %}
{% endtabs %}
## Process
{% stepper %}
{% step %}
#### Set up IONOS Cloud
Below are some screenshots from the DCD that contains the required VDCs.
To begin with, two virtual servers on the IONOS Cloud are provisioned and connected to each other via a private LAN. In this instance, LAN1 uses a custom subnet of `192.168.1.0/24`. We designate these two LAN hosts as `192.168.1.11` and `192.168.1.12`, respectively.
{% endstep %}
{% step %}
#### Simulate on-premises setup
Imagine the `user-on-prem-lhr` VDC as a user-managed site where you provision two virtual servers. Here, we will use the subnet `192.168.2.0/24`. Host `1` has been configured with internet access (IP address: `203.0.113.20`) and will function as the on-premises host acting as a user-managed gateway. We address these two LAN hosts as `192.168.2.11` and `192.168.2.12`, respectively and the user managed VPN gateway is assigned the following IP address: `192.168.2.5`.
{% endstep %}
{% step %}
#### Provision the VPN Gateway
1\. In the **DCD**, go to **Menu** > **Network Services** > **VPN Gateway**.
2\. Click **Create VPN Gateway** from the **VPN Gateways** window.
3\. Enter the following details:
{% tabs %}
{% tab title="Properties" %}
| **Components** | **Description** | **Example** |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Name** | Enter a descriptive name for the gateway instance. It is not required to be globally unique but must be limited to 255 characters. | `ionos-cloud-txl` |
| **Description** | Enter a descriptive text for the gateway. It is limited to 1024 characters. | `VPN Gateway for creating a WireGuard Peer between a VDC and on-premises gateway.` |
| **Location** | Select a location from the drop-down list of available locations for VPN Gateway. | `de/txl` |
| **IP Address** | Select an IP address from the drop-down list of available public IPv4 addresses. | `203.0.113.10` |
{% endtab %}
{% tab title="VPN Tier" %}
The **Enhanced VPN** tier is selected by default. The number of LANs and peers differ for each tier. You can also enable **High Availability** for a chosen tier, allowing VMs to operate in an active-passive mode. It minimizes downtime during a failover and ensures an uninterrupted connection.
{% hint style="info" %}
**Note:** You can only upgrade the tier or switch between High Availability (HA) and non-HA variants during editing.
{% endhint %}
{% endtab %}
{% tab title="Protocol" %}
Select **WireGuard** protocol and specify the following:
| **Components** | **Description** | **Example** |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- | ----------------- |
| **Private Key** | The `gateway_private_key` value generated earlier in this document. | `abcdefABC12345=` |
| **Interface IPv4** | The IPv4 address of the WireGuard interface. | `172.16.1.1/30` |
| **Interface IPv6** | The IPv6 address of the WireGuard interface. This demonstration does not contain IPv6 addresses. | `Not applicable` |
| **ListenPort** | The UDP port on which WireGuard will listen for encrypted VPN packets. The tutorial uses the default value `51280`. | `51280` |
{% endtab %}
{% tab title="LAN Connections" %}
Attach a VPN Gateway to LANs in IONOS Cloud. You can only connect to LANs in the exact location where the VPN Gateway was provisioned. Take a look at the following mandatory parameters:
| **Components** | **Description** | **Example** |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------- |
| **Datacenter** | Select a data center from the drop-down that lists VDCs in the same location as the gateway. | `ionos-cloud-txl` |
| **Connections** | After selecting a data center, click **Add LAN Connection** to launch an additional pop-up window to set the properties. | `See Below` |
Enter the following in the **Edit LAN Connection** pop-up window:
| **Components** | **Description** | **Example** |
| -------------- | ----------------------------------------------------------------------- | ---------------- |
| **LAN** | The ID of the LAN to connect to. | `1` |
| **IPv4 CIDR** | The LAN IPv4 address assigned to the subnet's gateway in CIDR notation. | `192.168.1.5` |
| **IPv6 CIDR** | The LAN IPv6 address assigned to the subnet's gateway in CIDR notation. | `Not applicable` |
{% endtab %}
{% endtabs %}
4\. Click **Save** and wait for the gateway to complete provisioning. The process typically takes about 8-10 minutes, but further operations on the gateway will be instantaneous.
{% endstep %}
{% step %}
#### Configure the VPN peer
Now that the VPN Gateway instance is provisioned, next step is to configure a peer to permit the two sides to talk with each other. We will need to configure a peer on both gateways but the on-premises will be configured using WireGuard configuration files.
1\. Click **Create Peers** to begin configuring a new peer.
{% tabs %}
{% tab title="Properties" %}
Enter the following details to configure a peer:
| **Components** | **Description** | **Example** |
| --------------- | --------------------------------------------------------------------------------------------------------- | ---------------- |
| **Peer Name** | Specify a name for the peer. It does not need to be globally unique and can be up to 255 characters long. | `customer_site` |
| **Description** | Enter more descriptive text for the peer, not exceeding 1024 characters. | `Not applicable` |
{% endtab %}
{% tab title="Endpoint configuration" %}
Configure the endpoint so the gateway knows with which remote address the connection must be established. We will configure this as the public IPv4 address of the gateway to be created in `user-on-prem-lhr`.
| **Components** | **Description** | **Example** |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| **Endpoint host** | The gateway public IPv4 address of the remote on-prem gateway. | `203.0.113.20` |
| **Endpoint port** | The endpoint port on which WireGuard will listen for incoming encrypted VPN packets. The tutorial uses the default value `51280`. | `51280` |
{% endtab %}
{% tab title="Peers configuration" %}
The peers section specifies which networks are permitted across the peer. Here we will specify the WireGuard subnet in CIDR notation as described earlier.
| **Components** | **Description** | **Example** |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |
| **Allowed IPs** | Enter a comma separated list of subnets in CIDR notation that are permitted to send traffic to the given peer. It is the subnet used on the peer side. | `192.168.2.0/24` |
| **Public Key** | The public key of the peer as we generated earlier in this tutorial. | `lmnoLMNO/89762=` |
{% endtab %}
{% endtabs %}
2\. Click **Save** to save the peer configuration. This operation should typically be completed within a minute or two.
{% endstep %}
{% step %}
#### Deploy on-premises WireGuard instance
In this tutorial, the on-premises "User VPN GW" Host acts as a user-managed gateway. The host has internet access, so SSH can be used instead of the web console. Start by establishing an SSH connection to the on-premises "User VPN GW" hosts public IPv4 address.
```
demo: ssh 203.0.113.20 -l root
linux userlanhost1 6.1.0-26-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.112-1 (2024-09-30) x86_64
The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.
Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Wed Oct 16 09:29:05 2024 from 123.123.123.123
root@userlanhost1:~#
```
1. Install pre-requisite software
{% hint style="info" %}
**Note:** This tutorial performs a basic install and setup of WireGuard. It is neither an in-depth guide nor does it contain detailed information about the configuration files' content. It is an exercise for the reader to determine the correct installation procedure for a secure production environment.
{% endhint %}
Update the package lists and install the required packages:
```bash
apt-get update
apt-get install wireguard wireguard-tools -y
```
2. Enable IP forwarding
The VPN gateway acts as a router and, therefore, is required to forward packets:
```bash
sysctl -w net.ipv4.ip_forward=1
```
This tutorial does not use an IPv6 address. If you intend to use one, ensure `net.ipv6.config.all.forwarding=1` exists.
3. Configure the user-managed WireGuard server
This tutorial will walk you through specific options for configuring WireGuard, but the rest of the configuration remains an exercise for the reader. This section contains the configuration files and content specific to this installation and peer setup.
**3.1 Create WireGuard configuration for the user-managed gateway** Let us first examine an empty WireGuard configuration file:
```
[Interface]
PrivateKey =
Address =
ListenPort =
[Peer]
PublicKey =
AllowedIPs =
Endpoint =
```
**3.2 Evaluate and configure sections parameters**
Let us evaluate each section parameter to understand what they are and what the values should be to configure the client:
| **Components** | **Value** | **Description** | **Example** |
| -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| Interface | PrivateKey | The user-managed gateway private key. Ensure it matches the public key we used when creating the peer in the DCD. | `kHKHABcC+67891=` |
| Interface | Address | The IP address to assign to the WireGuard interface on the user-managed gateway. | 172.16.1.2/30 |
| Interface | ListenPort | The UDP Port configured on the managed gateway, by default this is 51820. | 51820 |
| Peer | PublicKey | The public key of the IONOS Cloud managed gateway. Ensure it matches the private key we used when creating the IONOS Cloud managed gateway. | `defDEFhiH/98765=` |
| Peer | AllowedIPs | IP addresses allowed across the VPN. This should permit the subnet in use at the `de/txl` location. | 192.168.1.0/24 |
| Peer | Endpoint | The public IP address and port of the managed VPN gateway instance. | 203.0.113.10 |
{% hint style="success" %}
**Expected result:** This results in a final configuration file as follows, which must be saved to the `/etc/wireguard/wg0.conf` file:
```
[Interface]
PrivateKey = kHKHABcC+67891=
Address = 172.16.1.2/30
ListenPort = 51820
[Peer]
PublicKey = defDEFhiH/98765=
AllowedIPs = 192.168.1.0/24
Endpoint = 203.0.113.10
```
{% endhint %}
**3.3 Start WireGuard on the user-managed gateway**
Let us start WireGuard on the user-managed gateway using `wg utilities`. It enables the `wg0` interface and adds the required routing entries:
**Connected with the `user-on-prem-lhr`** **`UserLANHost1` in London:**
```
root@userlanhost1:~# wg-quick up wg0
[#] ip link add wg0 type wireguard
[#] wg setconf wg0 /dev/fd/63
[#] ip -4 address add 172.16.1.2/30 dev wg0
[#] ip link set mtu 1420 up dev wg0
[#] ip -4 route add 192.168.2.0/24 dev wg0
```
Now execute `wg show` to see the status:
```
root@userlanhost1:~# wg show
interface: wg0
public key: lmnoLMNO/89762=
private key: (hidden)
listening port: 51820
peer: defDEFhiH/98765=
endpoint: 192.168.1.5:51820
allowed ips: 192.168.1.0/24
```
{% endstep %}
{% step %}
#### Configure routing on LAN hosts
Currently, it is impossible to automate the addition of routes to LAN hosts to route the required subnets over the VPN Gateway. In this section, we will manually add the required routes. Remember to add them to the LAN hosts in both the VDCs.
{% stepper %}
{% step %}
**Configure routing on IONOS Cloud LAN Hosts**
1. Establish a console session to the LAN host(s)
We will use the web console to test connectivity for the LAN hosts without internet access. Open a console session and ping the LAN address assigned to the VPN Gateway, `192.168.1.5`. Begin by pinging the IP address:
**Connected with the `ionos-cloud-txl`** **`CloudLANHost1` in Berlin:**
```bash
root@cloudlanhost1:~# ping -c 3 192.168.1.5
PING 192.168.1.5 (192.168.1.5) 56(84) bytes of data.
64 bytes from 192.168.1.5: icmp_seq=1 ttl=64 time=0.626 ms
64 bytes from 192.168.1.5: icmp_seq=2 ttl=64 time=0.527 ms
64 bytes from 192.168.1.5: icmp_seq=3 ttl=64 time=0.336 ms
--- 192.168.1.5 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2035ms
rtt min/avg/max/mdev = 0.336/0.496/0.626/0.120 ms
root@cloudlanhost1:~#
```
2. Configure the VPN route
The LAN host(s) must know where to route the return traffic. To accomplish this, we will add a route for the on-premises LAN subnet `192.168.2.0/24` through the IONOS Cloud Gateway's LAN address `192.168.1.5`:
```bash
ip route add 192.168.2.0/24 via 192.168.1.5
```
Currently, we cannot ping the on-premises LAN hosts because those servers do not yet know how to route the return traffic. Continue to configure on-premises route in `user-on-prem-lhr` to resolve this issue.
{% endstep %}
{% step %}
**Configure on-premises route**
1. Establish an SSH session to the LAN hosts
{% hint style="info" %}
**Note:** Perform the configuration on the host acting as the user-managed gateway, as it already knows how to route based on the WireGuard configuration connected to the two LAN hosts.
{% endhint %}
We will use the web console to test connectivity for the LAN hosts without internet access. Open a console session and ping the LAN address assigned to the VPN Gateway, `192.168.2.5`. Begin by pinging the IP address:
**Connected with the `user-on-prem-lhr`** **`UserLANHost2` in London:**
```bash
root@userlanhost2:~# ping -c 3 192.168.2.5
PING 192.168.2.5 56(84) bytes of data.
64 bytes from 192.168.2.5 : icmp_seq=1 ttl=64 time=0.333 ms
64 bytes from 192.168.2.5 : icmp_seq=2 ttl=64 time=0.370 ms
64 bytes from 192.168.2.5 : icmp_seq=3 ttl=64 time=0.307 ms
--- 192.168.2.5 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2043ms
rtt min/avg/max/mdev = 0.307/0.336/0.370/0.025 ms
root@userlanhost2:~#
```
2. Configure the VPN route
The LAN host(s) must know where to route return traffic. To accomplish this, we will add a route to the IONOS Cloud LAN subnet `(192.168.1.0/24)` through the user-managed gateway's LAN address `(192.168.2.5)`:
```
ip route add 192.168.1.0/24 via 192.168.2.5
```
Repeat this process for all on-premises LAN hosts that need to send or receive traffic over the peer. At this point, we should have full connectivity between the two sites via the VPN Gateway.
{% endstep %}
{% endstepper %}
{% endstep %}
{% endstepper %}
## Final result
You should now be able to ping hosts in the simulated on-premises setup in `user-on-prem-lhr` from cloud hosts in `ionos-cloud-txl` and vice-versa.
{% tabs %}
{% tab title="Test from IONOS Cloud to On-Premises" %}
On a cloud LAN host `cloudlanhost1`, test connectivity to an on-premises LAN host:
```bash
root@cloudlanhost1:~# ping -c 5 192.168.2.12
PING 192.168.2.12 56(84) bytes of data.
64 bytes from 192.168.2.12 : icmp_seq=1 ttl=62 time=18.3 ms
64 bytes from 192.168.2.12 : icmp_seq=2 ttl=62 time=18.6 ms
64 bytes from 192.168.2.12 : icmp_seq=3 ttl=62 time=18.3 ms
64 bytes from 192.168.2.12 : icmp_seq=4 ttl=62 time=18.3 ms
64 bytes from 192.168.2.12 : icmp_seq=5 ttl=62 time=18.0 ms
--- 192.168.2.12 ping statistics ---
5 packets transmitted, 5 received, 0% packet loss, time 4005ms
rtt min/avg/max/mdev = 18.034/18.291/18.562/0.168 ms
```
{% endtab %}
{% tab title="Test from On-Premises to IONOS Cloud" %}
On an on-premises LAN host `userlanhost1`, test connectivity to a cloud LAN host:
```bash
root@userlanhost2:~# ping -c 5 192.168.1.11
PING 192.168.1.11 56(84) bytes of data.
64 bytes from 192.168.1.11 : icmp_seq=1 ttl=62 time=19.9 ms
64 bytes from 192.168.1.11 : icmp_seq=2 ttl=62 time=18.6 ms
64 bytes from 192.168.1.11 : icmp_seq=3 ttl=62 time=18.2 ms
64 bytes from 192.168.1.11 : icmp_seq=4 ttl=62 time=18.2 ms
64 bytes from 192.168.1.11 : icmp_seq=5 ttl=62 time=18.6 ms
--- 192.168.1.11 ping statistics ---
5 packets transmitted, 5 received, 0% packet loss, time 4006ms
rtt min/avg/max/mdev = 18.182/18.704/19.938/0.644 ms
```
{% endtab %}
{% endtabs %}
## Conclusion
You have successfully configured a site-to-site VPN connection between IONOS Cloud and your on-premises setup by utilising a Managed VPN Gateway in the cloud and a user-managed on-premises gateway.