PUPPET-AGENT(8) راهنمای OpenVox PUPPET-AGENT(8)

puppet-agent - دیمن عامل puppet ارائه‌شده توسط OpenVox

پیکربندی کلاینت را از سرور OpenVox دریافت کرده و آن را بر روی میزبان محلی اعمال می‌کند.

این سرویس می‌تواند به عنوان یک دیمن، به صورت دوره‌ای با استفاده از cron (یا سازوکارهای مشابه)، یا به صورت تعاملی برای اهداف آزمایشی اجرا شود.

puppet agent [--certname NAME] [-D|--daemonize|--no-daemonize] [-d|--debug] [--detailed-exitcodes] [--digest DIGEST] [--disable [MESSAGE]] [--enable] [--fingerprint] [-h|--help] [-l|--logdest syslog|eventlog|ABS FILEPATH|console] [--serverport PORT] [--noop] [-o|--onetime] [--sourceaddress IP_ADDRESS] [-t|--test] [-v|--verbose] [-V|--version] [-w|--waitforcert SECONDS]

این برنامه، کلاینت اصلی puppet است. وظیفه آن دریافت پیکربندی ماشین محلی از یک سرور راه دور و اعمال آن است. برای برقراری ارتباط موفق با سرور راه دور، کلاینت باید دارای گواهی امضاشده توسط مرجع صدور گواهی (CA) مورد اعتماد سرور باشد؛ روش توصیه‌شده در حال حاضر، اجرای یک مرجع صدور گواهی به عنوان بخشی از سرور puppet است (که حالت پیش‌فرض است). کلاینت متصل شده و درخواست گواهی امضاشده می‌دهد و اتصال را تا زمان دریافت گواهی ادامه خواهد داد.

به محض اینکه کلاینت گواهی امضاشده را دریافت کرد، پیکربندی خود را دریافت کرده و اعمال می‌نماید.

دستور 'puppet agent' تمام تلاش خود را به کار می‌گیرد تا تعادلی میان استفاده تعاملی و حالت دیمن ایجاد کند. اگر آن را بدون آرگومان و بدون پیکربندی اجرا کنید، به پس‌زمینه می‌رود، تلاش می‌کند گواهی امضاشده دریافت کند، و هر ۳۰ دقیقه یک بار پیکربندی خود را بازیابی و اعمال می‌نماید.

برخی گزینه‌ها به طور خاص برای استفاده تعاملی در نظر گرفته شده‌اند — به ویژه گزینه‌های 'test'، 'tags' و 'fingerprint' بسیار کاربردی هستند.

گزینه '--test' برنامه را یک بار در پیش‌زمینه همراه با گزارش‌گیری با جزئیات کامل اجرا کرده و سپس خارج می‌شود. همچنین در صورتی که نتواند کاتالوگ معتبری دریافت کند خارج خواهد شد. گزینه --test به طور پیش‌فرض شامل گزینه '--detailed-exitcodes' است و با یکی از کدهای خروج زیر خاتمه می‌یابد:

  • 0: اجرا با موفقیت بدون هیچ تغییر یا خطایی پایان یافت؛ سیستم از قبل در وضعیت مطلوب قرار داشت.
  • 1: اجرا با شکست مواجه شد، یا به دلیل در جریان بودن اجرای دیگر، تلاشی صورت نگرفت.
  • 2: اجرا با موفقیت پایان یافت و برخی منابع تغییر کردند.
  • 4: اجرا با موفقیت پایان یافت، اما برخی منابع با خطا مواجه شدند.
  • 6: اجرا با موفقیت پایان یافت و شامل هر دو مورد تغییرات و خطاها بود.

