GDNSDCTL(8) gdnsd GDNSDCTL(8)

gdnsdctl - ابزار کنترل دیمن gdnsd

Usage: gdnsdctl [-c /etc/gdnsd] [-s <IP:port>] [-D] [-l] [-t 47] [-o] [-i] <action> [...]
  -c - Configuration directory (def /etc/gdnsd), for finding UNIX control socket path
  -s - TCP control socket address
  -D - Enable verbose debug output
  -l - Send logs to syslog rather than stderr
  -t - Timeout in seconds (def 47, range 5 - 300)
  -o - One-shot mode: do not retry soft failures (comms errors, replace-in-progress)
  -i - Ignore lack of a running daemon for stop, reload-zones, replace,
       and acme-dns-01-flush, reporting success instead of failure in those cases.
Actions:
  stop - Stops the running daemon
  reload-zones - Reload the running daemon's zone data
  replace - Ask daemon to spawn a takeover replacement of itself (updates code, config, zone data)
  status - Checks the running daemon's status
  stats - Dumps JSON statistics from the running daemon
  states - Dumps JSON monitored states
  acme-dns-01 - Create ACME DNS-01 payloads from additional arguments:
                <name> <payload> <name> <payload> ... [max %u payloads]
  acme-dns-01-flush - Flush (remove) all ACME DNS-01 payloads added above

gdnsdctl کلاینت رسمی سوکت کنترلی برای gdnsd است. تمامی عملیات شرح‌داده‌شده در بالا همگام (synchronous) هستند و موفقیت را با خروج با وضعیت صفر، و شکست را با وضعیت غیرصفر گزارش می‌دهند.

به‌طور کلی، gdnsd و gdnsdctl از اجرای هم‌روند کنش‌های گوناگون از سوی چندین عامل علیه یک دیمن واحد پشتیبانی می‌کنند؛ و در صورت نبود اشکالات دیگر، در نهایت همه چیز بدون هیچ‌گونه باگ ناشی از شرایط رقابتی (race conditions) با موفقیت گزارش خواهد شد.

به بیان دیگر، برای نمونه اگر سیستم مدیریت پیکربندی شما به‌طور مرتب دستور "gdnsdctl replace" را برای اعمال به‌روزرسانی‌های پیکربندی اجرا کند، و ابزار دیگری مستقلاً و به‌طور مرتب دستور "gdnsdctl reload-zones" را هم‌گام با به‌روزرسانی داده‌های فایل‌های زون اجرا نماید، در حالی که مجموعه ابزار سومی در حال اجرای دستورات "gdnsdctl acme-dns-01" باشد، حتی اگر هر ۳ دستور با زمان‌بندی تقریباً هم‌زمان با یکدیگر تلاقی کنند، وضعیت پایدار و قابل اطمینان خواهد بود. در نهایت هر ۳ دستور "gdnsdctl" پایان خواهند یافت و وضعیت حاصل شامل تمامی به‌روزرسانی‌های پیکربندی، داده‌های زون و اعتبارسنجی‌ها خواهد بود.

این موضوع همچنین در مورد اجراهای چندگانه، مستقل و هم‌پوشان یک کنش یکسان صادق است؛ مانند چندین درخواست "reload-zones" که به‌طور موازی پیش می‌روند، یا چندین درخواست "acme-dns-01".

