기술자료

적용 환경

작업 전 준비사항

현재 설정 파일과 런타임 네트워크 정보를 백업합니다. 백업 디렉터리 이름에는 작업 시각을 포함해 여러 번의 수정본을 구분하는 것이 좋습니다.

sudo mkdir -p /root/netplan-backup
sudo cp -a /etc/netplan /root/netplan-backup/netplan-before-fix
ip -br link | sudo tee /root/netplan-backup/ip-link.txt
ip -br address | sudo tee /root/netplan-backup/ip-address.txt
ip route | sudo tee /root/netplan-backup/ip-route.txt

백업 후에도 현재 SSH 세션은 종료하지 말고, 복구가 완료될 때까지 유지하십시오.

현재 네트워크 상태 확인

1. 실제 네트워크 인터페이스 이름 확인

Netplan 설정의 장치명이 실제 인터페이스 이름과 다르면 해당 설정은 적용되지 않습니다. 먼저 커널이 인식한 장치명과 링크 상태를 확인합니다.

ip -br link
ip -br address
ls -1 /sys/class/net

출력에서 lo를 제외한 ens3, enp1s0, eth0 등의 실제 장치명을 확인합니다. 장치가 DOWN 상태라면 설정 문제뿐 아니라 가상 NIC 연결, 케이블, 하이퍼바이저 설정도 함께 점검해야 합니다.

2. 주소와 기본 경로 확인

ip address show
ip route show

• 인터페이스에 IPv4 주소가 없다면 DHCP 실패 또는 Netplan 장치명·주소 설정 오류를 의심합니다.
• default via 게이트웨이 dev 인터페이스 형태의 기본 경로가 없다면 외부 네트워크로 통신할 수 없습니다.
• 주소와 기본 경로가 정상인데 도메인만 접속되지 않으면 DNS 설정을 우선 점검합니다.

3. 현재 Netplan 상태 확인

업데이트된 Ubuntu 22.04의 Netplan에서는 다음 명령으로 구성 상태를 확인할 수 있습니다.

sudo netplan status --all

Netplan 설정 파일 점검

1. 적용되는 YAML 파일 목록 확인

Netplan은 /etc/netplan/ 아래의 여러 .yaml 파일을 함께 읽습니다. 이전 설정 파일이 남아 있으면 동일한 인터페이스나 기본 경로가 중복 정의될 수 있습니다.

sudo find /etc/netplan -maxdepth 1 -type f -name '*.yaml' -printf '%f\n'
sudo grep -RnsE '^(network:|[[:space:]]+(renderer|ethernets|wifis|addresses|routes|gateway4|nameservers|dhcp4):)' /etc/netplan

수정할 파일을 열기 전에 전체 내용을 줄 번호와 함께 확인합니다.

sudo grep -Rns . /etc/netplan --include='*.yaml'

2. YAML 들여쓰기와 필수 구조 확인

YAML은 탭이 아닌 공백으로 들여쓰기해야 합니다. 최상위에는 network:가 있어야 하며 그 아래에 version: 2와 장치 유형이 올바른 단계로 배치되어야 합니다.

• 탭 문자를 사용하지 않습니다.
• 같은 단계의 키는 동일한 수의 공백으로 들여씁니다.
• IP 주소에는 /24와 같은 CIDR 접두사 길이를 포함합니다.
• Ubuntu 22.04에서는 기본 경로를 routes:와 to: default로 표현할 수 있습니다.
• DHCP와 고정 주소를 동시에 사용할 목적이 아니라면 dhcp4: true와 수동 주소를 불필요하게 함께 지정하지 않습니다.

탭 문자가 포함되어 있는지 확인하려면 다음 명령을 사용합니다. 출력이 없으면 탭 문자가 발견되지 않은 것입니다.

sudo grep -Rn $'\t' /etc/netplan --include='*.yaml'

3. 설정 파일 권한 확인

Netplan 공식 문서는 YAML 파일을 root 사용자만 읽고 쓸 수 있는 600 권한으로 관리하도록 안내합니다.