گزینه '--tags' به شما امکان می‌دهد مشخص کنید کدام بخش‌ها از یک پیکربندی را می‌خواهید اعمال کنید. عناصر Puppet با تمام نام‌های کلاس یا تعاریفی که شامل آن‌ها هستند برچسب‌گذاری می‌شوند و می‌توانید از فلگ 'tags' برای تعیین یکی از این نام‌ها استفاده کنید، که باعث می‌شود تنها عناصر پیکربندی موجود در آن کلاس یا تعریف اعمال شوند. این ویژگی هنگام آزمایش پیکربندی‌های جدید بسیار مفید است — برای نمونه، اگر به تازگی مدیریت 'ntpd' را شروع کرده‌اید، تمام عناصر جدید را درون یک کلاس 'ntpd' قرار می‌دهید و puppet را با '--tags ntpd' فراخوانی می‌کنید؛ در نتیجه در حین آزمایش به جای اعمال کل پیکربندی، تنها همان بخش کوچک اعمال خواهد شد.

گزینه '--fingerprint' یک فلگ یک‌باره است. در این حالت 'puppet agent' یک بار اجرا می‌شود و اثر انگشت گواهی فعلی (یا درخواست گواهی) را در کنسول (و در لاگ) نمایش می‌دهد. ارائه گزینه '--digest' به شما امکان می‌دهد از یک الگوریتم خلاصه‌ساز دیگر برای تولید اثر انگشت استفاده کنید. کاربرد اصلی آن این است که پیش از امضای یک درخواست گواهی روی سرور اصلی، اطمینان حاصل شود که درخواست گواهی دریافت‌شده توسط سرور با آنچه کلاینت فرستاده یکسان است (برای جلوگیری از حملات مرد میانی هنگام امضای گواهی‌ها).

گزینه '--skip_tags' فلگی است که برای فیلتر کردن منابع به کار می‌رود. اگر این گزینه تنظیم شود، تنها منابعی که با برچسب‌های مشخص‌شده برچسب‌گذاری نشده‌اند اعمال خواهند شد. مقادیر باید با کاما از یکدیگر جدا شوند.

توجه داشته باشید هر تنظیم Puppet که در فایل پیکربندی معتبر باشد، به عنوان یک آرگومان بلند خط فرمان نیز معتبر است. برای نمونه، 'server' یک تنظیم معتبر است، بنابراین می‌توانید '--server servername' را به عنوان آرگومان مشخص کنید. تنظیمات بولی پیشوند '--no-' را برای خاموش کردن یک رفتار می‌پذیرند که به جفت‌های '--setting' و '--no-setting'، مانند --daemonize و --no-daemonize، ترجمه می‌شوند.

برای مشاهده فهرست کامل تنظیمات قابل‌قبول، مستندات فایل پیکربندی را در https://puppet.com/docs/puppet/latest/configuration.html ببینید. همچنین فهرستی از تمام تنظیمات همراه با توضیحات می‌تواند با اجرای puppet agent با گزینه '--genconfig' ایجاد شود.

  • --certname: تنظیم certname (شناسه یکتا) برای کلاینت. سرور اصلی این رشته شناسه یکتا را می‌خواند که معمولاً روی نام دامنه کاملاً واجد شرایط (FQDN) گره تنظیم می‌شود تا تعیین کند کدام پیکربندی‌ها را باید به این گره ارسال کند. از این گزینه برای عیب‌یابی مشکلات راه‌اندازی یا پیاده‌سازی طرح‌های شناسایی گره خاص استفاده کنید. (این یک تنظیم Puppet است و می‌تواند در puppet.conf قرار گیرد.)
  • --daemonize: فرستادن فرآیند به پس‌زمینه. این حالت پیش‌فرض است. (این یک تنظیم Puppet است و می‌تواند در puppet.conf قرار گیرد. به پیشوند خاص 'no-' برای تنظیمات بولی در خط فرمان توجه کنید.)
  • --no-daemonize: ارسال نکردن فرآیند به پس‌زمینه. (این یک تنظیم Puppet است و می‌تواند در puppet.conf قرار گیرد.)
  • --debug: فعال‌سازی اشکال‌زدایی کامل.
  • --detailed-exitcodes: ارائه اطلاعات اضافی درباره وضعیت اجرا از طریق کدهای خروج؛ تنها در صورتی عمل می‌کند که '--test' یا '--onetime' نیز تعیین شده باشد. در صورت فعال بودن، 'puppet agent' از کدهای خروج زیر استفاده می‌کند:
0: اجرا با موفقیت و بدون هیچ تغییر یا خطایی پایان یافت؛ سیستم از قبل در وضعیت مطلوب بود.
1: اجرا با شکست مواجه شد، یا به دلیل در جریان بودن اجرای دیگر، تلاشی صورت نگرفت.
2: اجرا با موفقیت پایان یافت و برخی منابع تغییر کردند.
4: اجرا با موفقیت پایان یافت، اما برخی منابع با شکست مواجه شدند.
6: اجرا با موفقیت پایان یافت و شامل هر دو حالت تغییرات و خطاها بود.
  • --digest: تغییر الگوریتم خلاصه‌ساز اثر انگشت گواهی. مقدار پیش‌فرض SHA256 است. مقادیر معتبر به نسخه OpenSSL نصب‌شده بستگی دارد، اما احتمالاً شامل MD5، MD2، SHA1 و SHA256 خواهد بود.
  • --disable: غیرفعال کردن اعمال تغییرات روی سیستم محلی. این گزینه یک فایل قفل ایجاد می‌کند و باعث می‌شود 'puppet agent' تا زمان حذف این فایل قفل، روی سیستم کاری انجام ندهد. این ویژگی زمانی مفید است که در حال آزمایش یک پیکربندی هستید و نمی‌خواهید پیکربندی مرکزی پیش از آزمایش و ثبت نهایی، وضعیت محلی را بازنویسی کند.
گزینه disable همچنین می‌تواند یک پیام اختیاری دریافت کند که توسط 'puppet agent' در اجرای غیرفعال بعدی گزارش خواهد شد.
برنامه 'puppet agent' هنگام اجرا از همین فایل قفل استفاده می‌کند، بنابراین بیش از یک فرآیند 'puppet agent' به طور همزمان کار نخواهد کرد.
برنامه 'puppet agent' پس از اجرای این گزینه خارج می‌شود.
•
--enable: فعال‌سازی مجدد کار بر روی سیستم محلی. این کار فایل قفل را حذف می‌کند و باعث می‌شود 'puppet agent' مجدداً مدیریت سیستم محلی را آغاز کند. با این حال، برنامه به زمان‌بندی عادی خود ادامه می‌دهد، بنابراین ممکن است تا نیم ساعت بعد شروع به کار نکند.
برنامه 'puppet agent' پس از اجرای این گزینه خارج می‌شود.
  • --evaltrace: ثبت گزارش هر منبع در حین ارزیابی آن. این به شما امکان می‌دهد به صورت تعاملی دقیقاً ببینید چه کاری در حال انجام است. (این یک تنظیم Puppet است و می‌تواند در puppet.conf قرار گیرد.)
  • --fingerprint: نمایش اثر انگشت گواهی فعلی یا درخواست امضای گواهی و سپس خروج. از گزینه '--digest' برای تغییر الگوریتم خلاصه‌ساز مورد استفاده بهره ببرید.
  • --help: چاپ این پیام راهنما.
  • --job-id: پیوست کردن شناسه کار (job id) مشخص‌شده به درخواست کاتالوگ و گزارش مورد استفاده برای این اجرای agent. این گزینه تنها زمانی کار می‌کند که '--onetime' استفاده شده باشد. هنگام استفاده از Puppet Enterprise این فلگ نباید استفاده شود زیرا هماهنگ‌کننده شناسه کار را برای شما تنظیم می‌کند و این مقدار باید یکتا باشد.
  • --logdest: مقصد ارسال پیام‌های گزارش (لاگ). از میان 'syslog' (سرویس لاگ سیستم در POSIX)، 'eventlog' (ثبت وقایع ویندوز)، 'console' یا مسیر یک فایل لاگ انتخاب کنید. اگر اشکال‌زدایی یا نمایش با جزئیات فعال باشد، مقدار پیش‌فرض 'console' است. در غیر این صورت، در سیستم‌های POSIX پیش‌فرض 'syslog' و در ویندوز 'eventlog' خواهد بود. مقاصد چندگانه را می‌توان با استفاده از فهرستی جداشده با کاما تعیین کرد (مانند: /path/file1,console,/path/file2).