دایرکتوری پیکربندی را تعیین می‌کند؛ پیش‌فرض /etc/gdnsd است. این گزینه برای یافتن پرونده پیکربندی دیمن اصلی و تجزیه آن استفاده می‌شود، در صورتی که دیمن مقدار غیرپیش‌فرضی را برای "run_dir" تنظیم کرده باشد، که در این صورت مسیر سوکت کنترلی یونیکس دیمن تغییر می‌کند.
به gdnsdctl اعلام می‌کند که به جای سوکت محلی معمول حوزه یونیکس (UNIX domain socket)، از طریق یک سوکت کنترلی TCP به دیمن متصل شود. برای اطلاعات بیشتر درباره پیکربندی سمت سرور این ویژگی، به مستندات gdnsd.config(5) ذیل "tcp_control" مراجعه کنید.
خروجی گزارش در سطح اشکال‌زدایی (debug) بیشتر را در صورت لزوم فعال می‌کند.
خروجی گزارش‌ها را به جای stderr پیش‌فرض، به syslog ارسال می‌کند.
مهلت زمانی (timeout) بر حسب ثانیه (پیش‌فرض ۴۷، در محدوده ۵ تا ۳۰۰) را برای کل فرآیند اجرا تعیین می‌کند. این مقدار از طریق تایمر فرآیندی SIGALRM اعمال می‌شود، اما در موارد خاص ممکن است اندکی بیشتر از زمان تعیین‌شده به طول بینجامد.
حالت تک‌تلاشه (One-shot). در شرایط عادی، gdnsdctl در صورت بروز شکست‌های نرم (soft failures) تلاش مجدد را به صورت مداوم ادامه می‌دهد. شرایط شکست نرم زمانی رخ می‌دهد که دیمن در بحبوحه عملیات "replace" باشد، یا خطای ارتباطی پس از برقراری اتصال اولیه رخ دهد (که می‌تواند نتیجه رقابتی ناشی از تلاقی نامناسب با خاموش شدن دیمن قدیمی در طول عملیات "replace" باشد). این گزینه تلاش‌های مجدد را غیرفعال کرده و تمامی خطاهای نرم (قابل تلاش مجدد) را به خطاهای سخت (بلافاصله مهلک) تبدیل می‌کند.
حالت نادیده‌گرفتن دیمن متوقف‌شده. در شرایط معمول، اگر هیچ دیمنی در حال اجرا نباشد، تمامی کنش‌ها با شکست مواجه می‌شوند. با تنظیم این فلگ، چنانچه دیمن در حال حاضر در حال اجرا نباشد، اما کنش درخواستی از جمله کنش‌های محدودی باشد که مقصود آن با راه‌اندازی آتی دیمن به‌درستی محقق می‌شود، gdnsdctl علیرغم فعال نبودن دیمن، مقدار خروجی موفقیت‌آمیز را برمی‌گرداند.

مجموعه دستوراتی که در حال حاضر از "-i" پشتیبانی می‌کنند عبارتند از: "reload-zones"، "stop"، "acme-dns-01-flush" و "replace".

دیمن در حال اجرا را به‌طور همگام متوقف می‌کند. وضعیت خروج صفر بدین معناست که توقف دیمن مطابق دستور مشاهده و تایید شده است.

با گزینه "-i"، وضعیت خروج صفر می‌تواند به این معنا نیز باشد که دیمن از قبل در حال اجرا نبوده است، که این امر "gdnsdctl -i stop"; را به یک دستور بی‌اثر بر توقف مجدد (idempotent stop) تبدیل می‌کند.

فایل‌های زون دیمن را به‌طور همگام بازخوانی (reload) می‌کند. وضعیت خروج صفر نشان می‌دهد که عملیات با موفقیت پایان یافته و داده‌های جدید برای کلاینت‌ها قابل مشاهده است.

با گزینه "-i"، وضعیت خروج صفر می‌تواند به این معنا نیز باشد که دیمن در حال اجرا نبوده است (اگر در آینده راه‌اندازی شود، فایل‌های زونِ اخیراً به‌روزرسانی‌شده اعمال خواهند شد).

از دیمن در حال اجرا می‌خواهد که یک نمونه جایگزین از خود ایجاد کند (spawn). این قابلیت می‌تواند برای ارتقای کد دیمن و/یا تغییرات پیکربندی استفاده شود. روند اجرای "replace" طوری طراحی شده است که از اکثر جهات کمترین تاثیر عملیاتی را داشته باشد: بدون شرایط رقابتی است، درخواست‌ها گم یا دور ریخته نمی‌شوند و هیچ وقفه‌ای در پردازش درخواست‌ها ایجاد نمی‌شود. داده‌های آماری (stats) به صورت یکپارچه از نمونه قدیمی به نمونه جدید تحویل داده می‌شوند، همچنین داده‌های موقت چالش ACME DNS-01 نیز منتقل می‌گردند. سوکت کنترلی در تمام مدت برای اتصالات جدید در دسترس باقی می‌ماند، اما پردازش واقعی اتصالات جدید برای مدت زمان کوتاهی به تعویق می‌افتد.

دستورات ارسال‌شده از سوی کلاینت‌های سوکت کنترلی که از پیش متصل شده‌اند (مانند gdnsdctl) ممکن است در طول بازه‌های زمانی حیاتی از توالی جایگزینی با پاسخ شکست نرم رد شوند، اما gdnsdctl منتظر مانده و پس از آن مجدداً تلاش خواهد کرد.

دیمن جایگزین در ابتدا به عنوان فرزند دیمن در حال اجرا اجرا می‌شود و بدین ترتیب بسیاری از ویژگی‌های محیط اجرای آن را به ارث می‌برد. دیمن‌های قدیم و جدید فرآیند تحویل را از طریق یک اتصال سوکت کنترلی میان‌دیمنی هماهنگ می‌کنند. فرآیند تحویل نهایت تلاش خود را می‌کند تا اطمینان یابد در صورت شکست دیمن جدید در هر مرحله‌ای از راه‌اندازی، دیمن قدیمی بتواند عملیات خود را مانند قبل ادامه دهد.

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

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

