UPSDRVCTL(8) راهنمای NUT UPSDRVCTL(8)

upsdrvctl - کنترل‌کننده درایور Network UPS Tools

upsdrvctl -h

upsdrvctl [گزینه‌ها] {start | stop | shutdown | status} [ups]

upsdrvctl [گزینه‌ها] {list | -l} [ups]

upsdrvctl [گزینه‌ها] -c COMMAND [ups]

دستور upsdrvctl یک رابط یکپارچه برای کنترل درایورهای UPS شما فراهم می‌کند. هر زمان که امکان‌پذیر است، باید به‌جای فراخوانی مستقیم درایورها از دستور upsdrvctl استفاده کنید.

هنگامی که به درستی استفاده شود، upsdrvctl به شما امکان می‌دهد اسکریپت‌های راه‌اندازی یکسانی را در چندین سیستم با پیکربندی‌های مختلف UPS حفظ کنید.


هشدار

برای سیستم‌های عاملی با چارچوب‌های مدیریت سرویس، مانند Solaris/illumos SMF یا Linux systemd، ممکن است upsdrvsvcctl(8) انتخاب بهتری باشد.

در واقع، نمونه‌های سرویسی که توسط nut-driver-enumerator(8) بر اساس محتویات فایل ups.conf(5) شما آماده شده و به‌طور خودکار توسط چارچوب مربوطه نگهداری می‌شوند، می‌توانند با اجرای دستی درایورها تداخل داشته باشند. در این حالت، upsdrvctl در ساخت‌هایی از NUT که این قابلیت را دارند هشداری صادر می‌کند (می‌توان با صادر کردن متغیر محیطی NUT_QUIET_INIT_NDE_WARNING با هر مقداری، این هشدار را بی‌صدا کرد).

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

-h

نمایش متن راهنما.

-r directory

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

این مقدار را می‌توان در ups.conf(5) با دستورالعمل chroot در بخش سراسری تنظیم کرد.

-t

فعال‌سازی حالت آزمایشی. این کار حالت اشکال‌زدایی را نیز فعال می‌کند. حالت آزمایشی باعث می‌شود upsdrvctl کارهایی را که اجرا خواهد کرد بدون انجام واقعی آن‌ها نمایش دهد. از این گزینه برای آزمایش پیکربندی خود بدون انجام هیچ کاری روی درایورهای UPS استفاده کنید.

این گزینه می‌تواند هنگام تعریف دستورالعمل sdorder در بخش مربوط به دستگاه در ups.conf(5) مفید باشد.

-u username

در صورت راه‌اندازی یک درایور، این مقدار آن را هدایت می‌کند تا شناسه کاربری (setuid(2)) خود را به کاربر مرتبط با username تغییر دهد.

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

این مقدار را می‌توان در ups.conf(5) با دستورالعمل user در بخش سراسری تنظیم کرد.

-D

افزایش سطح اشکال‌زدایی (debug level). برای جزئیات بیشتر، چندین بار از این گزینه استفاده کنید. از طرف دیگر، این مقدار را می‌توان از طریق debug_min در بخش سراسری ups.conf(5) تنظیم کرد. توجه داشته باشید که تنظیمات سراسری هم برای ابزار و هم برای درایور راه‌اندازی‌شده اعمال می‌شود؛ اما خط دیگری در بخش اختصاصی یک درایور می‌تواند آن را با مقداری بزرگ‌تر یا کوچک‌تر بازنویسی کند (از جمله debug_min=0 برای غیرفعال کردن ردگیری درایور به صورت پیش‌فرض).

توجه داشته باشید که این کار مانع از خروج ابزار upsdrvctl پس از انجام کارش نمی‌شود (با این حال گزینه صریح -F این کار را می‌کند).

همچنین توجه داشته باشید که این گزینه به تنهایی پرگویی اشکال‌زدایی ابزار را تغییر می‌دهد، اما بر درایورهایی که راه‌اندازی می‌کند تأثیری ندارد. برای این منظور به گزینه اضافی -d مراجعه کنید.

-d

ارسال سطح اشکال‌زدایی انتخاب‌شده از upsdrvctl به درایورهای راه‌اندازی‌شده.

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

-F

