NUTUPSDRV(8)

NUT Manual

NUTUPSDRV(8)

نام (NAME)

nutupsdrv - راهنمای عمومی برای درایورهای یکپارچه NUT

خلاصه دستور (SYNOPSIS)

nutupsdrv -h

nutupsdrv [گزینه‌ها]

توضیحات (DESCRIPTION)

دستور nutupsdrv در واقع یک درایور مستقل نیست. این یک صفحه راهنمای تجمیعی برای کدهای مشترکی است که هسته اصلی بسیاری از درایورها در بسته ابزارهای یوپی‌اس شبکه (Network UPS Tools - NUT) را تشکیل می‌دهند.

برای کسب اطلاعات درباره درایورهای خاص، به صفحات راهنمای اختصاصی هر یک مراجعه کنید.

درایورهای UPS یک کانال ارتباطی میان سخت‌افزار فیزیکی UPS و سرور upsd(8) فراهم می‌کنند. درایور وظیفه ترجمه پروتکل بومی دستگاه UPS به قالب مشترک مورد استفاده در سایر بخش‌های این بسته را بر عهده دارد.

هسته درایور دارای سه حالت کاری است که با گزینه‌های خط فرمان تعیین می‌شوند. در حالت عادی، درایور به صورت دوره‌ای و مطابق با پارامتر pollinterval در ups.conf(5)، وضعیت و پارامترهای UPS را استعلام (poll) می‌کند. نتایج این استعلام به upsd تحویل داده می‌شود. همچنین درایور در صورت پشتیبانی، مقداردهی متغیرها و اجرای دستورات فوری (instant commands) را مدیریت می‌کند.

در حالت دوم، با استفاده از گزینه -k، درایور می‌تواند به UPS دستور دهد بار مصرفی (تغذیه دستگاه‌های متصل) را احتمالاً پس از مقداری تاخیر قطع کند. این حالت کاری برای مواقعی در نظر گرفته شده است که مشخص است شارژ باتری UPS رو به اتمام است و سیستم‌های متصل باید خاموش شوند تا پس از بازگشت برق، راه‌اندازی مجدد به درستی انجام گیرد.

در حالت سوم، با استفاده از گزینه -d، درایور پس از چند چرخه به‌روزرسانی خارج می‌شود و درخت داده‌ها را (در قالبی مشابه با upsc(8)) در خروجی استاندارد (stdout) می‌ریزد. این ویژگی می‌تواند به عنوان مکمل nut-scanner(8) برای شناسایی دستگاه‌ها همراه با داده‌های دقیق و عمیق مفید باشد.

نکته

احتمالاً مایل نخواهید بود که از هیچ‌یک از این گزینه‌ها مستقیماً استفاده کنید. برای کنترل درایورهای خود باید از upsdrvctl(8) (یا upsdrvsvcctl(8) در سیستم‌های دارای چارچوب مدیریت سرویس مانند systemd یا SMF) و برای پیکربندی آن‌ها از ups.conf(5) استفاده نمایید. ادامه این راهنما به توضیح گزینه‌ها و پارامترهایی می‌پردازد که معمولاً توسط کاربران عادی مورد نیاز نیستند.

گزینه‌ها (OPTIONS)

-h

نمایش پیام راهنما بدون انجام هیچ کار دیگری. این گزینه همچنین مقادیر ممکن برای -x در آن درایور و سایر متن‌های راهنمایی را که نویسنده درایور ارائه کرده است فهرست می‌کند.

-a id

پیکربندی خودکار این درایور با استفاده از بخش id در ups.conf(5). این آرگومان هنگام فراخوانی مستقیم درایور اجباری است.

-s id

پیکربندی این درایور تنها با آرگومان‌های خط فرمان به جای خواندن ups.conf(5). این گزینه در صورت نیاز به اجرای درایوری که در فایل پیکربندی درایور وجود ندارد، به جای گزینه -a استفاده می‌شود. در عوض، پیکربندی درایور باید با گزینه‌های -x مستقیماً در خط فرمان تنظیم شود. از آنجا که این نمونه درایور را نمی‌توان با upsdrvctl(8) یا upsdrvsvcctl(8) کنترل کرد، این گزینه فقط باید برای نیازهای خاص استفاده شود.