تمامی دیگر عملیات gdnsdctl که وضعیت دیمن را تغییر می‌دهند (هر عملیاتی به‌جز کنش‌های فقط‌خواندنی "status"، "stats" و "states") و ممکن است به‌طور جداگانه و هم‌روند آغاز شده باشند، مادامی که بخش حیاتی توالی تحویل جایگزینی در جریان است صریحاً توسط دیمن مسدود می‌شوند. gdnsdctl به‌طور پیش‌فرض یک کنش را مکرراً تکرار می‌کند تا عملیات جایگزینی به پایان برسد و اجازه عبور کنش را بدهد یا مهلت زمانی "-t" فرا برسد. فلگ "-o" این تلاش‌های مجدد را غیرفعال می‌کند که موجب می‌شود کنش‌های تغییردهنده وضعیت gdnsdctl در طول بازه حساس جایگزینی فوراً با شکست مواجه شوند.

به‌طور معمول، اگر دیمنی در حال اجرا نباشد، این دستور با شکست مواجه خواهد شد. با این حال، با فلگ "-i"، وضعیت خروج صفر می‌تواند به این معنا نیز باشد که دیمن در حال اجرا نبوده است (اگر در آینده راه‌اندازی شود، پیکربندی یا فایل اجراییِ اخیراً به‌روزرسانی‌شده که تمایل به اجرای درخواست "replace" را برانگیخته بود، آن زمان اعمال خواهد شد).

سیستم تلاش مجدد برای اجرای هم‌روند "replace" در برابر "replace" نیز کار می‌کند: اگر چندین دستور "gdnsdctl replace" را به‌طور هم‌روند اجرا کنید، یکی از آن‌ها ابتدا پیش می‌رود و باقی در حلقه‌های تلاش مجدد منتظر می‌مانند تا هر کدام نوبت خود را برای جایگزینی ترتیبی دیمن طی کنند تا زمانی که همگی با موفقیت انجام شوند، مگر اینکه مهلت زمانی "-t" در gdnsdctl زودتر منقضی شود (راه‌اندازی هر دیمن جدید، بسته به تعداد فایل‌های زون و پیچیدگی پیکربندی، مدتی زمان خواهد برد).

وضعیت دیمن در حال اجرا را بررسی می‌کند و PID و نگارش آن را به stderr گزارش می‌دهد.
آمار دیمن در حال اجرا را در قالب JSON به stdout می‌ریزد.
وضعیت‌های پایش‌شده را از هر پایشگر سلامت سرویسِ پیکربندی‌شده، در قالب JSON تخلیه می‌کند.
محتواهای بار داده (payloads) موقت پاسخ چالش ACME DNS-01 را مطابق با تعریف https://tools.ietf.org/html/draft-ietf-acme-acme-14 به دیمن در حال اجرا تزریق می‌کند. این کنش برای یکپارچه‌سازی با اسکریپت‌ها یا سرویس‌هایی در نظر گرفته شده است که گواهی‌های امضاشده را از مرجع صدور گواهی با قابلیت ACME تولید می‌کنند.

دو یا چند آرگومان خط فرمان دیگر مورد نیاز است که به صورت جفت‌های "name" و "payload" ارائه می‌شوند، که در آن "name" یک نام دامنه معتبر و "payload" محتوای پاسخ چالش است (که به عنوان یک خروجی SHA-256 کدگذاری‌شده با قالب base64url، باید ۴۳ بایت طول داشته و تنها شامل حروف، ارقام و نویسه‌های "-" و "_" باشد). در هر بار فراخوانی gdnsdctl حداکثر ۱۰۰ بار داده مجزا را می‌توان تعیین کرد.

این مثال...

gdnsdctl acme-dns-01 example.org 012345678901234567890123456789012 www.example.org ABCDEFGHIJKLMNOPQRSTUVWXYZ-abcdefghijklmnop

... باعث می‌شود دیمن به‌طور موقت به درخواست‌های "TXT" برای نام "_acme-challenge.example.org." با نخستین بار داده بالا، و به همین ترتیب با دومین بار داده برای "_acme-challenge.www.example.org." پاسخ دهد.

پاسخ‌های محتوای چالشی تزریق‌شده توسط این دستور، به‌طور خودکار پس از مدت کوتاهی منقضی می‌شوند. زمان پیش‌فرض ۱۰ دقیقه است و از طریق گزینه پیکربندی "acme_challenge_ttl" قابل تنظیم می‌باشد. TTL واقعی DNS که همراه با پاسخ‌های "TXT" ارسال می‌شود، به‌طور پیش‌فرض صفر است (که اکیداً توصیه می‌شود!) و با گزینه جداگانه "acme_challenge_dns_ttl" کنترل می‌گردد.

