رفع خطاهای Netplan در Ubuntu؛ حل مشکل YAML، Route و Gateway

اگر بعد از ویرایش فایل‌های Netplan با خطای YAML، هشدار gateway4 has been deprecated، مشکل Route یا قطع‌شدن اینترنت سرور روبه‌رو شده‌اید، معمولاً لازم نیست Netplan را حذف یا شبکه را از ابتدا نصب کنید. بیشتر این مشکلات از تورفتگی اشتباه YAML، نام نادرست کارت شبکه، تعریف قدیمی Gateway یا ایجاد چند Default Route متناقض ناشی می‌شوند.

Netplan چیست و چرا یک خطای کوچک YAML شبکه را قطع می‌کند؟

Netplan سیستم تعریف تنظیمات شبکه در بسیاری از نسخه‌های Ubuntu است. شما وضعیت موردنظر کارت شبکه، IP، DNS و Route را در فایل YAML تعریف می‌کنید و Netplan این تنظیمات را برای Backend شبکه مانند systemd-networkd یا NetworkManager تولید می‌کند.

به همین دلیل، فاصله‌گذاری اشتباه یا قرار گرفتن یک گزینه در سطح نادرست YAML می‌تواند باعث شود تنظیم شبکه تولید نشود. روی VPS این موضوع حساس‌تر است؛ زیرا یک Default Gateway اشتباه ممکن است همان ارتباط SSH مورد استفاده برای تعمیر سرور را هم قطع کند.

مرحله ۱: قبل از تغییر Netplan وضعیت فعلی شبکه را پیدا کنید

اول نام واقعی Interface، IP فعلی و Default Route را بررسی کنید. این مرحله فقط اطلاعات را نمایش می‌دهد و تنظیم شبکه را تغییر نمی‌دهد.

ip -br address
ip route
ls -la /etc/netplan/
sudo netplan get

ممکن است نام کارت شبکه سرور شما ens3، ens18، eth0، enp1s0 یا نام دیگری باشد. نام Interface را از خروجی واقعی سرور بردارید و نام نمونه این مقاله را بدون بررسی کپی نکنید.

در نسخه‌هایی که فرمان مربوطه موجود است، دستور زیر نیز نمای مناسبی از وضعیت شبکه، IP، DNS و Route می‌دهد:

sudo netplan status --all

مرحله ۲: قبل از ویرایش از Netplan بکاپ بگیرید

اگر سرور از راه دور مدیریت می‌شود، قبل از تغییر شبکه یک نسخه از تنظیمات فعلی نگه دارید:

sudo cp -a /etc/netplan /root/netplan-backup

مرحله ۳: پیدا کردن خطاهای YAML در Netplan

YAML به ساختار و تورفتگی حساس است. یکی از متداول‌ترین مشکلات این است که گزینه‌ای مانند addresses، routes یا nameservers در سطح اشتباه قرار می‌گیرد.

برای بررسی فایل‌ها بدون اعمال تنظیم جدید اجرا کنید:

sudo netplan generate

فرمان netplan generate فایل‌های YAML را می‌خواند و پیکربندی Backend را تولید می‌کند، اما تنظیم تولیدشده را روی شبکه در حال اجرا اعمال نمی‌کند. بنابراین برای پیدا کردن بسیاری از خطاهای Syntax انتخاب مناسبی است.

نمونه ساختار صحیح YAML

فرض کنیم IP آزمایشی سرور 192.0.2.10/24، Gateway برابر 192.0.2.1 و Interface برابر ens3 است. ساختار می‌تواند به این شکل باشد:

network:
  version: 2
  renderer: networkd
  ethernets:
    ens3:
      dhcp4: false
      addresses:
        - 192.0.2.10/24
      routes:
        - to: default
          via: 192.0.2.1
      nameservers:
        addresses:
          - 1.1.1.1
          - 8.8.8.8

این IPها صرفاً مثال هستند. IP، Prefix، Gateway و Interface واقعی را باید از اطلاعات شبکه VPS یا تنظیمات فعلی سرور دریافت کنید.

رفع هشدار gateway4 has been deprecated

در تنظیمات قدیمی Netplan معمولاً Default Gateway به شکل زیر نوشته می‌شد:

gateway4: 192.0.2.1

اما gateway4 و gateway6 در مستندات فعلی Netplan Deprecated هستند. روش جدید تعریف Default Route برای IPv4 چنین است:

routes:
  - to: default
    via: 192.0.2.1

برای IPv4 می‌توان مقصد را به‌صورت 0.0.0.0/0 نیز تعریف کرد، اما default خواناتر است.

خطای Default Route و چند Gateway

اگر سرور چند Interface داشته باشد، تعریف چند Default Route در جدول اصلی می‌تواند باعث خطا یا مسیر نامشخص شود. Netplan برای هر خانواده IP و Routing Table انتظار Default Route بدون ابهام دارد.

اگر واقعاً به دو مسیر پیش‌فرض نیاز دارید، باید طراحی Routing مشخص باشد. در یک سناریوی ساده که هدف انتخاب مسیر اصلی و پشتیبان است، می‌توان Metric متفاوت تعریف کرد:

routes:
  - to: default
    via: 192.0.2.1
    metric: 100

عدد Metric کمتر معمولاً مسیر دارای اولویت بیشتر را مشخص می‌کند. برای Multi-WAN، چند IP عمومی با مسیرهای برگشت متفاوت یا Source-based Routing، صرفاً اضافه‌کردن Metric همیشه کافی نیست و ممکن است به Routing Table و routing-policy جداگانه نیاز داشته باشید.

چه زمانی on-link: true لازم می‌شود؟

در بعضی زیرساخت‌های VPS، Gateway ظاهراً خارج از Subnet تعریف‌شده برای IP سرور است. در چنین شرایطی Route معمولی ممکن است Gateway را قابل دسترس تشخیص ندهد.

اگر ارائه‌دهنده سرور صراحتاً چنین ساختاری را برای شبکه اعلام کرده باشد، Route می‌تواند به شکل زیر تعریف شود:

routes:
  - to: default
    via: 192.0.2.1
    on-link: true

خطای YAML: inconsistent indentation یا mapping values are not allowed

اگر Netplan شماره خط مشخصی را نمایش می‌دهد، همان قسمت و خطوط قبل از آن را بررسی کنید. در YAML ساختار والد و فرزند با فاصله مشخص می‌شود.

🔹 از Tab برای تورفتگی استفاده نکنید.

🔹 سطح گزینه‌هایی مانند addresses، routes و nameservers را بررسی کنید.

🔹 بعد از کلیدهایی مانند network: و ethernets: ساختار زیرمجموعه باید صحیح باشد.

🔹 خط تیره قبل از اعضای فهرست مانند IPها و Routeها را فراموش نکنید.

🔹 فایل‌های دیگر داخل /etc/netplan/ را هم بررسی کنید؛ Netplan می‌تواند چند فایل YAML را با هم بخواند.

وجود چند فایل YAML؛ خطایی که به‌راحتی دیده نمی‌شود

گاهی فایل اصلی کاملاً صحیح است، اما یک فایل YAML دیگر نیز در Netplan وجود دارد و تنظیمات آن با فایل جدید ترکیب می‌شود. برای مشاهده فایل‌ها اجرا کنید:

ls -la /etc/netplan/
sudo netplan get

Netplan فایل‌های پیکربندی را با ترتیب مشخصی پردازش و در صورت وجود چند فایل، تنظیمات آن‌ها را merge یا override می‌کند. بنابراین فقط بررسی یک فایل همیشه کافی نیست.

رفع Warning مربوط به Permission فایل Netplan

فایل‌های YAML شبکه ممکن است اطلاعات حساسی مانند رمز Wi-Fi یا کلیدهای شبکه داشته باشند. مستندات Netplan دسترسی محدود برای این فایل‌ها را توصیه می‌کنند. برای فایل موردنظر می‌توانید مجوز را روی 600 قرار دهید:

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

روش امن اعمال Netplan روی VPS بدون ریسک غیرضروری قطع SSH

بعد از اصلاح فایل، ابتدا Syntax و قابلیت تولید پیکربندی را بررسی کنید:

sudo netplan generate

اگر خطایی نمایش داده نشد، روی اتصال راه دور بهتر است ابتدا اجرا کنید:

