How to configure an additional IP on your VPS

Context

By default, every Winheberg VPS comes with one IPv4 address. If your project needs multiple addresses, for example to isolate several services, manage separate TLS certificates, or split traffic, you can order one or more additional IPs from your client area.

On our VPS, an additional IP is added in the same network as your primary IP, as a /25 for IPv4 and a /64 for IPv6. Unlike a fully isolated address, it doesn't need a dedicated gateway or a special routing rule, the default route already present on your VPS is enough for it to respond correctly from the outside. All you need to do is add the address on your existing network interface.

The typical symptom of an IP added with the wrong prefix, or not added at all, is no response to a ping from the outside.

$ ping 82.153.202.X
Request timeout for icmp_seq 0
Request timeout for icmp_seq 1
Request timeout for icmp_seq 2

Prerequisites

An active Winheberg VPS with root SSH access
An additional IP already ordered on your product and visible in the IP Address section of your client area
Access to your client area at https://billing.winheberg.com
A recent backup of your VPS

Changing network configuration always carries some risk. The steps in this guide are additive and don't touch your primary IP, so your SSH access on the primary address stays intact. Still keep a recent backup as a precaution, since our VPS don't have a boot console.

1. Get your additional IP's details

An additional IP is ordered from your client area, on the relevant product's page, through the Upgrade/Downgrade Options. Once the address is provisioned, it appears in the IP Address section of your product page. Note this value down, the examples in this guide use demo addresses.

Parameter	IPv4 example	IPv6 example
Additional address	`82.153.202.X`	`2001:db8:1::X`
Prefix	`/25`	`/64`

The exact address, for both IPv4 and IPv6, is shown in the IP Address section of your product page. The values in this guide are examples and don't match your network. No dedicated gateway is needed for an additional IP, it shares your primary IP's default route.

2. Identify the right method for your VPS

Persistence across reboots doesn't depend on the distribution itself, but on the tool managing your network. The table below summarizes which sub-tab to follow.

Distribution	Detected network tool	Sub-tab to follow
Debian 12+, Ubuntu 22.04+	netplan	Debian 12+ and Ubuntu 22.04+ (netplan)
AlmaLinux 9, Rocky 9	NetworkManager	AlmaLinux, Rocky, Fedora (NetworkManager)
AlmaLinux 10, Rocky 10	NetworkManager	AlmaLinux, Rocky, Fedora (NetworkManager)
Fedora 41, 42	NetworkManager	AlmaLinux, Rocky, Fedora (NetworkManager)
Debian 11	neither netplan nor NetworkManager, systemd only	Debian 11 (systemd)
Alpine 3.22	OpenRC	Alpine

If you're unsure which tool is active, the commands below will tell you, in this order of priority.

# Is netplan present?
ls /etc/netplan/ 2>/dev/null

# Is NetworkManager active?
systemctl is-active NetworkManager 2>/dev/null

# Is it Alpine?
cat /etc/alpine-release 2>/dev/null

If none of these three commands return a positive result but systemctl works, your system runs on systemd alone, which is the case for Debian 11 on our images.

If your interface isn't named eth0, adapt the commands. The ip -br link command lists your network interfaces.

3. Configure the additional IP

Two approaches are possible. Our automatic script detects your distribution and applies everything through a menu. Manual configuration gives you full control, with one method per network tool.

Automatic method with our script

Our script automatically detects your network tool and shows a menu to add or remove an additional IP, for both IPv4 and IPv6. It applies the configuration and handles persistence across reboots, without ever touching your primary IP. This is the method we recommend, the manual configuration below reproduces exactly what the script does, for those who prefer to do everything by hand.

Download the script from our GitHub repository, make it executable, then run it with root privileges.

curl -o /usr/local/sbin/winheberg-additional-ip.sh REPLACE-WITH-GITHUB-LINK
chmod +x /usr/local/sbin/winheberg-additional-ip.sh
sudo /usr/local/sbin/winheberg-additional-ip.sh

Enter your address when the script asks for it, for example 82.153.202.X, and it configures the interface for you.

Manual configuration

Choose IPv4 or IPv6 first, then the method suited to your network tool. Each method simply adds the address to the existing interface, in the same network as your primary IP, without a gateway or dedicated routing table.

Create a dedicated netplan file, for example /etc/netplan/70-additional.yaml, with the content below. netplan merges this file with your primary IP's existing configuration, there's no need to disable cloud-init's network management, cloud-init only rewrites its own file (50-cloud-init.yaml), not the additional files you create.

network:
  version: 2
  ethernets:
    eth0:
      addresses:
        - 82.153.202.X/25

The netplan file must be readable only by root, otherwise netplan shows a warning.

sudo chmod 600 /etc/netplan/70-additional.yaml

Apply the configuration by testing it first, which allows an automatic rollback if you lose the connection.

sudo netplan try
sudo netplan apply

netplan try applies the configuration and then waits for confirmation. Without validation within the given time, it automatically restores the previous state, which protects your SSH access.

On these distributions, NetworkManager manages the interface. Rather than modifying the existing connection profile, we add a dispatcher script that reapplies the address on every network event, without touching the NetworkManager configuration already in place.

First, find your interface's name.

ip -br link

Create the dispatcher script.

sudo tee /etc/NetworkManager/dispatcher.d/50-additional-ip << 'EOF'
#!/bin/sh
[ "$1" = "eth0" ] || exit 0
case "$2" in up|dhcp4-change|dhcp6-change|connectivity-change) ;; *) exit 0 ;; esac
ip addr replace 82.153.202.X/25 dev eth0
EOF
sudo chmod +x /etc/NetworkManager/dispatcher.d/50-additional-ip

Apply the address right away, without waiting for the next network event.

sudo ip addr replace 82.153.202.X/25 dev eth0