مسیری که به '.json' ختم شود خروجی ساختاریافته در قالب JSON دریافت خواهد کرد. به دلیل ماهیت الحاقی لاگ‌گیری، فایل لاگ به طور خودکار کاراکتر پایانی ']' را نخواهد داشت؛ برای تبدیل به JSON معتبر باید به صورت دستی اضافه شود.
مسیری که به '.jsonl' ختم شود خروجی ساختاریافته در قالب JSON Lines دریافت خواهد کرد.
  • --masterport: پورتی که برای ارتباط با Puppet Server استفاده می‌شود. (این یک تنظیم Puppet است و می‌تواند در puppet.conf قرار گیرد. به نفع تنظیم 'serverport' منسوخ شده است.)
  • --noop: استفاده از حالت 'noop' که در آن دیمن در حالت بدون عملیات یا شبیه‌سازی اجرا می‌شود. این حالت برای مشاهده تغییراتی که Puppet بدون اعمال واقعی آن‌ها ایجاد خواهد کرد مفید است. (این یک تنظیم Puppet است و می‌تواند در puppet.conf قرار گیرد.)
  • --onetime: اجرای پیکربندی برای یک بار. اجرای یک باره Puppet (که به طور معمول در قالب دیمن اجرا می‌شود). هنگامی که همراه با گزینه --no-daemonize استفاده شود، برای اجرای تعاملی puppet agent کاربرد دارد. (این یک تنظیم Puppet است و می‌تواند در puppet.conf قرار گیرد.)
  • --serverport: پورتی که برای ارتباط با Puppet Server استفاده می‌شود. (این یک تنظیم Puppet است و می‌تواند در puppet.conf قرار گیرد.)
  • --sourceaddress: تنظیم آدرس IP مبدأ برای تراکنش‌ها. مقدار پیش‌فرض انتخاب خودکار است. (این یک تنظیم Puppet است و می‌تواند در puppet.conf قرار گیرد.)
  • --test: فعال‌سازی متداول‌ترین گزینه‌های مورد استفاده برای آزمایش. این گزینه‌ها شامل 'onetime'، 'verbose'، 'no-daemonize'، 'no-usecacheonfailure'، 'detailed-exitcodes'، 'no-splay' و 'show_diff' هستند.
  • --trace: چاپ ردپای فراخوانی‌ها (stack trace) در صورت بروز برخی خطاها. (این یک تنظیم Puppet است و می‌تواند در puppet.conf قرار گیرد.)
  • --verbose: فعال‌سازی گزارش‌دهی با جزئیات کامل.
  • --version: چاپ شماره نسخه puppet و خروج.
  • --waitforcert: این گزینه تنها برای دیمن‌هایی اهمیت دارد که هنوز گواهی دریافت نکرده‌اند و به طور پیش‌فرض با مقدار 120 (ثانیه) فعال است. این امر باعث می‌شود 'puppet agent' هر ۲ دقیقه یک بار به سرور متصل شده و درخواست امضای گواهی کند. این برای راه‌اندازی اولیه کلاینت puppet مفید است. می‌توانید با تعیین مقدار 0، انتظار برای گواهی‌ها را غیرفعال کنید. (این یک تنظیم Puppet است و می‌تواند در puppet.conf قرار گیرد.)
  • --write_catalog_summary: پس از کامپایل کاتالوگ، فهرست منابع و فهرست کلاس‌ها را در دایرکتوری وضعیت گره در فایل‌هایی با نام classes.txt و resources.txt ذخیره می‌کند. (این یک تنظیم Puppet است و می‌تواند در puppet.conf قرار گیرد.)

$ puppet agent --server puppet.domain.com

راه‌اندازی مجدد دیمن puppet agent.
خاموش کردن و توقف دیمن puppet agent.
دریافت و اعمال فوری پیکربندی‌ها از سرور puppet master.
بستن توصیف‌کننده‌های فایل برای فایل‌های لاگ و بازگشایی مجدد آن‌ها. برای استفاده به همراه logrotate.

January 2025 Vox Pupuli