'\" t
.\"     Title: upslog
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 06/21/2026
.\"    Manual: راهنمای NUT
.\"    Source: Network UPS Tools 2\&.8\&.5
.\"  Language: Persian
.\"
.TH "UPSLOG" "8" "06/21/2026" "Network UPS Tools 2\&.8\&.5" "راهنمای NUT"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
upslog \- ثبت‌کننده وضعیت یوپی‌اس (UPS)
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBupslog \-h\fR
.sp
\fBupslog\fR [\fIگزینه‌ها\fR]
.SH "توضیحات (DESCRIPTION)"
.sp
برنامه \fBupslog\fR یک دیمن است که در بازه‌های زمانی مشخص وضعیت یک UPS را جویا می‌شود (poll می‌کند)، متغیرهای مدنظر شما را دریافت کرده، آن‌ها را قالب‌بندی می‌کند و در یک فایل می‌نویسد\&.
.sp
رشته قالب‌بندی پیش‌فرض شامل متغیرهایی است که توسط بسیاری از مدل‌های متداول UPS پشتیبانی می‌شوند\&. برای ساخت رشته سفارشی خود به توضیحات زیر مراجعه کنید\&.
.SH "گزینه‌ها (OPTIONS)"
.PP
\fB\-f\fR \fIformat\fR
.RS 4
نظارت بر UPS با استفاده از این رشته قالب‌بندی\&. اطمینان حاصل کنید که
\fIformat\fR
را در گیومه قرار می‌دهید تا پوسته شما آن را تکه‌تکه نکند\&. کاراکترهای اسکیپ (escape) معتبر در این رشته عبارتند از:
.PP
%%
.RS 4
درج یک نویسه "%" تنها
.RE
.PP
%t
.RS 4
درج یک نویسه TAB منفرد (مانند
printf("\et"))
.RE
.PP
%TIME format%
.RS 4
درج زمان با قالب‌بندی
strftime
.RE
.PP
%ETIME%
.RS 4
درج تعداد ثانیه‌ها از آغاز "Epoch"، مطابق با
time_t\&.
این مقدار اکنون یک عدد ۱۰ رقمی است\&.
.RE
.PP
%HOST%
.RS 4
درج نام میزبان محلی
.RE
.PP
%UPSHOST%
.RS 4
درج میزبان UPS تحت نظارت (بخش
<system>
در مشخصات لاگین شما، برای مثال
ups[@host[:port]])
.RE
.PP
%PID%
.RS 4
درج PID خود
upslog
.RE
.PP
%VAR varname%
.RS 4
درج مقدار متغیر varname (برای جزئیات بیشتر به فصل "Variables" در مستندات توسعه‌دهندگان NUT به صورت آنلاین یا در فایل
docs/nut\-names\&.txt
در سورس‌های نسخه نصب‌شده NUT مراجعه کنید)
.RE
.sp
رشته قالب‌بندی پیش‌فرض به شرح زیر است:
.sp
.if n \{\
.RS 4
.\}
.nf
%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%
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-N\fR
.RS 4
افزودن پیشوند
%UPSHOST%%t
قبل از رشته قالب‌بندی (چه پیش‌فرض و چه سفارشی)\&. هنگام ثبت گزارش چند سیستم در یک مقصد مشترک کاربرد دارد\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBنکته\fR
.ps -1
.br
این گزینه در حال حاضر بررسی نمی‌کند که آیا از قبل
%UPSHOST%
در رشته قالب‌بندی وجود دارد یا خیر (برای مثال به طور صریح مشخص شده باشد)\&.
.sp .5v
.RE
.RE
.PP
\fB\-i\fR \fIinterval\fR
.RS 4
مدت زمان انتظار بر حسب ثانیه میان هر بار نظرسنجی (poll)\&. مقدار پیش‌فرض
\fI30\fR
ثانیه است\&.
.sp
اگر به زمان‌بندی دقیق‌تری نیاز دارید، نوشتن ثبت‌کننده اختصاصی خود را با استفاده از کتابخانه
\fBupsclient\fR(3)
مدنظر قرار دهید\&.
.RE
.PP
\fB\-d\fR \fIcount\fR
.RS 4
خروج پس از تعداد مشخص‌شده به‌روزرسانی‌ها\&. مقدار پیش‌فرض
\fI0\fR
برای حلقه بی‌پایان است (تا زمانی که به روش دیگری متوقف شود)\&.
.RE
.PP
\fB\-l\fR \fIlogfile\fR
.RS 4
ذخیره نتایج در این فایل لاگ\&.
.sp
می‌توانید از
\-
برای stdout استفاده کنید، اما
upslog
به صورت پیش‌فرض در پیش‌زمینه باقی خواهد ماند\&.
.sp
نیازمند آن است که گزینه
\-s <system>
نیز برای ثبت گزارش تک‌سیستمی استفاده شده باشد\&.
.sp
می‌تواند به همراه
\-m <tuple>
استفاده شود و به فهرست اضافه خواهد شد\&.
.RE
.PP
\fB\-D\fR
.RS 4
افزایش سطح جزئیات اشکال‌زدایی به اندازه یک واحد؛
upslog
به صورت پیش‌فرض در پیش‌زمینه باقی خواهد ماند\&.
.RE
.PP
\fB\-F\fR
.RS 4
برنامه upslog صرف‌نظر از مقصد لاگ، در پیش‌زمینه اجرا خواهد شد\&.
.RE
.PP
\fB\-B\fR
.RS 4
برنامه upslog صرف‌نظر از مقصد لاگ یا اشکال‌زدایی، در پس‌زمینه اجرا خواهد شد\&.
.RE
.PP
\fB\-s\fR \fIups\fR
.RS 4
نظارت بر این UPS\&. قالب این گزینه به صورت
upsname[@hostname[:port]]
است\&. نام میزبان پیش‌فرض "localhost" است\&.
.sp
مقدار
\fIupsname\fR
می‌تواند علامت ستاره
*
باشد تا از UPSهایی که در حال حاضر توسط
\fIhostname\fR
سرویس‌دهی می‌شوند استعلام گرفته و هر یک از آن‌ها را (در همان مقصد لاگ) نظارت کند\&.
.sp
نیازمند آن است که گزینه
\-l <logfile>
نیز برای ثبت گزارش تک‌سیستمی استفاده شده باشد\&.
.sp
می‌تواند به همراه
\-m <tuple>
استفاده شود و به فهرست اضافه خواهد شد\&.
.RE
.PP
\fB\-m\fR \fItuple\fR
.RS 4
نظارت بر چندین UPS (با ارائه چندین مورد از این گزینه)\&.
.sp
قالب این گزینه یک چندتایی (tuple) از مشخصات سیستم UPS و فایل لاگ است که با کاما جدا شده‌اند\&. برای مثال:
.sp
.if n \{\
.RS 4
.\}
.nf
upsname@hostname:9999,/var/log/nut/cps\&.log
.fi
.if n \{\
.RE
.\}
.sp
مقدار
\fIupsname\fR
می‌تواند علامت ستاره
*
باشد تا از UPSهایی که در حال حاضر توسط
\fIhostname\fR
سرویس‌دهی می‌شوند استعلام گرفته و بر هر یک از آن‌ها (در همان مقصد لاگ) نظارت کند\&.
.sp
چندتایی‌ها می‌توانند
\-
را به عنوان logfile مشخص کنند تا پیام‌ها در
stdout
منتشر شوند (برای مثال جهت جمع‌آوری توسط ژورنال سیستم برای سرویس‌ها)\&.
.sp
استفاده از
stdout
از طریق مشخصات لاگ مبتنی بر tuple همچنین به این معنی است که upslog به طور پیش‌فرض در پیش‌زمینه باقی خواهد ماند\&.
.RE
.PP
\fB\-u\fR \fIusername\fR
.RS 4
اگر به عنوان
\fIroot\fR
اجرا شود،
upslog
به دلایل امنیتی با استفاده از
\fBsetuid\fR(2)
به شناسه کاربری مرتبط با
\fIusername\fR
تغییر هویت می‌دهد\&.
.sp
اگر
\fIusername\fR
تعریف نشده باشد، از مقداری که در زمان کامپایل درون برنامه تعبیه شده استفاده خواهد کرد\&. این مقدار به طور پیش‌فرض
\fInobody\fR
است (اگر به شکل دیگری پیکربندی نشده باشد)، که چندان مطلوب نیست\&.
.RE
.SH "گزینه‌های عمومی (COMMON OPTIONS)"
.PP
\fB\-h\fR
.RS 4
نمایش پیام راهنمای خط فرمان\&.
.RE
.PP
\fB\-V\fR
.RS 4
نمایش بنر نسخه NUT\&. جزئیات بیشتر در صورتی در دسترس خواهد بود که متغیر محیطی
export NUT_DEBUG_LEVEL=1
یا سطوح اشکال‌زدایی بالاتری را تنظیم کرده باشید\&.
.RE
.PP
\fB\-W\fR \fIsecs\fR
.RS 4
تنظیم مهلت زمانی برای اتصالات اولیه شبکه (به طور پیش‌فرض به صورت نامحدود غیرمسدودکننده هستند، یا تا زمانی که سیستم تلاش را متوقف کند)\&. متغیر محیطی اختیاری
NUT_DEFAULT_CONNECT_TIMEOUT
را لغو می‌کند\&.
.RE
.SH "تأخیرهای سرویس (SERVICE DELAYS)"
.sp
مقدار interval صرفاً عددی است که پس از پیمایش رشته قالب‌بندی به \fBsleep\fR(3) داده می‌شود\&. بنابراین، اجرای یک استعلام بسته به سرعت سیستم شما در عمل اندکی بیشتر از مقدار interval زمان خواهد برد\&.
.SH "ثبت گزارش بر حسب تقاضا (ON\-DEMAND LOGGING)"
.sp
ارسال سیگنال SIGUSR1 به یک فرآیند در حال اجرای \fBupslog\fR باعث بیدار شدن آن از خواب جاری و ثبت فوری گزارش می‌شود\&. این قابلیت هنگام راه‌اندازی از طریق یک رویداد \fBupssched\fR (مانند AT ONBATT یا AT ONLINE) بسیار مفید است تا اطمینان حاصل شود که همواره یک ورودی ثبت می‌شود، حتی اگر قطعی برق برای مدت زمانی کوتاه‌تر از مقدار مشخص‌شده با آرگومان \-i رخ دهد\&.
.SH "میزبانی مشترک لاگ (LOG CO\-LOCATION)"
.sp
امکان‌پذیر و ایمن است که یک فایل لاگ یکسان (شامل \- برای stdout) را در چندین tuple مشخص کنید، و آن فایل تنها یک بار و بدون تداخل باز یا بسته خواهد شد\&.
.sp
افزودن %UPSHOST% به رشته قالب‌بندی سفارشی خود را مدنظر قرار دهید (برای مثال با استفاده از گزینه خط فرمان \fB\-N\fR)، تا هنگام ثبت گزارش چندین سیستم در مقصدی یکسان، خطوط مربوط به سیستم‌های مختلف را به آسانی تمیز دهید\&.
.SH "چرخش لاگ (LOG ROTATION)"
.sp
برنامه \fBupslog\fR شناسه فرآیند خود را در upslog\&.pid می‌نویسد و در صورت دریافت سیگنال SIGHUP، فایل لاگ را دوباره باز می‌کند\&. این به برنامه اجازه می‌دهد هنگامی که فایل لاگ توسط یک برنامه خارجی چرخانده (rotate) می‌شود، به اجرای خود ادامه دهد\&.
.SH "نکات قابل توجه (CAVEATS)"
.sp
از نظر تاریخی، این دیمن از ثبت داده‌ها برای یک سیستم UPS در هر بار اجرا (مشخص‌شده با گزینه \-s) درون یک نام فایل لاگ یا stdout (مشخص‌شده با گزینه \-l) پشتیبانی می‌کرد\&.
.sp
از نسخه NUT v2\&.8\&.1، امکان ثبت گزارش چندین دستگاه (هر کدام درون فایل مقصد مجزا یا در stdout مشترک) طبق مشخصات ارائه‌شده در چندین گزینه tuple با \-m فراهم شد\&. اما این دو حالت در عمل نسبت به یکدیگر مانعة‌الجمع بودند (اگر گزینه‌های tuple نیز ارائه می‌شدند، گزینه‌های تک‌سیستم نادیده گرفته می‌شدند)\&.
.sp
از نسخه NUT v2\&.8\&.3، گزینه‌های تک‌سیستم به فهرست tupleها افزوده می‌شوند؛ بنابراین هم گزینه‌های قدیمی و هم گزینه‌های جدید را می‌توان با اطمینان برای نظارت بر چندین دستگاه در یک اجرای یکسان به کار برد\&.
.SH "همچنین ببینید (SEE ALSO)"
.SS "سرور:"
.sp
\fBupsd\fR(8)
.SS "کلاینت‌ها:"
.sp
\fBupsc\fR(8), \fBupscmd\fR(8), \fBupsrw\fR(8), \fBupsmon\fR(8), \fBupssched\fR(8)
.SS "منابع اینترنتی:"
.sp
صفحه خانگی NUT (Network UPS Tools): https://www\&.networkupstools\&.org/historic/v2\&.8\&.5