-D

افزایش سطح اشکال‌زدایی (دیباگ). برای مشاهده جزئیات بیشتر چندین بار از این گزینه استفاده کنید. اجرای درایور در حالت اشکال‌زدایی (به طور پیش‌فرض) از رفتن آن به پس‌زمینه پس از راه‌اندازی جلوگیری می‌کند. درایور ثبت اطلاعات در کنسول را تا زمان دریافت سیگنال SIGINT (معمولاً Ctrl-C) یا SIGTERM ادامه خواهد داد.

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

-d update_count

تخلیه درخت داده‌ها (در قالبی مشابه با upsc(8)) در stdout پس از اجرای حلقه به‌روزرسانی درایور به تعداد مشخص‌شده در update_count و سپس خروج.

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

-q

افزایش آستانه سطح ثبت وقایع (لاگ). برای ثبت جزئیات بیشتر چندین بار از این گزینه استفاده کنید.

نکته مربوط به اشکال‌زدایی در بالا در اینجا نیز صدق می‌کند.

-c command

ارسال command به عنوان سیگنال به فرآیند پس‌زمینه. دستورات معتبر عبارتند از:

reload

بازخوانی فایل‌های پیکربندی، با نادیده گرفتن تنظیمات تغییریافته‌ای که نمی‌توانند به صورت آنی اعمال شوند.

reload-or-error

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

reload-or-exit

بازخوانی فایل‌های پیکربندی، و خروج از فرآیند درایور قدیمی در صورت مواجهه با تنظیمات تغییریافته‌ای که نمی‌توانند به صورت آنی اعمال شوند (تا فراخواننده‌ای مانند systemd بتواند نسخه دیگری از درایور را راه‌اندازی کند).

exit

دستور به نمونه در حال اجرای درایور برای خروج کامل (تا یک فراخواننده خارجی مانند نمونه جدید درایور، یا چارچوب‌های systemd یا SMF نسخه دیگری را راه‌اندازی کنند).

در نسخه‌های جدید NUT v2.8.x، چنین دستوراتی را می‌توان با استفاده از سوکت یونیکس برای تعامل درایور و سرور ارسال کرد. به عنوان روش پشتیبان، همانند نسخه‌های قدیمی‌تر، سیگنال‌ها را می‌توان به PID یک نمونه قدیمی درایور (در صورت امکان) ارسال نمود.

-P pid

ارسال سیگنال دستور فوق با استفاده از شماره PID مشخص‌شده، به جای مراجعه به فایل PID. این کار می‌تواند در تعریف واحدهای سرویسی که هر درایور NUT را به عنوان یک فرآیند پیش‌زمینه راه‌اندازی می‌کنند تا فایل PID نسازد، کمک کند. همچنین گزینه -FF را به عنوان یک راهکار جایگزین بررسی کنید.

-F

اجبار به اجرای درایور به عنوان یک فرآیند پیش‌زمینه، صرف‌نظر از تنظیمات اشکال‌زدایی یا تخلیه داده‌ها. مشخص کردن دو بار (-FF یا -F -F) موجب ذخیره فایل PID حتی در این حالت می‌شود.

-B

اجبار به اجرای درایور به عنوان یک فرآیند پس‌زمینه، صرف‌نظر از تنظیمات اشکال‌زدایی یا تخلیه داده‌ها.

-i interval

تنظیم بازه زمانی استعلام (poll interval) برای دستگاه. مقدار پیش‌فرض ۲ (به ثانیه) است.

-V

تنها چاپ اطلاعات نسخه و سپس خروج.

-L

چاپ فهرستی قابل تجزیه از متغیرهای درایور. عمدتاً برای برنامه‌های ویزارد پیکربندی مفید است.

-k

(قطع برق - «Kill power») حالت خاموش‌سازی اجباری. در صورت امکان، UPS برق بار متصل را قطع خواهد کرد.

