WireGuard

WireGuard는 UDP 위에서 동작하는 간결한 VPN tunnel protocol이자 tunnel interface 기술이다. wireguard라는 이름의 공통 CLI command가 있는 것은 아니며, command-line 관리는 주로 wireguard-tools의 wg와 wg-quick을 사용한다.

Summary

wg는 WireGuard interface의 암호화·peer 설정과 runtime 상태를 조회·변경한다.
wg-quick은 configuration file을 바탕으로 interface, address, route와 선택적 DNS 설정을 적용한다.
AllowedIPs는 송신 route 선택과 수신 source IP 허용 목록 역할을 동시에 하므로 단순 ACL로만 취급하지 않는다.
private key와 preshared key는 wiki, shell history, process argument, Git에 기록하지 않는다.

명령 예시에서 executable 이름으로 wireguard를 사용하지 않는다. 제품·protocol 문서는 이 페이지에 두고, 실제 명령의 syntax와 option은 각각의 command page에서 관리한다.

Components

구성 요소	역할	문서
WireGuard protocol/interface	encrypted tunnel과 peer model	현재 페이지
`wg`	WireGuard 전용 runtime configuration과 상태 조회	wg
`wg-quick`	일반적인 interface lifecycle, address, route, DNS 보조	wg-quick
configuration file	`[Interface]`, `[Peer]` 및 helper 확장 설정	WireGuard configuration

Linux에서는 interface 자체를 ip link로 만들고 address와 route를 ip address·ip route로 관리할 수 있다. wg-quick은 흔한 구성을 단순화하는 wrapper이며 복잡한 network policy에서는 NetworkManager 같은 별도 manager를 사용할 수 있다.

Installation

설치 package는 운영체제에 따라 kernel support, CLI tools, GUI client를 함께 또는 따로 제공한다. 실제 command 설치 절차와 확인 방법은 wg Installation을 참고한다.

Debian / Ubuntu: upstream은 wireguard package를 안내한다.
Fedora: upstream은 wireguard-tools package를 안내한다.
RHEL: upstream의 명시적 절차는 RHEL 8용이므로 다른 major version에 그대로 적용하지 않는다.
macOS: GUI client는 App Store, basic CLI는 Homebrew 또는 MacPorts로 설치할 수 있다.
Windows: 공식 installer 또는 MSI를 사용한다. wg utility는 제공되지만 Unix shell script인 wg-quick workflow와는 다르다.

Operation Model

key 생성, peer의 runtime 설정과 상태 확인은 wg가 담당한다.
단순한 file 기반 tunnel 시작·종료는 wg-quick이 담당한다.
systemd에서는 배포판이 제공하는 wg-quick@INTERFACE unit을 사용할 수 있다.
같은 interface를 NetworkManager, systemd unit, 직접 실행한 helper가 동시에 관리하지 않도록 owner를 하나로 정한다.

SSH session이 사용하는 default route나 source address를 WireGuard로 바꾸면 원격 연결이 즉시 끊길 수 있다. full tunnel 설정을 적용하기 전에 console 또는 out-of-band 복구 경로와 rollback 절차를 준비한다.

Compatibility

Linux kernel 5.6 이상에는 WireGuard가 in-tree로 포함되어 있다. 배포판 kernel과 package 조합은 해당 배포판 지침을 우선한다.
BSD, macOS, Windows의 interface·service·DNS·route integration은 Linux와 다르다.
Windows의 wireguard executable은 manager/service용 command surface이며, 범용 command 이름으로 문서화하지 않는다.

History

codex:: 2026-08-13 WireGuard 설치, key 관리, wg/wg-quick 운용, service와 troubleshooting 문서를 추가했다.
codex:: 2026-08-13 제품·protocol 문서와 실제 wg, wg-quick command reference를 분리했다.

목차