مرجع CLI

دستور nardeboon سرویس نردبون، یعنی nardeboond، را روی همان دستگاهی که اجرایش می‌کنید کنترل می‌کند. همه‌ی دستورها --json را می‌پذیرند و کدهای خروج ثابت‌اند؛ پس هر چیزی که در این صفحه می‌بینید در اسکریپت‌ها هم کار می‌کند.

اجرای دستورها

nardeboon از طریق سوکت کنترلی /run/nardeboon/nardeboond.sock با سرویس ارتباط برقرار می‌کند. دستورها را با root اجرا کنید، یا کاربرتان را به گروه nardeboon اضافه کنید تا بدون sudo اجرایشان کنید:

sudo usermod -aG nardeboon "$USER"

عضویت در گروه از ورود بعدی‌تان به سیستم اعمال می‌شود. بدون هیچ‌کدام از این دو، دستورها با کد 7 (permission) خارج می‌شوند. در این صفحه، دستورهایی که تنظیمات را تغییر می‌دهند با sudo نوشته شده‌اند.

فایل‌ها و نام‌ها

خلاصه‌ی دستورها

اتصال

nardeboon up

nardeboon up [flags]

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

وقتی چیزی که به up می‌دهید باید از طرف سرور کنترل جواب بگیرد (کلید احراز هویت، نامی تازه، یا زیرشبکه یا نود خروجی‌ای که دستگاه پیشنهاد می‌کند)، up منتظر همان جواب می‌ماند، و اگر رد شود، مثلاً کلید معتبر نباشد، همین را به‌عنوان خطا برمی‌گرداند. مدت این انتظار را --timeout تعیین می‌کند؛ سرویس بعد از آن هم به تلاش ادامه می‌دهد.

sudo nardeboon up --auth-key "$NB_AUTH_KEY" --hostname web-1

nardeboon down

nardeboon down

اتصال این دستگاه را قطع می‌کند. سرویس همچنان در حال اجرا می‌ماند و دستگاه از حساب خارج نمی‌شود؛ پس nardeboon up دوباره وصلش می‌کند.

sudo nardeboon down

nardeboon login و nardeboon logout

nardeboon login
nardeboon logout

login یک لینک چاپ می‌کند. آن را در مرورگر باز کنید، وارد حسابتان شوید و شبکه را انتخاب کنید تا دستگاه به‌عنوان دستگاه شما و با قوانین تأیید همان شبکه به آن بپیوندد. هر لینک فقط یک بار و تا ده دقیقه کار می‌کند. login کلید منقضی‌شده‌ی دستگاه را هم تازه می‌کند.

logout دستگاه را از حساب خارج می‌کند: کلیدش منقضی می‌شود و دستگاه آن را پاک می‌کند. دستگاه در داشبورد می‌ماند، پس login آن را با همان نام و آدرس برمی‌گرداند.

sudo nardeboon login

To connect this device, open this link and sign in:

  https://app.nardeboon.io/connect/C6qEHb3wExNT

Connected: web-1 (100.83.20.5) on home.

nardeboon status

nardeboon status

اتصال، شبکه، آدرس‌های این دستگاه، دستگاه‌های دیگر شبکه و هشدارها را نشان می‌دهد؛ مثلاً هشدار در دسترس نبودن سرور کنترل. جدول اول خودِ این دستگاه را می‌آورد، بعد هر دستگاه دیگر را با endpointی که از آن گرفته می‌شود (یک آدرس مستقیم، یا رله‌ای که از آن می‌گذرد) و ترنسپورتی که آن را حمل می‌کند.

nardeboon status

Connected to network home as mypc (10.77.12.4)
  Control plane: direct

DEVICE    ADDRESS       OS     ENDPOINT                    TRANSPORT  STATUS
mypc      10.77.12.4    linux  -                           -          this device
gateway   10.77.3.17    linux  198.51.100.8:41641          nb-udp     online
hetzner   10.77.20.5    linux  via Frankfurt (Global Relay)  nb-udp   active, 12s ago
laptop    10.77.40.7    linux  -                           -          offline