sudo chown root:root /etc/netplan/*.yaml
sudo chmod 600 /etc/netplan/*.yaml
sudo ls -l /etc/netplan

정상적으로 변경되면 권한 부분이 -rw-------로 표시됩니다.

4. 적용 전에 구문과 정의 검사

다음 명령은 백엔드용 설정을 생성하면서 YAML 구문과 Netplan 키를 검사하지만, 현재 네트워크에는 적용하지 않습니다.

sudo netplan --debug generate

오류가 출력되면 표시된 파일명과 줄 번호를 먼저 수정합니다. 오류 없이 명령이 종료된 뒤에만 실제 적용 단계로 이동하십시오.

DHCP 및 고정 IP 설정 복구

DHCP 환경 복구 예시

DHCP로 주소를 자동 할당받는 서버라면 다음과 같이 구성할 수 있습니다. Ubuntu Server에서는 일반적으로 networkd 렌더러를 사용합니다.

network:
  version: 2
  renderer: networkd
  ethernets:
    enp1s0:
      dhcp4: true
      dhcp6: false

고정 IPv4 환경 복구 예시

고정 IP를 사용하는 경우 주소, 기본 경로와 DNS 서버를 함께 확인합니다.

network:
  version: 2
  renderer: networkd
  ethernets:
    enp1s0:
      dhcp4: false
      addresses:
        - 203.0.113.10/24
      routes:
        - to: default
          via: 203.0.113.1
      nameservers:
        addresses:
          - 1.1.1.1
          - 8.8.8.8

Ubuntu Desktop처럼 NetworkManager가 장치를 관리해야 하는 환경에서는 기존 설치 방식과 파일을 확인한 뒤 렌더러를 다음처럼 지정합니다.

network:
  version: 2
  renderer: NetworkManager

설정을 안전하게 적용하는 방법

1. 생성 단계에서 다시 검사

sudo netplan --debug generate

이 명령은 백엔드 설정을 만들지만 실행 중인 네트워크에는 적용하지 않습니다. 구문 오류나 알 수 없는 키가 표시되면 먼저 수정합니다.

2. 자동 롤백이 가능한 시험 적용

원격 서버에서는 netplan try를 우선 사용합니다. 변경 후 터미널에 확인 메시지가 나타나며, 제한 시간 안에 승인하지 않으면 이전 설정으로 되돌리도록 설계되어 있습니다.

sudo netplan try

시험 적용 후 별도의 터미널에서 서버로 다시 접속하고, 게이트웨이·외부 IP·DNS 통신을 확인한 뒤 설정을 승인합니다.

3. 최종 적용

콘솔에서 작업하거나 시험 적용과 재접속 검증을 마쳤다면 현재 설정을 적용합니다.

sudo netplan apply

오류 원인을 더 자세히 확인해야 할 때는 sudo netplan --debug apply를 사용합니다.

네트워크 연결 확인

설정 적용 후에는 링크, IP 주소, 라우팅, 인터넷 연결과 DNS를 분리해 확인해야 원인을 빠르게 좁힐 수 있습니다.

1. 링크와 IP 주소 확인

ip -br link
ip -br address
ip route show

대상 인터페이스가 UP 상태이고, 예상한 IP 주소와 기본 경로가 표시되는지 확인합니다.

2. 게이트웨이와 외부 IP 통신 확인

ping -c 4 203.0.113.1
ping -c 4 1.1.1.1

첫 번째 주소는 실제 게이트웨이로 바꿔 실행합니다. ICMP를 차단하는 네트워크에서는 ping 실패만으로 연결 장애를 단정하지 말고 라우팅과 서비스 접속도 함께 확인하십시오.

3. DNS 확인

resolvectl status
resolvectl query ubuntu.com

외부 IP에는 연결되지만 도메인 조회만 실패한다면 nameservers 들여쓰기, DNS 주소, systemd-resolved 상태와 /etc/resolv.conf 링크를 확인합니다.

systemctl status systemd-resolved --no-pager
ls -l /etc/resolv.conf

일반적인 Ubuntu 22.04 구성에서는 /etc/resolv.conf가 /run/systemd/resolve/ 아래의 파일을 가리키는 심볼릭 링크로 관리됩니다.

백엔드 서비스와 로그 확인

Netplan은 YAML을 직접 네트워크에 적용하는 데몬이 아니라 systemd-networkd 또는 NetworkManager용 설정을 생성합니다. 사용 중인 렌더러에 맞는 서비스를 확인해야 합니다.

systemd-networkd 사용 환경

systemctl status systemd-networkd --no-pager
networkctl list
networkctl status
journalctl -u systemd-networkd -b --no-pager

로그에서 대상 장치가 구성되지 않은 이유, DHCP 임대 실패, 주소 또는 경로 적용 실패 메시지를 확인합니다.

NetworkManager 사용 환경

systemctl status NetworkManager --no-pager
nmcli device status
nmcli connection show
journalctl -u NetworkManager -b --no-pager

렌더러는 networkd인데 NetworkManager만 활성화되어 있거나, 그 반대인 경우에는 장치가 예상한 백엔드에서 관리되지 않을 수 있습니다. 기존 설치 유형에 맞는 렌더러와 서비스 구성을 유지하십시오.

임시 네트워크 복구

Netplan 파일을 즉시 수정하기 어렵고 서버 콘솔에는 접속할 수 있다면, 런타임에 주소와 기본 경로를 임시로 추가해 원격 접근을 복구할 수 있습니다. 다음 값은 실제 환경에 맞게 변경해야 합니다.

sudo ip link set enp1s0 up
sudo ip address add 203.0.113.10/24 dev enp1s0
sudo ip route add default via 203.0.113.1 dev enp1s0
sudo resolvectl dns enp1s0 1.1.1.1 8.8.8.8

임시 연결이 복구되면 원격 세션을 유지한 상태에서 올바른 Netplan YAML을 작성하고 netplan generate와 netplan try로 영구 설정을 검증합니다.

DHCP 환경이라면 수동 주소를 임의로 추가하지 말고 먼저 올바른 인터페이스 이름으로 DHCP용 Netplan 설정을 복구하는 것이 안전합니다.

자주 발생하는 오류와 해결 방법

원상복구 방법

수정 후 네트워크가 더 불안정해졌다면 서버 콘솔에서 백업한 Netplan 디렉터리를 복원합니다.

sudo cp -a /etc/netplan /root/netplan-backup/netplan-failed-change
sudo mv /etc/netplan "/etc/netplan.failed.$(date +%Y%m%d%H%M%S)"
sudo cp -a /root/netplan-backup/netplan-before-fix /etc/netplan
sudo chown -R root:root /etc/netplan
sudo chmod 600 /etc/netplan/*.yaml
sudo netplan --debug generate
sudo netplan apply

복원 후 ip address, ip route, resolvectl status와 외부 접속을 다시 확인합니다.

백업 자체가 잘못된 경우에는 서버 사업자가 제공한 원래 IP 주소, 게이트웨이, 서브넷과 DNS 정보를 기준으로 최소한의 단일 YAML 파일부터 다시 작성하십시오.

관련 VISION IDC 기술자료

• PuTTY를 이용한 리눅스 SSH 접속 방법
• VISION IDC 서버 운영 기술자료

자주 묻는 질문

Netplan 파일 이름은 반드시 정해진 이름을 사용해야 하나요?

파일 이름은 고정되어 있지 않지만 /etc/netplan/ 아래에 .yaml 확장자로 저장해야 합니다. 여러 파일이 함께 처리될 수 있으므로 중복 정의를 피하고, 운영자가 용도를 알 수 있는 이름을 사용하는 것이 좋습니다.

설정 파일을 수정할 때 네트워크 서비스를 직접 재시작해야 하나요?

일반적으로 netplan apply가 백엔드 설정을 생성하고 적절한 네트워크 백엔드를 호출합니다. 문제 진단 목적이 아니라면 먼저 서비스를 직접 재시작하기보다 Netplan 명령으로 적용하는 것이 좋습니다.

IP 주소는 있는데 인터넷만 연결되지 않는 이유는 무엇인가요?

기본 경로가 없거나 게이트웨이가 잘못된 경우가 많습니다. ip route에서 기본 경로를 확인하고, 외부 IP 통신이 되지만 도메인만 실패하면 DNS 문제로 구분해 점검하십시오.

SSH가 끊긴 뒤에도 netplan try가 항상 자동 복구하나요?

자동 롤백 기능이 있지만 모든 가상 장치와 복잡한 네트워크 구성에서 완전한 복구를 보장할 수는 없습니다. 원격 서버에서는 별도 콘솔과 설정 백업을 반드시 함께 준비해야 합니다.

Ubuntu Server에서 renderer를 NetworkManager로 바꿔도 되나요?

가능하지만 NetworkManager 패키지와 서비스가 실제로 설치·활성화되어 있어야 하며 기존 운영 방식도 함께 변경됩니다. 단순 장애 해결을 위해 렌더러를 임의로 바꾸기보다 현재 시스템이 사용하던 백엔드를 확인하고 그 구성을 복구하는 것이 안전합니다.

공식 참고자료