How to Configure a WireGuard Point-to-Site VPN Server on Debian 12

A WireGuard point-to-site VPN on Debian 12 (Bookworm) is a practical way to let laptops, phones, or remote workstations reach a server or route traffic through it. One important clarification comes first: WireGuard does not have a special “server mode.” Every participant is a peer. In a point-to-site design, one Debian host simply acts as the stable, publicly reachable hub and each remote device gets its own key pair and tunnel address.

This guide uses Debian’s packaged WireGuard tools, wg-quick, IPv4 forwarding, and nftables. It assumes the Debian server has root or sudo access and that UDP port 51820 can reach it. If the server is behind a home or office router, you must forward that UDP port to the Debian host. If the ISP uses carrier-grade NAT (CGNAT), ordinary router port forwarding may not be enough; confirm that you actually have a reachable public address before troubleshooting WireGuard itself.

What will this configuration do?

The example VPN uses 10.8.0.0/24. The server is 10.8.0.1, and the first client is 10.8.0.2. The client can be configured as either a full-tunnel VPN, where IPv4 Internet traffic exits through the Debian server, or a split tunnel, where only selected private networks use WireGuard.

Debian’s own WireGuard documentation confirms that WireGuard is available through the distribution packages, while the official WireGuard quick-start documents key generation, wg-quick, and the optional persistent keepalive behavior. See the Debian WireGuard documentation, the official WireGuard Quick Start, and Debian’s wg-quick manual page.

Step 1: Install WireGuard and nftables

Update package metadata, then install WireGuard and nftables:

sudo apt update
sudo apt install wireguard nftables

A common misconception is that Debian 12 needs an out-of-tree WireGuard kernel module. It does not. WireGuard has been in the Linux kernel for years; Debian’s packages provide the userspace management tools you need. Action: use Debian packages instead of downloading an unverified installation script.

Step 2: Generate the server key pair

Create the key files with restrictive permissions:

sudo -i
install -d -m 700 /etc/wireguard
umask 077
wg genkey | tee /etc/wireguard/server_private.key | wg pubkey > /etc/wireguard/server_public.key
chmod 600 /etc/wireguard/server_private.key
cat /etc/wireguard/server_public.key

The private key must remain private. The public key is what you copy into client configurations. Ideally, generate each client’s private key on that client rather than on the server. That way the server never needs to possess client private keys.

Step 3: Enable IPv4 forwarding

VPN 터널은 성공적으로 설정되었지만 라우팅된 트래픽은 여전히 ​​실패할 수 있습니다. 그 이유는 Linux IP 포워딩이 WireGuard 자체와는 별개의 커널 설정이기 때문입니다. 영구적인 sysctl 파일을 생성하십시오.

echo 'net.ipv4.ip_forward=1' | sudo tee /etc/sysctl.d/99-wireguard.conf
sudo sysctl --system
sysctl net.ipv4.ip_forward

최종 명령은 를 보고해야 합니다 net.ipv4.ip_forward = 1. Debian 커널 문서에서는 를 ip_forwardIPv4 패킷 포워딩을 활성화하는 스위치로 설명합니다. 조치: 터널 인터페이스가 자동으로 라우팅을 켜는 것으로 가정하지 말고 이 값을 명시적으로 확인하십시오. Debian ip(7) 매뉴얼 과 sysctl.conf 문서를 참조하십시오 .

4단계: 서버 구성 생성

서버 개인 키를 읽은 다음 다음을 생성하세요 /etc/wireguard/wg0.conf.

[Interface]
Address = 10.8.0.1/24
ListenPort = 51820
PrivateKey = SERVER_PRIVATE_KEY

[Peer]
PublicKey = CLIENT_PUBLIC_KEY
AllowedIPs = 10.8.0.2/32

다음으로 파일을 보호하세요.

sudo chmod 600 /etc/wireguard/wg0.conf

AllowedIPsWireGuard 는 방화벽과 같은 허용 목록으로만 오해되는 경우가 많습니다. 하지만 라우팅도 제어합니다. 서버에서 10.8.0.2/32특정 피어에 주소를 할당하면 WireGuard는 해당 터널 주소로 오는 패킷이 이 클라이언트에 속한다고 인식합니다. 모든 클라이언트에게 고유한 주소와 별도의 [Peer]블록을 할당하십시오.