خط Control plane می‌گوید دستگاه از چه راهی به سرور کنترل رسیده: direct (مستقیم)، از درِ جلویی سرور کنترل، یا از طریق یک peer یا یکی از relayهای شبکه که جلسه‌اش را رد می‌کند، با اسمش (در --json زیر control با via و through و since). روی شبکه‌ای که اتصال‌هایی را که خود دستگاه شروع می‌کند قطع می‌کند و اتصال‌هایی را که دیگران شروع کنند راه می‌دهد (مثل دیتاسنترهای سخت‌گیرِ ایران)، یک خط همین را می‌گوید: آن‌وقت دستگاه هیچ‌وقت خودش به دستگاهی در جای دیگر اتصال شروع نمی‌کند و از آن می‌خواهد شروعش کند (در --json با callee). روی دستگاهی که برای شبکه‌اش relay است، یا یکی از Global Relayهای نردبون، یک خط همین را می‌گوید، با اینکه الان چند دستگاه از آن عبور می‌کنند، از وقتی روشن شده چقدر ترافیک رد کرده، و روی چه پورت‌هایی گوش می‌دهد تا فایروالِ جلویش آن‌ها را باز کند (در --json با relaying). دستگاهی که الان با آن ترافیک ردوبدل می‌شود active است. اگر دستگاه وصل باشد status با کد 0 تمام می‌شود، اگر روی هیچ شبکه‌ای نباشد با 4 و اگر قطع باشد با 5. با --json در هر حالت وضعیت را گزارش می‌کند.

مسیرها و عیب‌یابی

nardeboon path status

nardeboon path status

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

nardeboon path status

PEER      STATE    PATH                          TRANSPORT   RTT     LOSS   JITTER   CAPACITY     FEC
hetzner   active   via Frankfurt (Global Relay)  nb-udp      96 ms   2.1%   3 ms     48 Mbit/s    +40%, 12 rebuilt
laptop    active   direct                        nb-udp      1 ms    0.0%   1 ms     610 Mbit/s   -
nas       idle     direct                        nb-udp      -       -      -        -            -
phone     offline  -                             -           -       -      -        -            -

ستون STATE می‌گوید از مسیر چه می‌دانیم: active یعنی مسیر جواب می‌دهد؛ idle یعنی مدتی است ترافیکی با آن دستگاه نبوده، پس چیزی مسیر را اندازه نمی‌گیرد، و مسیری که نشان داده می‌شود همان است که بسته‌ی بعدی از آن می‌رود؛ searching یعنی ترافیک هست ولی هنوز هیچ مسیری جواب نداده؛ offline یعنی سرور کنترل آن دستگاه را آفلاین می‌بیند و هیچ مسیری جواب نمی‌دهد؛ no path یعنی هیچ مسیری برای امتحان نیست. اعداد فقط برای مسیری نشان داده می‌شوند که جواب می‌دهد.

ستون CAPACITY مقداری است که اندازه گرفته شده مسیر می‌تواند منتقل کند (مسیرها و رله‌ها را ببینید)؛ تا وقتی اندازه گرفته نشده - است، و فقط وقتی اندازه گرفته می‌شود که این دستگاه به اندازه‌ی کافی برای آن دستگاه داده بفرستد.

ستون FEC تصحیح خطای پیش‌رو روی مسیری است که بسته گم می‌کند: parityای که این دستگاه به داده‌هایی که برای آن دستگاه می‌فرستد اضافه می‌کند (+40%)، و تعداد بسته‌هایی از آن دستگاه که از parityِ آن بازسازی شده‌اند.

nardeboon path optimize

nardeboon path optimize

مسیرها را همین حالا اندازه می‌گیرد و دوباره ارزیابی می‌کند، به‌جای اینکه منتظر اندازه‌گیری بعدی بماند.

nardeboon path optimize

nardeboon path explain

nardeboon path explain <peer>

امتیازدهی کامل را برای یک دستگاه نشان می‌دهد: همه‌ی مسیرهای کاندید، مستقیم یا از طریق رله، با معیارها و امتیاز کلی از ۱۰۰، و اینکه چرا مسیر فعلی انتخاب شده است. مسیری که استفاده نمی‌شود، هر جا دلیلش معلوم باشد، آن را می‌گوید؛ و همه‌ی رله‌هایی که دستگاه می‌تواند از آن‌ها استفاده کند فهرست می‌شوند، و آن‌هایی که دستگاه به آن‌ها وصل نیست با دلیلش. مسیرها و رله‌ها را ببینید.