درایور بدون توجه به تنظیمات اشکال‌زدایی، در پیش‌زمینه اجرا خواهد شد (از فرایند upsdrvctl جدا یا fork نمی‌شود). این گزینه همچنین خود برنامه ابزار را در پیش‌زمینه نگه می‌دارد در حالی که دیمن‌های درایور به عنوان فرزندان آن اجرا می‌شوند (در صورت راه‌اندازی تنها یک درایور، حتی fork نیز نمی‌کند).

همچنین منتظر تکمیل مقداردهی اولیه درایورها نمی‌ماند، بنابراین upsdrvctl درباره چنین موقعیت‌هایی هشدار خواهد داد.

دو بار مشخص کنید (-FF یا -F -F) تا فایل PID درایور حتی در این حالت نیز ذخیره شود (به طور پیش‌فرض هنگام ماندن در پیش‌زمینه ذخیره نمی‌شود).

-B

درایورها بدون توجه به تنظیمات اشکال‌زدایی که توسط -D تنظیم شده و توسط گزینه‌های -d منتقل شده‌اند، در پس‌زمینه اجرا خواهند شد.

-l

نام مستعار برای دستور list.

ابزار upsdrvctl از سه دستور فعال پشتیبانی می‌کند — start، stop و shutdown. همچنین از ارسال درخواست‌ها به درایورهای در حال اجرا با استفاده از نحو -c COMMAND مشابه برخی دیمن‌های دیگر پشتیبانی می‌کند. چند دستور کمکی نیز در دسترس هستند — list و status.

همه آن‌ها می‌توانند یک آرگومان اختیاری دریافت کنند که نام یک UPS از ups.conf(5) است. بدون این آرگومان، آن‌ها بر روی هر UPS که در حال حاضر پیکربندی شده است عمل می‌کنند.


نکته

ابزار upsdrvctl نمی‌تواند دستگاه‌هایی را که در ups.conf فهرست نشده‌اند مدیریت کند (مانند درایورهای آزمایشی که با گزینه -s TMP شروع شده‌اند).

start

راه‌اندازی درایور(های) UPS. در صورت عدم موفقیت در راه‌اندازی در بازه زمانی maxstartdelay، تلاش‌های بعدی ممکن است با استفاده از مقادیر maxretry و retrydelay انجام شوند. برعکس، گزینه سراسری nowait را می‌توان به ویژه برای سرعت بخشیدن به راه‌اندازی موازی بسیاری از درایورها استفاده کرد.

درباره این گزینه‌ها به ups.conf(5) مراجعه کنید. مقادیر پیش‌فرض توکار عبارتند از: maxstartdelay=75 (ثانیه)، maxretry=1 (به معنای یک تلاش برای شروع)، retrydelay=5 (ثانیه).

stop

متوقف کردن درایور(های) UPS. این دستور فرمانی به UPS ارسال نمی‌کند.

shutdown

دستور به درایور(های) UPS برای اجرای توالی خاموش‌سازی آن‌ها. این فرض می‌کند که درایور دیگر در حال اجرا نیست و یک نمونه تازه را از طریق drivername -k شروع می‌کند. این دستور به عنوان آخرین مرحله در خاموش کردن سیستم، پس از اینکه سیستم‌های فایل دیگر به صورت rw (خواندنی-نوشتنی) سوار (mount) نیستند، در نظر گرفته شده است. درایورها بر اساس مقدار sdorder آن‌ها متوقف می‌شوند — به ups.conf(5) مراجعه کنید.

هشدار

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


نکته

برای استفاده از پارامتر nowait به ups.conf(5) مراجعه کنید. این مقدار را می‌توان با متغیر محیطی NUT_IGNORE_NOWAIT لغو کرد (به عنوان مثال برای دور زدن برخی مشکلات با systemd در غیر این صورت استفاده می‌شود).

list

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

نکته

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


نکته

سطر بنر نام ابزار و نسخه NUT نیز قبل از هر پردازش دیگری در stdout چاپ می‌شود. این را می‌توان با متغیر محیطی NUT_QUIET_INIT_BANNER (صادرشده توسط فراخواننده و خالی یا "true") سرکوب کرد:

:; NUT_QUIET_INIT_BANNER=true upsdrvctl list
dummy
UPS1
UPS2

status