SaveConfig = true이 파일을 수동으로 관리할 경우, 해당 옵션을 생략하는 것도 유용한 방법입니다 . 옵션을 사용 SaveConfig하면 wg-quick시스템 종료 시 실시간 상태를 구성 파일에 다시 기록할 수 있으며, 이로 인해 수동으로 편집한 내용이 덮어쓰여질 수 있습니다. 따라서 실시간 상태를 저장하려는 경우가 아니라면 파일을 선언적인 형태로 유지하십시오.

5단계: nftables 마스킹 구성

풀터널 클라이언트가 데비안 서버를 통해 인터넷에 접속해야 하는 경우, 가장 쉬운 방법은 IPv4 마스커레이딩을 사용하는 것입니다. 먼저 서버의 아웃바운드 인터페이스를 확인해야 합니다.

ip route get 1.1.1.1

, , 또는 dev와 같은 인터페이스가 뒤에 오는지 확인하십시오 . 항상 라고 가정하지 마십시오 .eth0ens3enp1s0eth0

이미 NAT 설정을 유지 관리 중인 경우 /etc/nftables.conf, 파일을 교체하는 대신 다음 NAT 테이블을 기존 규칙 세트에 병합하십시오.

table ip wireguard-nat {
    chain postrouting {
        type nat hook postrouting priority 100; policy accept;
        oifname "eth0" ip saddr 10.8.0.0/24 masquerade
    }
}

eth0실제 발신 인터페이스로 교체하십시오 . 로드하기 전에 유효성을 검사하십시오.

sudo nft -c -f /etc/nftables.conf
sudo systemctl enable --now nftables
sudo nft list ruleset

WireGuard에서 NAT는 필수적인 요소가 아닙니다. 목적지 LAN에 이미 서버로 돌아가는 경로가 있는 경우 10.8.0.0/24, NAT 마스커레이딩 없이도 라우팅된 액세스가 가능합니다. NAT는 원격 클라이언트가 서버의 기존 인터넷 경로를 사용하도록 하고, 다른 곳으로의 복귀 경로를 제어할 수 없는 경우에 주로 유용합니다. 권장 사항: 단순한 인터넷 출구 경로의 경우에는 NAT 마스커레이딩을 사용하고, 네트워크를 제어하고 소스 주소를 유지하려는 경우에는 명시적 라우팅을 사용하는 것이 좋습니다.

방화벽 규칙도 필요하신가요?

이미 설치된 방화벽에 따라 다릅니다. nftables 입력 정책이 제한적이라면 인바운드 UDP를 허용하십시오 51820. 포워드 체인에 기본 차단 정책이 있는 경우, wg0의도한 목적지로의 트래픽과 설정된 반환 트래픽을 허용하는 규칙을 추가하십시오. 클라우드 VPS 제공업체는 UDP를 허용해야 하는 별도의 보안 그룹 또는 제공업체 방화벽을 보유하고 있을 수도 있습니다 51820.

원격 SSH 서버에 완전히 새로운 기본 방화벽 규칙 세트를 무턱대고 붙여넣지 마십시오. 접속이 차단될 수 있습니다. 조치: sudo nft list ruleset기존 방화벽을 검토하고 WireGuard를 통합하십시오.

6단계: 고객 프로필 작성

클라이언트 측에서 WireGuard 앱 또는 다른 방법을 사용하여 자체 키 쌍을 생성합니다 wg genkey. 전체 터널 IPv4 프로필은 다음과 같습니다.

[Interface]
Address = 10.8.0.2/24
PrivateKey = CLIENT_PRIVATE_KEY
DNS = 1.1.1.1

[Peer]
PublicKey = SERVER_PUBLIC_KEY
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

vpn.example.com서버의 공개 DNS 이름 또는 공개 IP 주소로 바꾸십시오 . 이 DNS줄은 선택 사항이며 클라이언트 구현 지원 여부는 다를 수 있습니다. 스플릿 터널의 경우 AllowedIPsVPN을 통과해야 하는 네트워크만 지정하십시오. 예를 들어, 10.8.0.0/24사설 LAN(예: )을 추가하십시오 192.168.50.0/24.