nardeboon path explain hetzner

PATH                          TRANSPORT   RTT     LOSS   JITTER   CAPACITY    SCORE
via Frankfurt (Global Relay)  nb-udp      96 ms   0.1%   3 ms     48 Mbit/s   84  ✓ chosen
direct 203.0.113.9:41641      nb-udp      -       -      -        -           no path
direct 203.0.113.9:47391      nb-tls      -       -      -        -           no path
via am-vps                    -           -       -      -        -           this device isn't attached to it: it doesn't answer this device's hellos

Chose via Frankfurt (Global Relay): the best overall score of the paths that work.

روی شبکه‌ای که اتصالِ شروع‌شده از خودِ دستگاه را قطع می‌کند، یک مسیر مستقیم ممکن است بگوید waits for the peer to call: دستگاه شروعِ اتصال را به طرف مقابل می‌سپارد (ترنسپورت‌ها را ببینید).

nardeboon path pin

nardeboon path pin <peer> <route>
nardeboon path unpin <peer>

مسیر این دستگاه به یک دستگاه دیگر را سنجاق می‌کند: تا وقتی آن مسیر جواب می‌دهد از همان می‌رود و وقتی جواب ندهد، مثل همیشه مسیر را انتخاب می‌کند. مسیر یا direct است، یا اسم یکی از رله‌های شبکه، یا اسم یا کد منطقه‌ی یک Global Relay. سنجاقِ این دستگاه، فقط روی همین دستگاه، به سنجاقی که مدیران شبکه برای همان دستگاه مقابل گذاشته‌اند اولویت دارد. پلنی می‌خواهد که سنجاق کردن مسیر را شامل شود. مسیرها و رله‌ها را ببینید.

sudo nardeboon path pin hetzner tr1

The path to hetzner is pinned via tr1: it takes that route while it answers, and is chosen as usual while it doesn't.

nardeboon ping

nardeboon ping [--transport <name>] <peer>

بدون --transport، بررسی می‌کند که دستگاهی در دسترس هست یا نه، از همان مسیری که این دستگاه الان برایش به کار می‌برد، و پاسخ می‌گوید مسیر از کدام ترنسپورت رفت. هر ثانیه یک ping می‌فرستد تا یکی جواب بگیرد، حداکثر ده ثانیه: اولین بسته به دستگاهی که مدتی بیکار بوده منتظر handshake تونل می‌ماند. اگر دستگاه شناخته‌شده باشد ولی فعلاً هیچ مسیری کار نکند، ping با کد 10 (unreachable) خارج می‌شود.

--transport <name> (nb-udp، nb-udp-dco، nb-tls یا nb-wss) به‌جای آن، رسیدن مستقیم به دستگاه را روی همان ترنسپورت می‌آزماید — مثلاً برای اینکه ببینید آیا nb-tls به یک دستگاه می‌رسد. nb-udp-dco، nb-tls و nb-wss به پورت‌هایی می‌روند که دستگاه برایشان اعلام کرده است (برای دو تای آخر، درِ ورودی‌اش). دستگاهی که فقط از طریق رله در دسترس است هیچ مسیر مستقیمی روی هیچ ترنسپورتی ندارد، پس دستور با کد 10 خارج می‌شود.

nardeboon ping --transport nb-tls hetzner

pong from hetzner (100.83.20.5): direct 203.0.113.9:47391, nb-tls, 112 ms

پاسخ می‌گوید از کدام راه آمد: direct و نشانی دستگاه، یا via و یک رله؛ یا رله‌ای از خودِ شبکه‌ی شما (relay)، یا یکی از Global Relayهای نردبون که با نام منطقه‌اش آمده (Global Relay)؛ و بعد ترنسپورتِ گام اول (روی شبکه‌ای که UDP را می‌بندد، nb-tls). درست بعد از روشن شدن دستگاه ممکن است مسیر هنوز جا نیفتاده باشد و پاسخ فقط زمان را بگوید. با --json، کد منطقه‌ی Global Relay در relay_region و ترنسپورت در transport است، همان‌طور که برای هر دستگاه در status.

nardeboon netcheck

nardeboon netcheck

