نام (NAME)

apccontrol — اسکریپت کنترل رویدادهای apcupsd

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

apccontrol { <event> <ups-name> <connected> <powered> }

توضیحات (DESCRIPTION)

هنگامی که apcupsd(8) ناهنجاری‌هایی را در UPS تحت نظارت تشخیص می‌دهد، رویدادی را فراخوانی می‌کند که معمولاً منجر به یک یا چند بار فراخوانی اسکریپت شل apccontrol می‌شود. هر رویداد موجب می‌شود apccontrol اقدام خاصی را انجام دهد. این اقدامات به‌طور پیش‌فرض رفتارهای معقول و استانداردی برای تمام رویدادهایی هستند که احتمال مواجهه apcupsd با آن‌ها وجود دارد. با این حال، می‌توانید رفتار تک‌تک اقدامات را تغییر دهید.

هنگامی که apcupsd رویدادی را تشخیص می‌دهد، اسکریپت apccontrol را با چهار آرگومان زیر فراخوانی می‌کند:

event: این همان رویدادی است که رخ داده است. به فهرست رویدادهای ممکن در زیر مراجعه کنید.
ups-name: نام UPS همان‌طور که در فایل پیکربندی /etc/apcupsd/apcupsd.conf مشخص شده است - نه نام موجود در EEPROM یک UPS هوشمند.
connected: اگر apcupsd از طریق درگاه سریال یا USB به UPS متصل باشد، مقدار آن 1 است. در مورد یک دستگاه پیرو (slave) که apcupsd در آن مستقیماً به UPS متصل نیست، این مقدار 0 خواهد بود.
powered: اگر رایانه‌ای که apcupsd روی آن اجرا می‌شود از UPS تغذیه شود مقدار آن 1 و در غیر این صورت 0 است. این ویژگی در حال حاضر پیاده‌سازی نشده و همیشه پیش‌فرض 0 دارد.

رویدادها به گزارش سیستم (system log) و در صورت تمایل به فایل موقت رویدادها (/etc/apcupsd/apcupsd.events), ارسال می‌شوند، و همچنین فراخوانی apccontrol را ایجاد می‌کنند که به نوبه خود هر اسکریپتی را که در دایرکتوری /etc/apcupsd قرار داده‌اید فراخوانی خواهد کرد.

فهرست رویدادها و اقدامات پیش‌فرض (LIST OF EVENTS AND DEFAULT ACTIONS)