تا جای ممکن باید به جای فراخوانی مستقیم این گزینه، از upsdrvctl shutdown استفاده کنید. توجه داشته باشید که شرایط محدود سیستم‌عامل برای خاموش‌سازی معمولاً مانع استفاده از upsdrvsvcctl shutdown می‌شود.

-r directory

درایور در طول فرآیند مقداردهی اولیه، با دستور chroot(2) به directory تغییر ریشه می‌دهد. این قابلیت هنگام ایمن‌سازی سیستم‌ها می‌تواند مفید باشد.

علاوه بر مسیر وضعیت، بسیاری از سیستم‌ها برای کارکرد این قابلیت نیاز دارند که /dev/null درون directory وجود داشته باشد. پورت‌های سریال پیش از فراخوانی chroot باز می‌شوند، بنابراین نیازی به ایجاد آن‌ها در محیط ایزوله (jail) ندارید. در واقع، ایجاد نکردن آن‌ها تا حدی ایمن‌تر است (اما اتصال مجدد به دستگاه‌ها ممکن است دیگر امکان‌پذیر نباشد و به راه‌اندازی مجدد کامل درایور نیاز داشته باشد).

-u username

بازنویسی نام کاربری بدون امتیازی که درایور ممکن است پس از راه‌اندازی استفاده کند. اگر به عنوان root راه‌اندازی شود، پس از باز کردن فایل‌های پیکربندی (و فراخوانی اختیاری chroot(2)، همان‌طور که در گزینه قبل توضیح داده شد)، درایور نام کاربری username را در پایگاه داده passwd جستجو می‌کند، سپس به هویت‌های کاربری و گروهی مرتبط با username تغییر وضعیت می‌دهد. (اگر با UID یا UID موثر غیرصفر راه‌اندازی شود، درایور این گزینه را نادیده می‌گیرد.)

هنگام کامپایل NUT از سورس، نام کاربری پیش‌فرض معمولاً nobody است، و این ممکن است هنگام باز کردن نود دستگاه UPS توسط درایور باعث خطاهای دسترسی شود. می‌توانید از این گزینه برای بازنویسی موقت مقادیر پیش‌فرض استفاده کنید. برای اهداف آزمایشی، می‌توانید این گزینه را روی root تنظیم کنید تا خطاهای دسترسی دور زده شوند، به ویژه در درایورهای مبتنی بر USB. با این حال، بعداً باید این گزینه را حذف کنید تا از تداخل مجوزها میان درایور و نسخه بدون امتیاز upsd(8) جلوگیری شود.

-g groupname

بازنویسی نام گروه بدون امتیازی که درایور ممکن است پس از راه‌اندازی برای تنظیم مجوزهای سوکت سیستم‌فایل استفاده کند تا upsd همچنان بتواند به آن دسترسی داشته باشد اگر کاربر زمان اجرای (user) درایور در حالت عادی مانع این دسترسی شود.

-x var=val

تعریف متغیری به نام var با مقدار val در درایور. این مقادیر از درایوری به درایور دیگر متفاوت است — برای اطلاعات بیشتر به صفحات راهنمای اختصاصی آن‌ها مراجعه کنید.

این مانند تنظیم var=val در ups.conf(5) است، اما -x در خط فرمان هرگونه تنظیماتی را از آن فایل بازنویسی می‌کند.

توجه داشته باشید که برای مقادیر پشتیبان متغیرهای NUT که توسط یک دستگاه خاص و/یا درایور NUT آن ضعیف پشتیبانی می‌شوند، می‌توانید default.var.name=val را برای تنظیم یک مقدار پیش‌فرض مشخص کنید (که ممکن است در زمان اجرا با داده دریافتی از دستگاه جایگزین شود)، یا override.var.name=val را برای تعیین مقدار ثابت و نادیده گرفتن مقادیر دریافتی از دستگاه حتی در صورت ارسال آن‌ها مشخص نمایید. برای مثال، این قابلیت اغلب با override.battery.voltage.nominal استفاده می‌شود زمانی که دستگاه یک تک‌سلول در محدوده ۲ ولت را گزارش می‌دهد و شما به یک بسته باتری استاندارد در محدوده ۱۲ ولت برای باتری سربی-اسیدی (PbAc) نیاز دارید.

