نام (NAME)

upslog - ثبت‌کننده وضعیت یوپی‌اس (UPS)

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

upslog -h

upslog [گزینه‌ها]

توضیحات (DESCRIPTION)

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

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

گزینه‌ها (OPTIONS)

-f format

نظارت بر UPS با استفاده از این رشته قالب‌بندی. اطمینان حاصل کنید که format را در گیومه قرار می‌دهید تا پوسته شما آن را تکه‌تکه نکند. کاراکترهای اسکیپ (escape) معتبر در این رشته عبارتند از:

%%

درج یک نویسه "%" تنها

%t

درج یک نویسه TAB منفرد (مانند printf("\t"))

%TIME format%

درج زمان با قالب‌بندی strftime

%ETIME%

درج تعداد ثانیه‌ها از آغاز "Epoch"، مطابق با time_t. این مقدار اکنون یک عدد ۱۰ رقمی است.

%HOST%

درج نام میزبان محلی

%UPSHOST%

درج میزبان UPS تحت نظارت (بخش <system> در مشخصات لاگین شما، برای مثال ups[@host[:port]])

%PID%

درج PID خود upslog

%VAR varname%

درج مقدار متغیر varname (برای جزئیات بیشتر به فصل "Variables" در مستندات توسعه‌دهندگان NUT به صورت آنلاین یا در فایل docs/nut-names.txt در سورس‌های نسخه نصب‌شده NUT مراجعه کنید)

رشته قالب‌بندی پیش‌فرض به شرح زیر است:

%TIME @Y@m@d @H@M@S% %VAR battery.charge% %VAR input.voltage%
%VAR ups.load% [%VAR ups.status%] %VAR ups.temperature%
%VAR input.frequency%

-N

افزودن پیشوند %UPSHOST%%t قبل از رشته قالب‌بندی (چه پیش‌فرض و چه سفارشی). هنگام ثبت گزارش چند سیستم در یک مقصد مشترک کاربرد دارد.

نکته
این گزینه در حال حاضر بررسی نمی‌کند که آیا از قبل %UPSHOST% در رشته قالب‌بندی وجود دارد یا خیر (برای مثال به طور صریح مشخص شده باشد).

-i interval

مدت زمان انتظار بر حسب ثانیه میان هر بار نظرسنجی (poll). مقدار پیش‌فرض 30 ثانیه است.

اگر به زمان‌بندی دقیق‌تری نیاز دارید، نوشتن ثبت‌کننده اختصاصی خود را با استفاده از کتابخانه upsclient(3) مدنظر قرار دهید.

-d count

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

-l logfile

ذخیره نتایج در این فایل لاگ.

می‌توانید از - برای stdout استفاده کنید، اما upslog به صورت پیش‌فرض در پیش‌زمینه باقی خواهد ماند.

نیازمند آن است که گزینه -s <system> نیز برای ثبت گزارش تک‌سیستمی استفاده شده باشد.

می‌تواند به همراه -m <tuple> استفاده شود و به فهرست اضافه خواهد شد.

-D

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

-F

برنامه upslog صرف‌نظر از مقصد لاگ، در پیش‌زمینه اجرا خواهد شد.

-B

برنامه upslog صرف‌نظر از مقصد لاگ یا اشکال‌زدایی، در پس‌زمینه اجرا خواهد شد.

-s ups

نظارت بر این UPS. قالب این گزینه به صورت upsname[@hostname[:port]] است. نام میزبان پیش‌فرض "localhost" است.

مقدار upsname می‌تواند علامت ستاره * باشد تا از UPSهایی که در حال حاضر توسط hostname سرویس‌دهی می‌شوند استعلام گرفته و هر یک از آن‌ها را (در همان مقصد لاگ) نظارت کند.

نیازمند آن است که گزینه -l <logfile> نیز برای ثبت گزارش تک‌سیستمی استفاده شده باشد.

می‌تواند به همراه -m <tuple> استفاده شود و به فهرست اضافه خواهد شد.

-m tuple

نظارت بر چندین UPS (با ارائه چندین مورد از این گزینه).

قالب این گزینه یک چندتایی (tuple) از مشخصات سیستم UPS و فایل لاگ است که با کاما جدا شده‌اند. برای مثال:

upsname@hostname:9999,/var/log/nut/cps.log

مقدار upsname می‌تواند علامت ستاره * باشد تا از UPSهایی که در حال حاضر توسط hostname سرویس‌دهی می‌شوند استعلام گرفته و بر هر یک از آن‌ها (در همان مقصد لاگ) نظارت کند.

