wireguard:ko [Command Line Interface Helper]

이 문서는 읽기 전용입니다. 원본을 볼 수는 있지만 바꿀 수는 없습니다. 문제가 있다고 생각하면 관리자에게 문의하세요.
{{tag>[network vpn wireguard linux windows macos security]}}

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

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

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

===== Components =====
^ 구성 요소 ^ 역할 ^ 문서 ^
| WireGuard protocol/interface | encrypted tunnel과 peer model | 현재 페이지 |
| ''wg'' | WireGuard 전용 runtime configuration과 상태 조회 | [[wireguard:wg:ko|wg]] |
| ''wg-quick'' | 일반적인 interface lifecycle, address, route, DNS 보조 | [[wireguard:wg-quick:ko|wg-quick]] |
| configuration file | ''[Interface]'', ''[Peer]'' 및 helper 확장 설정 | [[wireguard:config:ko|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 설치 절차와 확인 방법은 [[wireguard:wg:ko#installation|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 설정과 상태 확인은 [[wireguard:wg:ko|wg]]가 담당한다.
  * 단순한 file 기반 tunnel 시작·종료는 [[wireguard:wg-quick:ko|wg-quick]]이 담당한다.
  * systemd에서는 배포판이 제공하는 ''wg-quick@INTERFACE'' unit을 사용할 수 있다.
  * 같은 interface를 NetworkManager, systemd unit, 직접 실행한 helper가 동시에 관리하지 않도록 owner를 하나로 정한다.

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

===== 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 이름으로 문서화하지 않는다.

===== See Also =====
  * [[wireguard:wg:ko|wg]]
  * [[wireguard:wg-quick:ko|wg-quick]]
  * [[wireguard:config:ko|WireGuard configuration]]
  * [[networkmanager:ko|NetworkManager]]
  * [[linux:rhel:firewalld|firewalld]]
  * [[https://www.wireguard.com/install/|WireGuard Installation]]
  * [[https://www.wireguard.com/quickstart/|WireGuard Quick Start]]

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

{{indexmenu>.#1|js}}