مشابه list، اما اطلاعات بیشتری را گزارش می‌دهد — همچنین نام درایور، PID در صورت در حال اجرا بودن، و نتیجه بررسی سیگنال برای اطمینان از پاسخگو بودن آن. سرکوب با NUT_QUIET_INIT_BANNER می‌تواند برای تجزیه در اسکریپت‌ها مفید باشد. اگر چیزی برای چاپ وجود داشته باشد (حداقل یک دستگاه شناخته شده باشد)، سطر اول گزارش وضعیت، سرصفحه با نام ستون‌ها خواهد بود: 
:; NUT_QUIET_INIT_BANNER=true upsdrvctl status
UPSNAME              UPSDRV  RUNNING PF_PID  S_RESPONSIVE    S_PID   S_STATUS
dummy             dummy-ups  N/A     -3      NOT_RESPONSIVE  N/A
eco650           usbhid-ups  RUNNING 3559207 RESPONSIVE      3559207 "OL"
UPS2              dummy-ups  RUNNING 31455   RESPONSIVE      31455   "OL BOOST"

مقادیر با کلید TAB جدا شده‌اند، اما UPSNAME و UPSDRV ممکن است به ترتیب با فاصله‌ها در سمت راست و چپ پر شوند. هر مقدار رشته‌ای پیچیده در نقل‌قول دوتایی محصور می‌شود.

فیلدهای گزارش‌شده (PF_* = بر اساس فایل PID، در صورت وجود؛ S_* = از طریق پروتکل سوکت):

UPSNAME

نام پیکربندی بخش درایور

UPSDRV

نام برنامه درایور مطابق با ups.conf

RUNNING

مقدار RUNNING اگر PF_PID یا S_PID معتبر باشد، STOPPED اگر حداقل یک مقدار PID تجزیه شده باشد اما هیچ برنامه‌ای با نام صحیح در حال اجرا یافت نشود؛ N/A اگر فایل PID یا پاسخ سوکت وجود نداشته باشد یا تجزیه با شکست مواجه شود. ابتدا فایل PID بررسی می‌شود، اما ممکن است به دلیل پارامترهای خط فرمان دیمن‌ها، یا به دلیل پلتفرم (WIN32) وجود نداشته باشد. اگر هیچ مقدار PID از این طریق یافت و تأیید نشد، بررسی PID گزارش‌شده از طریق پروتکل را به عنوان جایگزین انجام می‌دهیم (در صورت موجود بودن و متفاوت بودن).

PF_PID

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

S_RESPONSIVE

مقدار RESPONSIVE اگر PING/PONG در طول راه‌اندازی نشست پروتکل سوکت با موفقیت انجام شود؛ در غیر این صورت NOT_RESPONSIVE

S_PID

شناسه PID درایور بر اساس پرس‌وجوی فعال GETPID، یا N/A در صورت شکست پرس‌وجو

S_STATUS

مقدار داخل نقل‌قول متغیر ups.status

این حالت درایورهایی را که در ups.conf نیستند (مانند درایورهایی که به صورت دستی برای آزمایش با گزینه‌های متعدد خط فرمان -x راه‌اندازی شده‌اند) شناسایی نمی‌کند.

-c command

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

dump

به درایور(ها) می‌گوید اطلاعات وضعیت شناخته‌شده فعلی را در stdout خود (در صورت متصل بودن به هر کجا) تخلیه کنند

reload

خواندن مجدد فایل‌های پیکربندی، با نادیده گرفتن تنظیمات تغییر‌یافته‌ای که نمی‌توانند "در حین اجرا" (on the fly) اعمال شوند

reload-or-error

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

reload-or-exit

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

exit

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

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

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

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

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

اگر upsdrvctl هنگام انجام عملیات درخواستی با خطایی مواجه شود، یک کد خروج غیر صفر برمی‌گرداند. این امر همچنین در صورتی رخ می‌دهد که ورود یک درایور به پس‌زمینه بیش از دوره زمانی maxstartdelay طول بکشد.

upsdrvsvcctl(8), nut-driver-enumerator(8), nutupsdrv(8), upsd(8), ups.conf(5)

صفحه اصلی NUT (Network UPS Tools): https://www.networkupstools.org/historic/v2.8.5

06/21/2026 Network UPS Tools 2.8.5