PersistentKeepalive = 25이 설정은 선택 사항입니다. WireGuard 공식 문서에서는 NAT 또는 상태 저장 방화벽 뒤에 있는 피어가 유휴 시간 동안 매핑을 유지해야 하는 경우 25초를 적절한 값으로 권장합니다. 이는 성능 설정이 아니며 모든 클라이언트에 필수적인 것은 아닙니다. 권장 사항: 주로 로밍 클라이언트 또는 NAT 환경의 클라이언트처럼 유휴 시간 이후 연결할 수 없게 되는 경우에 사용하십시오.

7단계: 부팅 시 WireGuard를 시작합니다.

먼저 nftables를 실행한 다음 WireGuard 인터페이스를 활성화하십시오.

sudo systemctl enable --now nftables
sudo systemctl enable --now wg-quick@wg0
systemctl is-active nftables
systemctl is-active wg-quick@wg0

wg-quick@wg0/etc/wireguard/wg0.conf설명서 를 읽어보면 wg-quick이 명명 규칙이 아래에 저장된 구성에 대한 일반적인 바로 가기임을 확인할 수 있습니다 /etc/wireguard. 조치: 더 복잡한 네트워크 관리자 설계가 없는 한 사용자 지정 부팅 스크립트 대신 서비스를 사용하십시오.

8단계: 핸드셰이크 및 트래픽을 확인합니다.

클라이언트를 연결한 다음 서버를 검사하십시오.

sudo wg show
ip address show wg0
ping -c 3 10.8.0.2

정상적인 피어는 터널을 통과한 후 최근 핸드셰이크 기록과 0이 아닌 전송 카운터 값을 보여줍니다. 전체 터널을 구성한 경우, 신뢰할 수 있는 IP 확인 서비스를 사용하여 클라이언트의 공용 IPv4 주소를 확인하십시오. 해당 주소가 Debian 서버의 송신 주소와 일치해야 합니다.

흔히 발생하는 문제점과 그 실제 의미

완전 터널형 도로와 분할형 도로, 어떤 것을 선택해야 할까요?

신뢰할 수 없는 Wi-Fi에서 트래픽을 보호하거나 인터넷 트래픽이 Debian 서버에서 나가도록 하려면 전체 터널링을 사용하십시오. 서버, 홈 네트워크, 연구실 또는 내부 애플리케이션에 대한 원격 액세스만 필요하고 일반 인터넷 트래픽은 로컬에 유지하려는 경우에는 분할 터널링을 사용하십시오. 어떤 방식을 선택할지는 주로 클라이언트의 설정에 따라 결정됩니다 AllowedIPs.

소규모 지점 간 구축의 경우, 위와 같은 구성으로 유지 관리 가능한 기본 설정을 구축할 수 있습니다. 클라이언트당 하나의 피어 블록, 고유한 터널 주소, Debian에서 관리하는 서비스, 그리고 실제로 필요한 라우팅 동작을 위한 nftables만 있으면 됩니다. 하지만 대규모 구축의 경우, WireGuard 프로토콜 자체는 단순하지만 키 배포, 피어 수명 주기, DNS, 로깅 및 구성 관리 등이 운영상의 고려 사항이 됩니다.

최종 확인 체크리스트

• wg-quick@wg0활성화되어 있으며 다음과 같은 wg0특징을 가지고 있습니다 10.8.0.1/24.
• 서버는 UDP 포트를 사용하며 51820, 해당 포트는 상위 방화벽이나 라우터를 통해서도 접근 가능합니다.
• 모든 클라이언트는 고유한 키 쌍과 /32서버에 등록된 고유한 항목을 가지고 있습니다.
• net.ipv4.ip_forward1라우팅 액세스가 필요한 경우 와 같습니다 .
• nftables 마스킹은 의도적으로 라우팅된 반환 경로를 사용하지 않는 한 전체 터널 인터넷 액세스에 사용됩니다.
• wg show클라이언트가 트래픽을 전송한 후 최근 핸드셰이크 정보를 표시합니다.
• 고객의 설계는 AllowedIPs의도된 전체 터널 또는 분할 터널 설계와 일치합니다.

이 단계는 Debian 12 및 Debian에서 제공하는 표준 WireGuard 도구를 대상으로 합니다. 네트워크 토폴로지, 업스트림 NAT, 클라우드 방화벽, 사설 LAN 라우팅 및 IPv6 정책은 환경에 따라 다르므로 WireGuard 구성만으로는 이러한 요소를 추론할 수 없습니다. 모든 연결 문제를 WireGuard 오류로 간주하지 말고 각 요소를 개별적으로 검증하십시오.