'\"macro stdmacro
.\"
.\" Copyright (c) 2024 Ken McDonell.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PCP-CHECK 1 "PCP" "Performance Co-Pilot"
.SH "نام (NAME)"
\f3pcp-check\f1 \- مدیریت پیکربندی مؤلفه‌های اختیاری PCP
.SH "خلاصه دستور (SYNOPSIS)"
\f3$pcp-check\f1
[\f3\-a\f1] [\f3\-d\f1] [\f3\-l\f1] [\f3\-n\f1] [\f3\-s\f1]
[\f3\-v\f1] [\f3\-x\f1] [component ...]
.br
\f3$pcp-check\f1
[\f3\-a\f1] [\f3\-c\f1 script]] [\f3\-d\f1] [\f3\-l\f1] [\f3\-n\f1] [\f3\-s\f1]
[\f3\-v\f1] [\f3\-x\f1]
.br
\f3$PCP_BINADM_DIR/pmcheck\f1 ...
.SH "توضیحات (DESCRIPTION)"
مجموعهٔ Performance Co-Pilot (PCP) شامل تعدادی مؤلفهٔ اصلی است که احتمالاً از پیش پیکربندی شده و فعال هستند، اما همچنین شامل تعداد بیشتری مؤلفه است که به‌طور پیش‌فرض فعال نیستند.
در چارچوب
.B pmcheck
این مؤلفه‌ها شامل سرویس‌هایی هستند که معمولاً در حین فرایند راه‌اندازی (بوت) سیستم آغاز می‌شوند؛ مانند
.BR pmcd (1)،
.BR pmlogger (1)،
.BR pmproxy (1)
و غیره؛ یا کارگزاران اختیاری دامنهٔ سنجه‌های کارایی (PMDAها) که معیارهای کارایی موجود و ارائه‌شده توسط
.BR pmcd (1)
را گسترش می‌دهند.
.PP
ابزار
.B pmcheck
امکان بررسی و پرس‌وجوی وضعیت مؤلفه‌ها را با گزینهٔ \fB\-s\fR یا \fB\-\-state\fR فراهم می‌کند.
مؤلفه‌ها می‌توانند با گزینهٔ
\fB\-a\fR یا \fB\-\-activate\fR فعال شده،
یا با گزینهٔ
\fB\-d\fR یا \fB\-\-deactivate\fR غیرفعال شوند.
این سه گزینه در هر بار اجرای دستور
.B pmcheck
ناسازگار با یکدیگر (مانعة‌الجمع) هستند و در صورت عدم استفاده از هر یک از آن‌ها، گزینهٔ
.B \-s
به‌عنوان پیش‌فرض در نظر گرفته می‌شود.
.PP
مجموعهٔ مؤلفه‌هایی که باید بررسی یا پیکربندی شوند با نام یا نام‌های
.I component
از طریق خط فرمان تعیین می‌شوند؛ در غیر این صورت و در صورت عدم وجود هرگونه آرگومان
.IR component ،
تمام مؤلفه‌های شناخته‌شده در نظر گرفته می‌شوند.
هنگامی که یک یا چند آرگومان
.I component
مشخص شود، این آرگومان‌ها اختیاری می‌توانند الگوهای
.BR sh (1)
(تطبیق glob) باشند که با نام‌های مؤلفه‌های شناخته‌شده مطابقت داده می‌شوند.
.PP
گزینهٔ \fB\-l\fR یا \fB\-\-list\fR مؤلفه‌های شناخته‌شده را گزارش می‌دهد.
با تعیین یک یا چند
.I component
وضعیت هر یک از آن‌ها گزارش می‌شود.
بدون هیچ آرگومان
.IR component ،
گزینهٔ
.I \-l
تمام مؤلفه‌های شناخته‌شده را فهرست می‌کند که در واقع تمامی اسکریپت‌های مؤلفه (بخش
.B "COMPONENT SCRIPTS"
در ادامه را ببینید)
ذخیره‌شده در دایرکتوری
.I $PCP_SHARE_DIR/lib/pmcheck
هستند.
اگر گزینهٔ
.B \-v
نیز استفاده شود، یک توضیح کوتاه از هر مؤلفهٔ درخواست‌شده نیز نمایش داده خواهد شد.
.PP
مؤلفه‌های اضافی می‌توانند در چارچوب
.B pmcheck
ادغام شوند، و گزینهٔ
\fB\-c\fR یا \fB\-\-file\fR
اجازه می‌دهد یک
.I script
جایگزین در
.BR sh (1)
به جای اسکریپت مرتبط با یک
.I component
شناخته‌شده مورد استفاده قرار گیرد.
.PP
در ترکیب با گزینه‌های
.B \-a
یا
.BR \-d ،
گزینهٔ \fB\-n\fR یا \fB\-\-show-me\fR یک اجرای آزمایشی (dry run) انجام می‌دهد، به این ترتیب که دستورهای
.BR sh (1)
را که برای انجام پیکربندی مجدد لازم هستند نمایش می‌دهد، اما هیچ‌گونه پیکربندی مجددی انجام نمی‌شود.
دستورهایی که باید با دسترسی «root» اجرا شوند با پیشوند
.B #
و سایر دستورها با پیشوند
.B $
نمایش داده می‌شوند.
.PP
گزینهٔ \fB\-v\fR یا \fB\-\-verbose\fR میزان جزئیات گزارش را افزایش می‌دهد.
.PP
گزینهٔ \fB\-x\fR یا \fB\-\-trace\fR می‌تواند برای تعیین اجرای اسکریپت‌های مؤلفه با گزینهٔ
.B \-x
در
.BR sh (1)
استفاده شود.
این کار می‌تواند به اشکال‌زدایی خطاهای یک اسکریپت مؤلفه یا در حین توسعهٔ یک اسکریپت مؤلفهٔ جدید کمک کند؛ که احتمالاً همراه با استفاده از گزینهٔ
.B \-c
در
.B pmcheck
خواهد بود.
.PP
گزینهٔ \fB\-?\fR یا \fB\-\-help\fR
پیام راهنمای نحوهٔ استفاده را نمایش می‌دهد.
.PP
برای سهولت،
.B pmcheck
یک نام مستعار برای
.B pcp-check
است..SH "اسکریپت‌های مؤلفه (COMPONENT SCRIPTS)"
چارچوب
.B pmcheck
توسعه‌پذیر است، زیرا مجموعهٔ مؤلفه‌های شناخته‌شده توسط نام اسکریپت‌های مؤلفه در دایرکتوری
.I $PCP_SHARE_DIR/lib/pmcheck
تعریف می‌شود.
.PP
هر اسکریپت مؤلفه برای ادغام درست با
.BR pmcheck
باید از قواعد زیر پیروی کند:
.IP \(bu 2n
.PD 0
اسکریپت با
.BR sh (1)
اجرا خواهد شد؛ اگر به زبان اسکریپت‌نویسی دیگری نیاز دارید، باید یک پوشش (wrapper) در
.BR sh (1)
ارائه دهید.
.IP \(bu
از آنجا که هر اسکریپت مسئول یک مؤلفه است، نام مؤلفه به‌طور ضمنی مشخص است؛ با این حال نام مؤلفه از طرف
.B pmcheck
به‌عنوان تنها آرگومان پس از گزینه‌ها نیز فرستاده می‌شود.
این ویژگی اجازه می‌دهد اسکریپت‌های مؤلفهٔ عمومی به‌صورت پیوندهای سخت (hard links) در زیر
.I $PCP_SHARE_DIR/lib/pmcheck
پیاده‌سازی شوند.
.IP \(bu
هنگامی که با گزینهٔ
\fB\-l\fR، \fB\-\-list\fR
فراخوانی شود، اسکریپت کاری انجام نمی‌دهد؛ مگر این‌که هم‌زمان با گزینهٔ
.B \-v
فراخوانده شود که در این حالت توضیح کوتاهی از مؤلفه در خروجی استاندارد نمایش داده می‌شود.
.IP \(bu
هنگامی که با گزینهٔ
\fB\-s\fR، \fB\-\-state\fR
فراخوانی شود، اسکریپت باید با یک کد خروجی که وضعیت مؤلفه را مشخص می‌کند پایان یابد؛ یعنی 0
(فعال)، 1 (غیرفعال، اما
.I می‌تواند
توسط
.BR pmcheck
فعال شود)،
2 (غیرفعال و
.I نمی‌تواند
توسط
.BR pmcheck
فعال گردد).
تمایز میان کدهای خروج 1 و 2 بر اساس عوامل متعددی است، اما 1 معمولاً به این معنی است که تمام بسته‌های نرم‌افزاری لازم (PCP و موارد دیگر) نصب شده‌اند، سرویس‌های پیش‌نیاز مورد نیاز در حال اجرا هستند یا می‌توانند بدون خطر راه‌اندازی شوند، و هرگونه پیکربندی مؤلفه می‌تواند تنظیمات پیش‌فرض را در نظر بگیرد یا به‌طور قابل اطمینان استنتاج شود، برای نمونه شماره درگاه (پورت) برای ارتباطات.
در مقابل، 2 به این معنی است که فعال‌سازی خودکار مؤلفه ممکن نیست و به مداخلهٔ کاربر نهایی نیاز است.
.IP \(bu
هنگامی که با گزینهٔ \fB\-a\fR، \fB\-\-activate\fR فراخوانی شود،
اسکریپت باید مؤلفه را فعال کند.
این به معنای اعمال هرگونه تغییر پیکربندی لازم است تا در راه‌اندازی مجدد بعدی سیستم یا راه‌اندازی مجدد
.BR pmcd (1)
مجدداً راه‌اندازی
.I شود،
و در صورتی که در حال حاضر غیرفعال است، مؤلفه را آغاز کند.
.IP \(bu
هنگامی که با گزینهٔ \fB\-d\fR، \fB\-\-deactivate\fR فراخوانی شود،
اسکریپت باید مؤلفه را غیرفعال کند.
این به معنای متوقف کردن مؤلفه در صورت فعال بودن آن در حال حاضر، و اعمال هرگونه تغییر پیکربندی لازم است تا در راه‌اندازی مجدد بعدی سیستم یا راه‌اندازی مجدد
.BR pmcd (1)
مجدداً راه‌اندازی
.IR "نشود" .
.IP \(bu
هنگامی که با گزینهٔ \fB\-n\fR، \fB\-\-show-me\fR فراخوانی شود،
اسکریپت باید یک اجرای آزمایشی (dry run) انجام داده و هر دستور لازم را مطابق با قواعد شرح‌داده‌شده در بالا برای گزینهٔ
.B \-n
در
.BR pmcheck
در خروجی استاندارد چاپ (echo) کند.
.IP \(bu
اگر گزینهٔ \fB\-v\fR، \fB\-\-verbose\fR نیز مشخص شده باشد،
اسکریپت باید متن توضیحی را در خروجی استاندارد ارائه دهد تا به روشن شدن وضعیت کمک کند، به‌ویژه در مواردی که مؤلفه فعال نیست یا پیکربندی مجدد ناموفق بوده است.
.PD
.PP
برای کمک به توسعهٔ اسکریپت مؤلفه، فایل
.I $PCP_SHARE_DIR/lib/checkproc.sh
می‌تواند بارگذاری (source) شود (پس از بارگذاری
.IR $PCP_DIR/etc/pcp.env ).
فایل
.I checkproc.sh
سرویس‌های زیر را ارائه می‌دهد:
.IP \(bu 2n
.PD 0
یک دایرکتوری موقت ایجاد شده و متغیر شل
.B $tmp
به مسیر کامل دایرکتوری اختصاص می‌یابد.
.IP \(bu
متغیر شل
.B $status
برای بازگرداندن وضعیت خروج از اسکریپت استفاده می‌شود [پیش‌فرض 0 است].
.IP \(bu
متغیر شل
.B $component
به نام مؤلفهٔ مربوطه اختصاص می‌یابد.
.IP \(bu
متغیر شل
.B $prog
به نام پایهٔ (basename) اسکریپت اختصاص می‌یابد (بنابراین در حالت پیش‌فرض همان نام مؤلفه است).
.IP \(bu
یک
.B trap
برای پاک‌سازی
.B $tmp
و خروج با وضعیت
.B $status
تنظیم شده است.
.IP \(bu
یک رویهٔ شل به نام
.B _do_args
که تمام تجزیهٔ آرگومان‌های دستور را مدیریت می‌کند.
.IP \(bu
متغیرهای شل
.BR $aflag ،
.BR $dflag ،
.BR $lflag
یا
.B $sflag
دارای مقادیر پیش‌فرض
.B false
هستند و هنگامی که گزینه‌های
.BR \-a ،
.BR \-d ،
.BR \-l
یا
.B \-s
تجزیه شوند، توسط
.B _do_args
روی
.B true
تنظیم می‌شوند.
.IP \(bu
متغیر شل
.B $show_me
دارای مقدار پیش‌فرض
.B false
بوده و زمانی که گزینهٔ
.B \-n
تجزیه شود، توسط
.B _do_args
روی
.B true
تنظیم می‌گردد.
.IP \(bu
متغیر شل
.B $verbose
تعداد گزینه‌های
.B \-v
تجزیه‌شده توسط
.B _do_args
را می‌شمارد.
.IP \(bu
یک رویهٔ شل به نام
.B _ctl_svc
که درخواست‌های وضعیت و تمام عملیات پیکربندی مجدد را برای سرویس‌هایی که توسط
.BR systemctl (1)
یا
.BR init (1)
یا لایه‌های زیرساختی مشابه مدیریت می‌شوند، مدیریت می‌کند.
.B _ctl_svc
۲ آرگومان می‌گیرد، اولی یک
.I action
(یکی از
.BR state ،
.BR start ،
.BR stop ،
.B activate
(enable و start)،
یا
.B deactivate
(stop و disable))،
و دومی
.I name
مؤلفه است؛
برای مؤلفه‌های مدیریت‌شده توسط
.BR systemctl (1) ،
مقدار
.I name
باید نام پایهٔ (basename) سرویس باشد، مثلاً
.B pmcd
برای واحد
.B pmcd.service
در
.BR systemd (1) ،
در غیر این صورت
.I name
نام اسکریپت
.BR init (1)
یا اسکریپت «rc» مشابه است..IP \(bu
.B _ctl_svc
مقداری را (از طریق
.B $?
هنگامی که از یک اسکریپت شل فراخوانی شود) بازمی‌گرداند که با کدهای خروج تعریف‌شده در بالا برای هر کنش مطابقت دارد.
.IP \(bu
یک رویهٔ شل
.B _ctl_pmda
که درخواست‌های وضعیت و تمامی عملیات پیکربندی مجدد را برای یک PMDA متصل به
.BR pmcd (1)
مدیریت می‌کند.
.B _ctl_pmda
حداقل ۲ آرگومان می‌گیرد؛ نخستین آرگومان یک کنش است (یکی از
.BR state ،
.B activate
یا
.BR deactivate )
و آرگومان دوم نام PMDA است.
برای کنش
.BR install ،
یک آرگومان سوم برای نام فایل اجرایی یا DSO مربوط به PMDA وجود دارد و یک آرگومان اختیاری چهارم نیز نام فایلی است که ورودی مورد نیاز برای اسکریپت
.I Install
مربوط به PMDA را ارائه می‌دهد (پیش‌فرض /dev/null است).
.IP \(bu
.B _ctl_pmda
مقداری را (از طریق
.B $?
هنگامی که از یک اسکریپت شل فراخوانی شود) بازمی‌گرداند که با کدهای خروج تعریف‌شده در بالا برای هر کنش مطابقت دارد.
.PD
.PP
بنابراین مورد زیر ساده‌ترین اسکریپت مؤلفهٔ ممکن برای یک سرویس سیستمی است.
.PP
.ft CR
.nf
#!/bin/sh
\&. $PCP_DIR/etc/pcp.env || exit 1
\&. $PCP_SHARE_DIR/lib/checkproc.sh
.sp 0.5v
_do_args "$@"
.sp 0.5v
if $lflag
then
    [ $verbose -gt 0 ] && echo "my description"
elif $sflag
then
    _ctl_svc state $component
    status=$?
elif $aflag
then
    _ctl_svc activate $component || status=1
elif $dflag
then
    _ctl_svc deactivate $component || status=1
fi
.fi
.ft
.PP
و مورد زیر ساده‌ترین اسکریپت مؤلفهٔ ممکن برای یک PMDA است.
.PP
.ft CR
.nf
#!/bin/sh
\&. $PCP_DIR/etc/pcp.env || exit 1
\&. $PCP_SHARE_DIR/lib/checkproc.sh
.sp 0.5v
_do_args "$@"
.sp 0.5v
if $lflag
then
    [ $verbose -gt 0 ] && echo "my description"
elif $sflag
then
    _ctl_pmda state $component
    status=$?
elif $aflag
then
    _ctl_pmda activate $component || status=1
elif $dflag
then
    _ctl_pmda deactivate $component || status=1
fi
.fi
.ft
.SH "خطاها (DIAGNOSTICS)"
برای
.B pmcheck
(نه اسکریپت‌های مؤلفه)، وضعیت خروج معمولاً 0 است، اما مقادیر 9 یا 99 نشان‌دهندهٔ اشکالات داخلی جدی هستند.
.PP
هنگامی که گزینه‌های
.B \-a
یا
.B \-d
استفاده شوند، موفقیت یا شکست پیکربندی مجدد روی خروجی استاندارد گزارش می‌شود.
.PD
.SH "هشدار (CAVEAT)"
برخی مؤلفه‌ها دارای پیش‌نیازهایی هستند که نیازمند نصب، پیکربندی و فعال بودن سرویس‌های غیر PCP دیگری می‌باشند؛ مانند یک سرور پایگاه داده یا یک سرور کلید-مقدار.
در این موارد، بررسی وضعیت سرویس‌های غیر PCP ممکن است مشمول برخی کنترل‌های دسترسی باشد و اگر
.B pmcheck
توسط کاربری غیر از ریشه (non-root) اجرا شود، ممکن است خروجی حاصل از
.B \-s
(پیش‌فرض)
ناقص یا گمراه‌کننده باشد؛ در این شرایط، اجرای
.B pmcheck
به‌عنوان کاربر ریشه (root) گزارش دقیق‌تری ارائه خواهد داد.
.SH "محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند \fBPCP_\fP برای مقداردهی نام فایل‌ها و دایرکتوری‌های مورد استفاده توسط PCP به کار می‌روند.
در هر نصب، فایل \fI/etc/pcp.conf\fP حاوی مقادیر محلی برای این متغیرها است.
متغیر \fB$PCP_CONF\fP ممکن است برای تعیین یک فایل پیکربندی جایگزین استفاده شود، همان‌طور که در \fBpcp.conf\fP(5) شرح داده شده است..SH "همچنین ببینید (SEE ALSO)"
.BR init (1)،
.BR PCPIntro (1)،
.BR pmcd (1)،
.BR pmlogger (1)،
.BR pmproxy (1)،
.BR sh (1)،
.BR systemctl (1)،
.BR pcp.conf (5)
و
.BR pcp.env (5).

.\" control lines for scripts/man-spell
.\" +ok+ _ctl_pmda _ctl_svc _do_args aflag checkproc dflag
.\" +ok+ gt {from test -gt}  lflag pre prog rc {from ``rc'' script}
.\" +ok+ sflag show_me tmp