annoyme: برنامه apcupsd این رویداد را زمانی ایجاد می‌کند که خاموش شدن سیستم زمان‌بندی شده باشد و زمان مشخص‌شده توسط دستورالعمل پیکربندی ANNOYME در فایل /etc/apcupsd/apcupsd.conf منقضی شده باشد.
اقدام پیش‌فرض -- پیام "Power problems please logoff." را به wall(1) ارسال کرده و سپس خارج می‌شود.
battattach: برنامه apcupsd این رویداد را هنگامی ایجاد می‌کند که تشخیص دهد باتری UPS پس از رویداد battdetach دوباره متصل شده است.
اقدام پیش‌فرض: کاری انجام نمی‌دهد.
battdetach: برنامه apcupsd این رویداد را هنگامی ایجاد می‌کند که تشخیص دهد باتری UPS قطع شده است.
اقدام پیش‌فرض: کاری انجام نمی‌دهد.
changeme: برنامه apcupsd این رویداد را هنگامی ایجاد می‌کند که تشخیص دهد برق شهری وصل است، اما باتری به‌درستی کار نمی‌کند. این رویداد هر ۹ ساعت تکرار می‌شود.
اقدام پیش‌فرض -- پیام "Emergency! UPS batteries have failed Change them NOW" را به wall ارسال کرده و سپس خارج می‌شود.
commfailure: برنامه apcupsd این رویداد را هر بار که ارتباط با UPS تحت نظارت قطع شود ایجاد می‌کند. این رویداد در UPSهای دارای سیگنال‌دهی ساده مانند Back-UPS 650 تشخیص داده نمی‌شود.
اقدام پیش‌فرض -- پیام "Communications with UPS lost." را به wall ارسال کرده و سپس خارج می‌شود.
commok: برنامه apcupsd این رویداد را پس از یک رویداد commfailure، هنگامی که ارتباط با UPS دوباره برقرار شود، ایجاد می‌کند.
اقدام پیش‌فرض -- پیام "Communications with UPS restored." را به wall ارسال کرده و سپس خارج می‌شود.
doreboot: این رویداد منسوخ شده و نباید استفاده شود.
اقدام پیش‌فرض -- پیام "Beginning Reboot Sequence" را به wall ارسال کرده و سپس shutdown(8) را با آرگومان‌های خط فرمان "-r now"; برای راه‌اندازی مجدد رایانه فراخوانی می‌کند.
doshutdown: برنامه apcupsd این رویداد را برای خاموش کردن رایانه هنگامی که UPS روی توان باتری کار می‌کند و یکی از محدودیت‌ها (زمان، مدت کارکرد، بار مصرفی) فرا رسیده است، ایجاد می‌کند.
اقدام پیش‌فرض -- پیام "Beginning Shutdown Sequence" را به wall ارسال کرده و سپس shutdown(8) را با آرگومان‌های خط فرمان "-h now"; برای خاموش کردن رایانه فراخوانی می‌کند.
emergency: برنامه apcupsd این رویداد را زمانی ایجاد می‌کند که UPS روی توان باتری است، شارژ باتری کم است و برق شهری وصل است: نشانه‌ای قطعی از خرابی باتری!
اقدام پیش‌فرض -- پیام "Emergency Shutdown. Possible UPS battery failure." را به wall ارسال می‌کند. بلافاصله پس از این، apcupsd یک رویداد doshutdown برای خاموش کردن سیستم ایجاد می‌کند.
failing: برنامه apcupsd این رویداد را زمانی ایجاد می‌کند که UPS روی باتری‌ها کار می‌کند و UPS سیگنال باتری ضعیف را فعال می‌نماید که نشان می‌دهد توان باتری تقریباً تمام شده است. پس از این رویداد، apcupsd بلافاصله یک رویداد doshutdown ایجاد خواهد کرد.
اقدام پیش‌فرض -- پیام "UPS battery power exhausted. Doing shutdown." را به wall ارسال کرده و سپس خارج می‌شود.
killpower: برنامه apcupsd معمولاً این رویداد را ایجاد نمی‌کند. در عوض، مستقیماً از اسکریپت توقف سیستم به‌صورت 'apccontrol killpower' فراخوانی می‌شود زیرا رویداد killpower باید تا حد امکان در اواخر فرآیند خاموش شدن سیستم انجام شود.
اقدام پیش‌فرض -- پیام "UPS now committed to shut down" را به wall ارسال کرده، ۱۰ ثانیه صبر می‌کند و سپس دستور "apcupsd --killpower" را صادر می‌کند تا UPS به حالت خواب زمستانی (hibernate) برود و برق تجهیزات متصل قطع شود. در مورد یک UPS هوشمند، سپس UPS منتظر انقضای هرگونه تاخیر زمانی خاموش‌سازی پیکربندی‌شده که توسط دستورالعمل پیکربندی SLEEP مشخص شده است می‌ماند. در حالت خواب زمستانی، UPS برق شهری را با توجه به مقادیر مشخص‌شده برای دستورالعمل‌های پیکربندی RETURNCHARGE و WAKEUP به تجهیزات متصل بازمی‌گرداند.
loadlimit: برنامه apcupsd این رویداد را هنگامی ایجاد می‌کند که حد تخلیه باتری مشخص‌شده توسط دستورالعمل پیکربندی BATTERYLEVEL فرا رسیده باشد.
اقدام پیش‌فرض -- پیام "UPS battery discharge limit reached. Doing shutdown" را به wall ارسال کرده و سپس خارج می‌شود. پس از این رویداد، apcupsd بلافاصله یک رویداد doshutdown ایجاد خواهد کرد.
mainsback: برنامه apcupsd این رویداد را زمانی ایجاد می‌کند که برق شهری پس از یک رویداد powerout بازگردد. رویداد doshutdown بسته به پارامترهایی که تعریف کرده‌اید و مدت زمان قطعی برق ممکن است ایجاد شده یا نشده باشد. هرگز نباید برای لغو یک رویداد doshutdown تلاش شود زیرا بسیار بعید است به موفقیت برسد و تقریباً به‌طور قطع رایانه شما را در وضعیتی نامشخص رها می‌کند.
اقدام پیش‌فرض -- اگر فایل /var/run/powerfail وجود داشته باشد، پیام "Continuing with shutdown." را به wall ارسال کرده و سپس خارج می‌شود. در غیر این صورت، کاری انجام نمی‌دهد.
onbattery: برنامه apcupsd این رویداد را در صورتی ایجاد می‌کند که قطعی برق تشخیص داده شده باشد و UPS پس از انقضای تاخیر مشخص‌شده توسط دستورالعمل پیکربندی ONBATTERYDELAY همچنان روی توان باتری باشد.
اقدام پیش‌فرض -- پیام "Power failure. Running on UPS batteries." را به wall ارسال کرده و سپس خارج می‌شود.
offbattery: برنامه apcupsd این رویداد را زمانی ایجاد می‌کند که برق شهری بازگردد اگر، و تنها اگر، رویداد onbattery ایجاد شده باشد.
پیش‌فرض -- پیام "Power has returned..." را به wall ارسال کرده و سپس خارج می‌شود.
powerout: برنامه apcupsd این رویداد را به محض اینکه تشخیص دهد UPS به توان باتری تغییر وضعیت داده و خودآزمایی (self-test) نیست، ایجاد می‌کند.
اقدام پیش‌فرض -- کاری انجام نمی‌دهد.
remotedown: برنامه apcupsd این رویداد را روی یک دستگاه پیرو (slave) هنگامی ایجاد می‌کند که تشخیص دهد (۱) دستگاه اصلی (master) خاموش شده است، یا (۲) رویداد onbattery رخ داده و ارتباط با دستگاه اصلی قطع شده است.
اقدام پیش‌فرض: پیام "Remote Shutdown. Beginning Shutdown Sequence." را به wall ارسال کرده و خارج می‌شود. بلافاصله پس از این، apcupsd یک رویداد doshutdown برای خاموش کردن سیستم ایجاد می‌کند.
runlimit: برنامه apcupsd این رویداد را هنگامی ایجاد می‌کند که حد زمان کارکرد باقی‌مانده مشخص‌شده توسط دستورالعمل پیکربندی MINUTES، در حالی که UPS به دلیل قطعی برق شهری روی توان باتری است، منقضی شود. زمان کارکرد باقی‌مانده به‌صورت داخلی توسط UPS محاسبه شده و توسط apcupsd نظارت می‌شود.
اقدام پیش‌فرض -- پیام "UPS battery runtime percent reached. Doing shutdown." را به wall ارسال کرده و سپس خارج می‌شود. پس از این رویداد، apcupsd بلافاصله یک رویداد doshutdown ایجاد خواهد کرد.
timeout: برنامه apcupsd این رویداد را زمانی ایجاد می‌کند که زمان مشخص‌شده توسط دستورالعمل پیکربندی TIMEOUT، در حالی که UPS به دلیل قطعی برق شهری روی توان باتری است، منقضی شود. این دستورالعمل پیکربندی معمولاً برای UPSهای هوشمند استفاده نمی‌شود؛ این دستگاه‌ها در عوض بر دستورالعمل‌های پیکربندی مطمئن‌تر زمان کارکرد باقی‌مانده (MINUTES) یا سطح باتری (BATTERYLEVEL) تکیه می‌کنند.
اقدام پیش‌فرض -- پیام "UPS battery runtime limit exceeded. Doing shutdown." را به wall ارسال کرده و سپس خارج می‌شود. پس از این رویداد، apcupsd بلافاصله یک رویداد doshutdown ایجاد خواهد کرد.
startselftest: برنامه apcupsd این رویداد را هنگامی ایجاد می‌کند که شروع خودآزمایی UPS را تشخیص دهد.
اقدام پیش‌فرض: کاری انجام نمی‌دهد.
endselftest: برنامه apcupsd این رویداد را هنگامی ایجاد می‌کند که پایان خودآزمایی UPS را تشخیص دهد.
اقدام پیش‌فرض: کاری انجام نمی‌دهد.

سفارشی‌سازی اقدامات رویدادها (CUSTOMISING EVENT ACTIONS)

اسکریپت apccontrol را مستقیماً تغییر ندهید زیرا با ارتقا به نسخه جدید apcupsd بازنویسی خواهد شد.

روش توصیه‌شده برای سفارشی‌سازی اقدام یک رویداد این است که یک برنامه اجرایی یا فایل اسکریپت با همان نام رویداد ایجاد کرده و آن فایل را در دایرکتوری /etc/apcupsd قرار دهید. اکنون، هنگامی که رویداد انتخاب‌شده رخ دهد، apccontrol برنامه یا اسکریپت شما را اجرا خواهد کرد.

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

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

چند اسکریپت نمونه (changeme، commfailure، commok، offbattery و onbattery) که به‌جای پخش پیام برای همه کاربران واردشده به سیستم، پیام‌ها را به root ایمیل می‌کنند، پس از نصب در /etc/apcupsd و همچنین در دایرکتوری platforms/etc کد منبع apcupsd یافت می‌شوند.