چندتایی‌ها می‌توانند - را به عنوان logfile مشخص کنند تا پیام‌ها در stdout منتشر شوند (برای مثال جهت جمع‌آوری توسط ژورنال سیستم برای سرویس‌ها).

استفاده از stdout از طریق مشخصات لاگ مبتنی بر tuple همچنین به این معنی است که upslog به طور پیش‌فرض در پیش‌زمینه باقی خواهد ماند.

-u username

اگر به عنوان root اجرا شود، upslog به دلایل امنیتی با استفاده از setuid(2) به شناسه کاربری مرتبط با username تغییر هویت می‌دهد.

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

گزینه‌های عمومی (COMMON OPTIONS)

-h

نمایش پیام راهنمای خط فرمان.

-V

نمایش بنر نسخه NUT. جزئیات بیشتر در صورتی در دسترس خواهد بود که متغیر محیطی export NUT_DEBUG_LEVEL=1 یا سطوح اشکال‌زدایی بالاتری را تنظیم کرده باشید.

-W secs

تنظیم مهلت زمانی برای اتصالات اولیه شبکه (به طور پیش‌فرض به صورت نامحدود غیرمسدودکننده هستند، یا تا زمانی که سیستم تلاش را متوقف کند). متغیر محیطی اختیاری NUT_DEFAULT_CONNECT_TIMEOUT را لغو می‌کند.

تأخیرهای سرویس (SERVICE DELAYS)

مقدار interval صرفاً عددی است که پس از پیمایش رشته قالب‌بندی به sleep(3) داده می‌شود. بنابراین، اجرای یک استعلام بسته به سرعت سیستم شما در عمل اندکی بیشتر از مقدار interval زمان خواهد برد.

ثبت گزارش بر حسب تقاضا (ON-DEMAND LOGGING)

ارسال سیگنال SIGUSR1 به یک فرآیند در حال اجرای upslog باعث بیدار شدن آن از خواب جاری و ثبت فوری گزارش می‌شود. این قابلیت هنگام راه‌اندازی از طریق یک رویداد upssched (مانند AT ONBATT یا AT ONLINE) بسیار مفید است تا اطمینان حاصل شود که همواره یک ورودی ثبت می‌شود، حتی اگر قطعی برق برای مدت زمانی کوتاه‌تر از مقدار مشخص‌شده با آرگومان -i رخ دهد.

میزبانی مشترک لاگ (LOG CO-LOCATION)

امکان‌پذیر و ایمن است که یک فایل لاگ یکسان (شامل - برای stdout) را در چندین tuple مشخص کنید، و آن فایل تنها یک بار و بدون تداخل باز یا بسته خواهد شد.

افزودن %UPSHOST% به رشته قالب‌بندی سفارشی خود را مدنظر قرار دهید (برای مثال با استفاده از گزینه خط فرمان -N)، تا هنگام ثبت گزارش چندین سیستم در مقصدی یکسان، خطوط مربوط به سیستم‌های مختلف را به آسانی تمیز دهید.

چرخش لاگ (LOG ROTATION)

برنامه upslog شناسه فرآیند خود را در upslog.pid می‌نویسد و در صورت دریافت سیگنال SIGHUP، فایل لاگ را دوباره باز می‌کند. این به برنامه اجازه می‌دهد هنگامی که فایل لاگ توسط یک برنامه خارجی چرخانده (rotate) می‌شود، به اجرای خود ادامه دهد.

نکات قابل توجه (CAVEATS)

از نظر تاریخی، این دیمن از ثبت داده‌ها برای یک سیستم UPS در هر بار اجرا (مشخص‌شده با گزینه -s) درون یک نام فایل لاگ یا stdout (مشخص‌شده با گزینه -l) پشتیبانی می‌کرد.

از نسخه NUT v2.8.1، امکان ثبت گزارش چندین دستگاه (هر کدام درون فایل مقصد مجزا یا در stdout مشترک) طبق مشخصات ارائه‌شده در چندین گزینه tuple با -m فراهم شد. اما این دو حالت در عمل نسبت به یکدیگر مانعة‌الجمع بودند (اگر گزینه‌های tuple نیز ارائه می‌شدند، گزینه‌های تک‌سیستم نادیده گرفته می‌شدند).

از نسخه NUT v2.8.3، گزینه‌های تک‌سیستم به فهرست tupleها افزوده می‌شوند؛ بنابراین هم گزینه‌های قدیمی و هم گزینه‌های جدید را می‌توان با اطمینان برای نظارت بر چندین دستگاه در یک اجرای یکسان به کار برد.