sudo netplan try

Netplan تنظیم جدید را موقت اعمال می‌کند و برای تأیید منتظر می‌ماند. اگر ارتباط سالم باقی ماند، تنظیم را تأیید کنید. در حالت معمول، اگر تأیید انجام نشود، Netplan تلاش می‌کند تنظیم قبلی را برگرداند.

بعد از اعمال تنظیمات چه چیزهایی را تست کنیم؟

بعد از تأیید Netplan، وضعیت IP و Route را دوباره بررسی کنید:

ip -br address
ip route
sudo netplan status --all

سپس دسترسی شبکه را مرحله‌ای بررسی کنید:

ping -c 4 1.1.1.1
getent hosts ubuntu.com

اگر Ping به IP کار می‌کند ولی نام دامنه Resolve نمی‌شود، مشکل احتمالاً از DNS است، نه Default Route. اگر حتی IP عمومی قابل دسترس نیست، IP، Prefix، Gateway و جدول Route را دوباره بررسی کنید.

اگر بعد از Netplan اینترنت سرور قطع شد چه کنیم؟

از کنسول سرور وارد شوید و ابتدا وضعیت را بررسی کنید:

ip -br address
ip route
sudo netplan generate
sudo netplan get

اگر قبلاً طبق این آموزش بکاپ گرفته‌اید و مطمئن هستید نسخه بکاپ همان تنظیم سالم قبلی است، می‌توانید پس از بررسی محتویات آن برای بازیابی استفاده کنید. روی سرور عملیاتی فایل‌ها را بدون بررسی کورکورانه جایگزین نکنید.

خطاهای رایج Netplan و راه‌حل آن‌ها

پرسش‌های متداول درباره خطاهای Netplan

آیا gateway4 هنوز در Netplan کار می‌کند؟

ممکن است در برخی نسخه‌ها همچنان پذیرفته شود، اما در مستندات Netplan Deprecated اعلام شده است. برای تنظیم جدید بهتر است Default Gateway را با routes تعریف کنید.

فرق netplan generate و netplan apply چیست؟

netplan generate پیکربندی Backend را از روی YAML تولید می‌کند و برای تشخیص خطاهای پیکربندی مفید است؛ اما netplan apply تنظیمات را روی شبکه در حال اجرا اعمال می‌کند.

برای VPS بهتر است netplan apply اجرا کنیم یا netplan try؟

وقتی از راه SSH متصل هستید، برای تغییراتی که ممکن است دسترسی شبکه را مختل کنند، netplan try انتخاب امن‌تری برای آزمایش اولیه است؛ چون تنظیم جدید نیازمند تأیید است و در صورت تأیید نشدن قابلیت بازگشت دارد.

آیا on-link: true را همیشه کنار Gateway قرار دهیم؟

خیر. این گزینه زمانی کاربرد دارد که Route باید Gateway را روی همان Link در نظر بگیرد؛ برای مثال در بعضی طراحی‌های خاص شبکه VPS. استفاده بی‌دلیل از آن می‌تواند عیب‌یابی را دشوارتر کند.

چرا با وجود درست بودن فایل Netplan هنوز Route اشتباه است؟

وجود فایل YAML دیگر، Route دریافتی از DHCP، چند Interface، Metric یا Routing Policy می‌تواند نتیجه نهایی را تغییر دهد. خروجی netplan get و ip route را بررسی کنید.

چطور بفهمیم مشکل از DNS است یا Gateway؟

ابتدا یک IP عمومی را Ping کنید. اگر ارتباط با IP برقرار است ولی Resolve دامنه با getent hosts شکست می‌خورد، DNS یکی از اولین مواردی است که باید بررسی شود. اگر IP عمومی هم قابل دسترس نیست، Route و Gateway را بررسی کنید.

منابع فنی

🔹 مستندات رسمی Netplan؛ مرجع YAML، Default Route، routes، routing-policy و gateway4/gateway6.

🔹 Netplan Tutorial؛ مرجع netplan get، netplan status، netplan try و روش اعمال تنظیمات.

🔹 Netplan Security؛ مرجع Permission پیشنهادی برای فایل‌های YAML.