{{tag>[cli wg-quick wireguard network vpn linux security]}}

====== wg-quick ======
''wg-quick''은 common use case에서 WireGuard interface를 간단히 시작하고 종료하는 script다. ''wg''와 운영체제의 network command를 감싸 address, MTU, route, 선택적 DNS와 hook을 함께 처리한다.

===== Summary =====
  * ''up''은 interface를 만들고 configuration, address, MTU와 route를 적용한다.
  * ''down''은 interface를 종료·제거하고 선택적으로 현재 설정을 저장한다.
  * ''save''는 interface를 내리지 않고 현재 configuration을 저장한다.
  * ''strip''은 ''wg-quick'' 전용 key를 제거해 ''wg''에 전달할 형식으로 출력한다.

===== Installation =====
''wg-quick''은 Unix 계열 환경의 ''wireguard-tools''에 포함된다.

==== Debian / Ubuntu ====
<code bash>
sudo apt update
sudo apt install wireguard
</code>

==== Fedora ====
<code bash>
sudo dnf install wireguard-tools
</code>

==== RHEL 8 ====
<code bash>
sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm https://www.elrepo.org/elrepo-release-8.el8.elrepo.noarch.rpm
sudo yum install kmod-wireguard wireguard-tools
</code>

이 upstream 절차는 RHEL 8 전용이다. 다른 major version에는 그대로 적용하지 않는다.

==== macOS ====
<code bash>
brew install wireguard-tools
</code>

==== Windows ====
Windows용 WireGuard는 native manager와 tunnel service를 사용하며 Unix shell script인 ''wg-quick''을 기본 workflow로 제공하지 않는다.

==== 설치 확인 ====
<code bash>
wg-quick --help
</code>

<note important>
현재 문서 작성 환경에는 ''wg-quick''이 설치되어 있지 않아 live help를 실행하지 않았다. command와 동작은 upstream ''wg-quick(8)'' manual을 기준으로 정리했다.
</note>

===== Usage =====
  * ''<color #c3c3c3>**wg-quick**</color> <color #ff7f27>up|down|save|strip</color> <color #7092be>INTERFACE|CONFIG_FILE</color>''

<code bash>
sudo wg-quick up wg0
sudo wg-quick down wg0
</code>

interface 이름만 주면 일반적으로 ''/etc/wireguard/INTERFACE.conf''를 찾는다. file path를 직접 줄 때는 file 이름이 interface 이름과 같은 ''INTERFACE.conf'' 형식이어야 한다.

===== Commands =====
^ Command ^ 역할 ^
| ''up'' | interface 생성, configuration·address·route 적용과 up hook 실행 |
| ''down'' | down hook 실행, 선택적 저장과 interface 제거 |
| ''save'' | 활성 interface의 configuration을 file에 저장 |
| ''strip'' | ''wg-quick'' 확장 key를 제외한 ''wg'' configuration 출력 |

===== Interface Lifecycle =====
==== 일회성 시작과 종료 ====
<code bash>
sudo wg-quick up wg0
sudo wg-quick down wg0
</code>

==== systemd에서 자동 시작 ====
<code bash>
sudo systemctl enable --now wg-quick@wg0
systemctl status wg-quick@wg0 --no-pager
journalctl -u wg-quick@wg0 -b --no-pager
</code>

<note warning>
full tunnel 설정으로 SSH session의 default route나 source address가 바뀌면 연결이 즉시 끊길 수 있다. console 접근과 ''sudo wg-quick down wg0'' rollback 경로를 먼저 확보한다.
</note>

===== Configuration =====
''wg-quick''은 ''wg'' configuration에 ''Address'', ''DNS'', ''MTU'', ''Table'', ''PreUp'', ''PostUp'', ''PreDown'', ''PostDown'', ''SaveConfig''를 확장한다. 전체 작성법은 [[wireguard:config:ko|WireGuard configuration]]을 참고한다.

==== wg 형식으로 변환 ====
<code bash>
sudo wg-quick strip wg0
</code>

출력에는 secret이 포함될 수 있으므로 terminal log나 ticket에 그대로 공유하지 않는다.

==== 활성 interface에 차이 반영 ====
<code bash>
sudo wg syncconf wg0 <(sudo wg-quick strip wg0)
</code>

이 방식은 ''wg''가 이해하는 peer 설정 변경에 적합하다. address, DNS, route, MTU 또는 hook이 바뀌면 ''down'' 후 ''up''이 필요할 수 있다.

==== SaveConfig 주의 ====
<note important>
''SaveConfig = true''이면 ''down'' 시 runtime 상태가 configuration file을 덮어쓸 수 있다. 선언적 file을 source of truth로 관리한다면 일반적으로 생략하고 변경 전 backup을 보관한다.
</note>

===== Troubleshooting =====
==== 시작 실패 ====
<code bash>
sudo wg-quick up wg0
systemctl status wg-quick@wg0 --no-pager
journalctl -u wg-quick@wg0 -b --no-pager
sudo wg-quick strip wg0
</code>

configuration file permission, key 형식, CIDR, interface 중복, 필요한 ''resolvconf'' 또는 firewall command의 존재 여부를 확인한다.

==== route 또는 DNS 문제 ====
  * ''AllowedIPs''에서 자동 생성된 route와 기존 route가 충돌하는지 확인한다.
  * default route가 포함되면 policy routing과 firewall mark도 함께 확인한다.
  * Linux의 ''DNS'' 처리는 ''resolvconf''를 호출할 수 있으므로 resolver manager와의 호환성을 확인한다.
  * MTU 문제로 특정 크기의 packet만 실패하면 path MTU와 ''MTU'' 설정을 점검한다.

===== Compatibility =====
  * ''wg-quick''은 단순한 use case용 helper다. 복잡한 policy는 NetworkManager 또는 명시적인 network configuration이 더 적합할 수 있다.
  * route, DNS, firewall helper 동작과 configuration 검색 경로는 운영체제·배포판별로 다를 수 있다.
  * Windows에서는 native WireGuard manager와 service workflow를 사용한다.

===== Help =====
++++ wg-quick --help |
<code text>
</code>
++++

===== See Also =====
  * [[wireguard:ko|WireGuard]]
  * [[wireguard:wg:ko|wg]]
  * [[wireguard:config:ko|WireGuard configuration]]
  * [[networkmanager:ko|NetworkManager]]
  * [[https://git.zx2c4.com/wireguard-tools/about/src/man/wg-quick.8|wg-quick(8)]]

===== History =====
  * codex:: 2026-08-13 WireGuard 문서에서 wg-quick command reference를 분리했다.

{{indexmenu>.#1|js}}