گزارش می‌دهد شبکه‌ی فعلی چه چیزهایی را اجازه می‌دهد: NAT این دستگاه را چطور map می‌کند، از بیرون کجا دیده می‌شود، IPv6 دارد یا نه، اگر پورتی روی NAT باز شده چطور باز شده، کدام ترنسپورت‌ها می‌توانند ترافیک را ببرند، و به کدام رله‌ها می‌رسد. دستگاهِ پشت NATِ «سخت» (address- and port-dependent) تا وقتی مسیر مستقیم باز شود به رله نیاز دارد؛ دستگاهِ پشت NATِ «آسان» (endpoint-independent) بیشتر peerها را مستقیم می‌گیرد.

nardeboon netcheck

NAT type:         endpoint-independent mapping (easy)
Seen from:        198.51.100.20
Flows it starts:  let through
IPv6:             no
Port mapping:     NAT-PMP
On battery:       no
Metered:          no

Transports:
  nb-udp     ok
  nb-tls     ok
  nb-wss     ok

Relays:
  Frankfurt (Global Relay)  reaching, 31 ms
  node4                     reaching, 4 ms

Seen from جایی است که سرور کنترل دستگاه را می‌بیند؛ اگر نشود از سرور کنترل پرسید، جایی است که peerهایش می‌بینند، با علامت (by peers). Flows it starts می‌گوید شبکه با اتصالی که خودِ دستگاه باز می‌کند چه می‌کند: let through (رد می‌شود)، یا cut after a few packets (بعد از چند بسته قطع می‌شود) در شبکه‌هایی مثل دیتاسنترهای سخت‌گیرِ ایران که چیزی را که دیگران شروع کنند راه می‌دهند و چیزی را که دستگاه شروع کند قطع می‌کنند؛ آن‌وقت peerها با دستگاه تماس می‌گیرند. این از یک پورت جداگانه سنجیده می‌شود، پس به اتصال‌های تونل دست نمی‌زند.

nb-tls و nb-wss با «در ورودی» حداکثر سه رله هم‌زمان و حداکثر پنج ثانیه سنجیده می‌شوند: اگر یکی جواب بدهد ok، اگر هیچ‌کدام نه blocked، و اگر هیچ رله‌ای چنین دری نداشته باشد unavailable. دستگاه فقط وقتی سراغشان می‌رود که nb-udp رد نشود، پس روی شبکه‌ای که UDP کار می‌کند خودش هیچ اتصال fallbackی باز نمی‌کند. nb-udp وقتی ok است که reflectorِ سرور کنترل یا یک peer از رویش جواب بدهد. کل بررسی چند ثانیه طول می‌کشد؛ کنار هر رله زمان رفت‌وبرگشتِ آخرین جوابش آمده است.

Port mapping نشان می‌دهد پورت چطور روی NAT باز شده — NAT-PMP، PCP یا UPnP — یا هیچ. port mapping به‌طور پیش‌فرض روشن است؛ یک شبکه می‌تواند از داشبورد خاموشش کند.

شبکه

nardeboon dns

nardeboon dns status
nardeboon dns query <name>

dns status تنظیمات DNS این دستگاه را نشان می‌دهد: دامنه‌ی شبکه، split DNS، اینکه بقیه‌ی نام‌ها کجا می‌روند و resolver سیستم چطور به نردبون سپرده شده است. dns query یک نام را، یا یک آدرس را به‌صورت معکوس، با همان روشی که این دستگاه به کار می‌برد پیدا می‌کند و نشان می‌دهد جواب از کجا آمده است. DNS و نام دستگاه‌ها را ببینید.

nardeboon dns query hetzner

hetzner.home.nb.internal   A   100.83.20.5

nardeboon route

nardeboon route list
nardeboon route advertise [<ranges…>]
nardeboon route accept [on|off]

برخلاف up، دستورهای advertise و accept فقط همان تنظیم را عوض می‌کنند: دستگاهی که وصل است وصل می‌ماند و دستگاهی که قطع است قطع می‌ماند.

sudo nardeboon route accept

Subnet route را ببینید.

nardeboon exit-node

nardeboon exit-node list
nardeboon exit-node set <name>
nardeboon exit-node clear