This script fires again every time NetworkManager reconfigures the interface (reboot, reconnection), which makes the address persistent without modifying your existing ifcfg or keyfile connection profile.

Debian 11 doesn't install netplan by default and generally doesn't run NetworkManager on our images. Persistence therefore goes through a dedicated systemd service that reapplies the address on every boot.

Create the apply script.

sudo tee /usr/local/sbin/winheberg-additional-ip-apply.sh << 'EOF'
#!/bin/sh
ip addr replace 82.153.202.X/25 dev eth0
EOF
sudo chmod +x /usr/local/sbin/winheberg-additional-ip-apply.sh

Create the associated systemd service.

sudo tee /etc/systemd/system/winheberg-additional-ip.service << 'EOF'
[Unit]
Description=Winheberg - additional IP
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/sbin/winheberg-additional-ip-apply.sh

[Install]
WantedBy=multi-user.target
EOF

Enable the service so it fires on future boots, then apply the address right away.

sudo systemctl daemon-reload
sudo systemctl enable winheberg-additional-ip.service
sudo ip addr replace 82.153.202.X/25 dev eth0

First, install iproute2, if not already done.

apk add iproute2

Create a startup script that applies the address on every boot.

cat > /etc/local.d/additional-ip.start << 'EOF'
#!/bin/sh
ip addr replace 82.153.202.X/25 dev eth0
EOF
chmod +x /etc/local.d/additional-ip.start

Enable OpenRC's local service, then run the script without waiting for the next reboot.

rc-update add local default
rc-service local start

The /etc/local.d/ folder is provided by OpenRC for this kind of startup command. Your address is thus automatically reapplied on every boot.

Complete the same /etc/netplan/70-additional.yaml file with the IPv6 block, or create the file if you haven't configured IPv4. When both families coexist, group the addresses entries in the same eth0 block.

network:
  version: 2
  ethernets:
    eth0:
      addresses:
        - "2001:db8:1::X/64"

Secure and apply the file the same way as for IPv4.

sudo chmod 600 /etc/netplan/70-additional.yaml
sudo netplan try
sudo netplan apply

Add the IPv6 line to the same dispatcher script, after the IPv4 line.

sudo tee -a /etc/NetworkManager/dispatcher.d/50-additional-ip << 'EOF'
ip -6 addr replace 2001:db8:1::X/64 dev eth0
EOF

Apply right away.

sudo ip -6 addr replace 2001:db8:1::X/64 dev eth0

Add the IPv6 line to the same apply script, after the IPv4 line.

sudo tee -a /usr/local/sbin/winheberg-additional-ip-apply.sh << 'EOF'
ip -6 addr replace 2001:db8:1::X/64 dev eth0
EOF

Apply right away, the systemd service will replay this line on the next boot.

sudo ip -6 addr replace 2001:db8:1::X/64 dev eth0

Add the IPv6 line to the /etc/local.d/additional-ip.start script, after the IPv4 line.

ip -6 addr replace 2001:db8:1::X/64 dev eth0

Then restart the local service to apply it.

rc-service local restart

4. Check that the IP responds

Check that the address is present on the interface.

ip -br addr show eth0

You should see your additional IP in the address list, with the correct prefix (/25 for IPv4, /64 for IPv6). From another machine, a ping to the additional IP should now respond.

ping 82.153.202.X
ping -6 2001:db8:1::X

This verification command is the same across all network tools. It relies on iproute2, present by default everywhere except Alpine, where it's installed with apk add iproute2.

If you run into trouble

❌ The additional IP doesn't respond to ping

Check that the address shows up in ip -br addr show eth0 with the correct prefix
Make sure you haven't used a /32 or /128 prefix by mistake, the additional IP must stay in the same network as your primary IP, /25 for IPv4 and /64 for IPv6
Check that your firewall (ufw, firewalld, or iptables) isn't blocking ICMP traffic or the relevant services on the new address
Confirm you're targeting the right interface, eth0 on some images, ens3 or another name on others
Compare the configured address with the exact value shown in the IP Address section

❌ The configuration disappears after a reboot

netplan, the file must be located in /etc/netplan/ with a .yaml extension
NetworkManager, the dispatcher script must exist in /etc/NetworkManager/dispatcher.d/ and be executable, check with ls -l
Debian 11, the service must be enabled, check with systemctl is-enabled winheberg-additional-ip.service and systemctl status winheberg-additional-ip.service
Alpine, check that rc-update add local default was run and that the .start script is executable

❌ The IP responds but some remote services reject it

Check that the service is actually listening on this address and not only on the primary IP, especially if your application binds to a specific address
Check that no firewall rule specifically targets the primary IP and effectively excludes the new address

Best practices

Prefer our automatic script, it applies exactly the methods described in this guide and handles detecting your network tool for you
On netplan systems (Debian 12+ and Ubuntu), test with netplan try, it restores the previous configuration if you lose access
Keep your changes additive and never modify your primary IP's configuration
Always respect the given prefix, /25 for IPv4 and /64 for IPv6, a /32 or /128 prefix would isolate the address and prevent it from responding correctly
Document each additional IP's address and the method used to apply it
Check your firewall after adding the address and only open the services you want on the new address
Back up your network configuration files before any change

Need help?

To order an additional IP, go to the relevant product's page in your client area at https://billing.winheberg.com and use the Upgrade/Downgrade Options. The assigned address then appears in the IP Address section of the product page.

If your additional IP still doesn't respond after configuration, open a ticket with our support. Choose the Technical department and fill in the Produit lié field with the VPS in question. Specify the configured address, the network tool used, and the result of the verification commands, this helps our team diagnose the issue faster.

Your VPS can now properly expose multiple addresses, each added on the same network as your primary IP 🐧