تزریق پاسخ‌ها برای نام‌های دامنه‌ای که در محدوده یکی از زون‌های پیکربندی‌شده ایستا نیستند موفقیت‌آمیز خواهد بود، اما پاسخ به چنین پرس‌وجوهایی همچنان "REFUSED" خواهد ماند (تا زمانی که در آینده چنین زونی پدیدار شود، در صورت وقوع).

اگر بیش از یک بار داده برای یک نام مشخص تعیین شود (در همان دستور یا در دستورات مجزا با فاصله زمانی کمتر از پنجره TTL)، چندین رکورد TXT صادر خواهد شد. چنانچه داده‌های TXT از پیش پیکربندی‌شده ایستا از فایل‌های زون با نام متداخل "_acme-challenge" وجود داشته باشد، رکوردهای منبع (RR) ایستای TXT نیز در کنار هر داده‌ای از این سازوکار ارائه خواهند شد.

به عنوان یک جزئیات پیاده‌سازی (یا رفتار خاص؟) در این سازوکار، هر رکورد ایستای فایل زون که اولین بخش برچسب آن "_acme-challenge" باشد، صرف‌نظر از TTL تعیین‌شده در فایل زون، TTL آن به‌طور خودکار روی "acme_challenge_dns_ttl" اجبار خواهد شد. این ساده‌ترین راه برای اطمینان از این نکته بود که هرگز مقادیر ترکیبی TTL را در یک مجموعه رکوردهای منبع (RR-set) واحد از رکوردهای TXT ارائه ندهیم، که طبق RFC 2181 ممنوع است.

داده‌های تزریق‌شده توسط این سازوکار در طول عملیات "replace" دیمن پابرجا می‌مانند، اما با توقف کامل ("stop") دیمن باقی نمی‌مانند. همچنین این داده‌ها در بازخوانی‌های فایل‌های زون پابرجا می‌مانند، و در صورتی که داده‌ها برای زونی تزریق شوند که وجود نداشته باشد و سپس از طریق بازخوانی زون پدید آید، چالش پس از بازخوانی شروع به کار خواهد کرد.

بلافاصله تمام داده‌های بار داده تزریق‌شده از دستور بالا را پیش از انقضای طبیعی آن‌ها پاکسازی (flush) می‌کند. این کنش بیشتر برای آزمایش یا پاکسازی اشتباهات مفید است، اما برخی سامانه‌های یکپارچه‌سازی با حجم‌های بالای مقطعی چالش‌ها ممکن است مایل باشند داده‌ها را در زمان‌هایی که هیچ چالش DNS-01 فعالی وجود ندارد، صریحاً پاکسازی کنند.

این دستور دیگری است که از گزینه "-i" پشتیبانی می‌کند: اگر "-i" تعیین شود و دیمن در حال اجرا نباشد، این دستور موفقیت را گزارش می‌کند؛ زیرا یک دیمن غیرفعال، داده چالشی برای پاکسازی ندارد.

به‌طور کلی، تمامی عملیات با وضعیت خروج صفر پایان می‌یابند اگر و تنها اگر عملیات موفقیت‌آمیز باشد. خطاها و بیشتر خروجی‌های دیگر به stderr ارسال می‌شوند، به‌جز موارد تخلیه داده‌های JSON که به stdout ارسال می‌گردند.

gdnsd(8), gdnsd.config(5), gdnsd.zonefile(5)

راهنمای gdnsd.

Copyright (c) 2012 Brandon L Black <blblack@gmail.com>

این پرونده بخشی از gdnsd است.

نرم‌افزار gdnsd یک نرم‌افزار آزاد است: می‌توانید آن را تحت شرایط مجوز عمومی همگانی گنو (GNU General Public License) منتشرشده توسط بنیاد نرم‌افزار آزاد، نگارش ۳ مجوز یا (به انتخاب خودتان) هر نگارش بالاتری بازتوزیع کرده و/یا تغییر دهید.

نرم‌افزار gdnsd به این امید توزیع شده است که مفید واقع شود، اما بدون هرگونه ضمانت؛ حتی بدون ضمانت ضمنی قابل فروش بودن یا مناسب بودن برای یک هدف مشخص. برای جزئیات بیشتر به مجوز عمومی همگانی گنو مراجعه کنید.

باید همراه با gdnsd نسخه‌ای از مجوز عمومی همگانی گنو را دریافت کرده باشید. در غیر این صورت، نشانی http://www.gnu.org/licenses را ببینید.

2026-04-04 gdnsd 3.8.3