list فهرست نودهای خروجی قابل استفاده برای این دستگاه را نشان می‌دهد و می‌گوید از کدام استفاده می‌کند. set ترافیک اینترنت این دستگاه را از یکی از آن‌ها، با نام یا آدرسش، عبور می‌دهد و clear استفاده از آن را متوقف می‌کند. اگر نود خروجی قطع شود، ترافیک اینترنت به‌جای اینکه مستقیم بیرون برود متوقف می‌شود. این دستورها هم مثل route فقط همان تنظیم را عوض می‌کنند. نود خروجی را ببینید.

sudo nardeboon exit-node set hetzner

nardeboon whois

nardeboon whois <ip|name>

یک دستگاه را با IP یا نامش شناسایی می‌کند. اگر چیزی پیدا نشود، با کد 6 (not-found) خارج می‌شود.

nardeboon whois 100.83.20.5

نگهداری

nardeboon update

nardeboon update check
nardeboon update apply
nardeboon update channel <c>

دستگاه‌ها خودکار به‌روز می‌شوند. check می‌گوید دستگاه چه نسخه‌ای را روی کدام کانال اجرا می‌کند، چطور نصب شده و آیا نسخه‌ی امضاشده‌ی جدیدتری آمده است؛ apply همین حالا نصبش می‌کند؛ channel کانال (stable یا beta) را نشان می‌دهد یا عوض می‌کند. فقط نسخه‌های امضاشده نصب می‌شوند و هیچ‌وقت نسخه‌ی قدیمی‌تر: اگر بررسی امضا یا یکپارچگی شکست بخورد، دستور با کد 9 (verify) خارج می‌شود. nardeboon set auto-update off به‌روزرسانی خودکار را روی این دستگاه خاموش می‌کند. نصب روی Linux را ببینید.

nardeboon update check
sudo nardeboon update apply

nardeboon version

nardeboon version

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

nardeboon bugreport

nardeboon bugreport [--out <file>]

یک بسته‌ی عیب‌یابی روی همین دستگاه می‌سازد و آن را در پوشه‌ی فعلی، یا در --out، طوری می‌نویسد که فقط خودتان بتوانید بخوانید. تنظیمات و وضعیت دستگاه، نام و آدرس و مسیر همتاها، اینکه شبکه‌ی فعلی چه اجازه‌ای می‌دهد، آدرس‌ها و routeها و تنظیمات DNS تونل و آخرین خط‌های لاگ سرویس در آن است. هیچ کلید یا داده‌ی حساسی ندارد: نه کلیدها و وضعیت دستگاه، نه نقشه‌ی شبکه و نه لینک ورود. تا وقتی خودتان آن را به اشتراک نگذارید روی دستگاه می‌ماند؛ پس می‌توانید اول بررسی‌اش کنید.

nardeboon set

nardeboon set <setting> <value>

یکی از تنظیمات این دستگاه را عوض می‌کند و اتصال را همان‌طور که هست نگه می‌دارد. تنظیم‌ها همان‌هایی‌اند که up به‌عنوان گزینه می‌گیرد:

sudo nardeboon set accept-routes on

خروجی JSON

--json را به هر دستوری اضافه کنید. خروجی همیشه همین ساختار ثابت را دارد:

{"schema": "nardeboon.<command>/v1", "ok": true, "data": { ... }}
{"schema": "nardeboon.<command>/v1", "ok": false, "error": {"code": "offline", "message": "..."}}

• schema نام دستور و نسخه‌ی قالب خروجی آن را نشان می‌دهد.
• ok نشان می‌دهد دستور موفق بوده یا نه. پیش از خواندن data آن را بررسی کنید.
• در صورت خطا، error جای data را می‌گیرد: code برای برنامه‌هاست و message برای آدم‌ها. code دلیل دقیق را می‌گوید، مثل needs_login، invalid_auth_key، not_found یا unreachable، و کد خروج این دلیل‌ها را دسته‌بندی می‌کند.

nardeboon status --json | jq '.ok'

کدهای خروج

کدهای خروج ثابت و مستندند:

برای کد 3، وضعیت سرویس را با systemctl status nardeboond بررسی کنید.

اسکریپت‌ها می‌توانند بر اساس این کدها تصمیم بگیرند:

nardeboon ping hetzner > /dev/null
case $? in
  0)  echo "hetzner is reachable" ;;
  5)  echo "not connected: run nardeboon up" ;;
  10) echo "hetzner is known, but no path works right now" ;;
  *)  echo "ping failed" ;;
esac