عیب‌یابی (DIAGNOSTICS)

اطلاعات مربوط به فرآیند راه‌اندازی در stdout و/یا stderr چاپ می‌شود. پیام‌های تکمیلی پس از آن نقطه تنها در syslog در دسترس هستند، مگر اینکه درایور در پیش‌زمینه باقی بماند (مثلاً به دلیل افزایش سطح اشکال‌زدایی).

پس از راه‌اندازی upsd(8)، کلاینت‌های UPS مانند upsc(8) می‌توانند برای استعلام وضعیت یک UPS استفاده شوند.

کنترل برنامه (PROGRAM CONTROL)

همیشه باید از upsdrvctl(8) (یا upsdrvsvcctl(8) در سیستم‌های دارای چارچوب مدیریت سرویس مانند systemd یا SMF) برای کنترل درایورها استفاده کنید. اگرچه درایورها را می‌توان برای اهداف آزمایشی به صورت دستی راه‌اندازی کرد، اما این کار برای استفاده در محیط عملیاتی توصیه نمی‌شود.

فایل‌ها (FILES)

ups.conf

فایل پیکربندی الزامی. این فایل شامل تمام جزئیات مربوط به اینکه کدام درایورها راه‌اندازی شوند و سخت‌افزار به کجا متصل است می‌باشد.

متغیرهای محیطی (ENVIRONMENT VARIABLES)

متغیر NUT_DEBUG_LEVEL در صورتی که هیچ آرگومان -D در خط فرمان ارائه نشده باشد، سطح پیش‌فرض اشکال‌زدایی را تنظیم می‌کند، اما درخواستی برای اجرای دیمون در حالت پیش‌زمینه ارائه نمی‌دهد.

متغیر NUT_CONFPATH نام مسیر دایرکتوری حاوی ups.conf و سایر فایل‌های پیکربندی است. اگر این متغیر تنظیم نشود، درایورها از یک مقدار پیش‌فرض داخلی استفاده می‌کنند که اغلب /usr/local/ups/etc است.

متغیر NUT_STATEPATH نام مسیر دایرکتوری است که در آن upsd و درایورها اطلاعات وضعیت مشترک را نگهداری می‌کنند. اگر این متغیر تنظیم نشود، upsd و درایورها از یک مقدار پیش‌فرض داخلی استفاده می‌کنند که اغلب /var/state/ups است. دستور STATEPATH در upsd.conf(5) این متغیر را بازنویسی می‌کند.

متغیر NUT_ALTPIDPATH نام مسیر دایرکتوری است که در آن upsd و درایورها فایل‌های .pid را ذخیره می‌کنند. اگر این متغیر تنظیم نشود، upsd و درایورها در صورت تنظیم بودن از NUT_STATEPATH، یا در صورت تنظیم بودن از ALTPIDPATH، و در غیر این صورت از مقدار پیش‌فرض داخلی STATEPATH استفاده می‌کنند.

متغیر NUT_QUIET_INIT_UPSNOTIFY=true می‌تواند برای جلوگیری از ارسال اعلان‌ها توسط دیمون‌هایی که قادرند چارچوب‌های مدیریت سرویس (مانند systemd) را از سپری شدن نقاط عطف چرخه حیات خود آگاه سازند، استفاده شود (از جمله اعلان‌های عدم پشتیبانی سیستم از این ویژگی‌های نوین، یک‌بار در هر اجرا).

متغیر NUT_QUIET_INIT_BANNER=true می‌تواند برای جلوگیری از نمایش بنر نام و نسخه ابزار NUT استفاده شود. به دلیل تاثیر منفی در عیب‌یابی برای سرویس‌ها توصیه نمی‌شود، اما ممکن است در پروفایل‌های شل یا اسکریپت‌هایی که خروجی ابزار NUT را پردازش می‌کنند مفید باشد.