SYSTEMTAP(8) System Manager's Manual SYSTEMTAP(8)

systemtap-service - اسکریپت راه‌انداز و سرویس systemd برای SystemTap

systemtap-service COMMAND [OPTIONS] [SCRIPT...]

service systemtap COMMAND [OPTIONS] [SCRIPT...]

هدف اسکریپت راه‌انداز SystemTap فراهم کردن راهکاری برای اجرای اسکریپت‌ها به عنوان یک سرویس و کنترل آسان و مجزای هر یک از آن‌ها است. اسکریپت‌ها می‌توانند طوری پیکربندی شوند که با درخواست دستی کاربر یا هنگام راه‌اندازی سیستم اجرا شوند. در سیستم‌های مبتنی بر dracut، امکان ادغام اسکریپت‌ها در initramfs و اجرای آن‌ها در مراحل اولیه بوت (early-boot) نیز وجود دارد.

اسکریپت راه‌انداز SystemTap را می‌توان به صورت دستی با استفاده از دستور systemtap-service فراخوانی کرد. در سیستم‌های مبتنی بر systemd، این اسکریپت توسط systemctl و با فایل سرویس systemtap.service کنترل می‌شود.

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

فایل پیکربندی اسکریپت راه‌انداز در مسیر /etc/systemtap/config قرار دارد. پارامترهای مجاز با جزئیات در بخش «پارامترهای سراسری (GLOBAL PARAMETERS)» شرح داده شده‌اند.

اسکریپت‌ها باید در دایرکتوری /etc/systemtap/script.d قرار گیرند و پسوند .stp داشته باشند. هنگام ارجاع به آن‌ها در خط فرمان، نیازی به درج پسوند .stp نیست. نام اسکریپت‌ها فقط می‌تواند شامل نویسه‌های الفبایی‌عددی (و '_') باشد و نباید با عدد شروع شود. دایرکتوری اسکریپت‌ها را می‌توان با تنظیم پارامتر SCRIPT_PATH در فایل پیکربندی تغییر داد.

یکی از دستورات زیر باید مشخص شود:

اجرای SCRIPTها. اگر هیچ اسکریپتی مشخص نشده باشد، اسکریپت‌های تعیین‌شده در پیکربندی DEFAULT_START اجرا می‌شوند. اگر DEFAULT_START تنظیم نشده باشد، تمام اسکریپت‌های موجود در دایرکتوری اسکریپت‌ها اجرا خواهند شد. برای اسکریپت‌هایی که از قبل اجرا شده‌اند، این دستور نادیده گرفته می‌شود. در صورت عدم موفقیت در اجرای اسکریپت‌ها، دستور با خطا مواجه خواهد شد (همچنین به پیکربندی PASSALL مراجعه کنید).

اگر گزینه پیکربندی AUTOCOMPILE فعال باشد، در صورت برقرار بودن یکی از شرایط زیر، دستور سعی می‌کند اسکریپت‌های مشخص‌شده را کامپایل یا به‌روزرسانی کند:

-
فایل کش کامپایل‌شده وجود نداشته باشد.
-
زمان ویرایش (mtime) فایل اسکریپت اصلی جدیدتر از زمان کش اسکریپت کامپایل‌شده باشد.
-
گزینه‌های stap مشخص‌شده برای کامپایل اسکریپت تغییر کرده باشند (همچنین به بخش «پارامترهای اسکریپت (SCRIPT PARAMETERS)» مراجعه کنید).
-
نتیجه دستور `uname -a` تغییر کرده باشد.
متوقف کردن SCRIPTها. اگر هیچ اسکریپتی مشخص نشده باشد، تمام اسکریپت‌های در حال اجرا متوقف می‌شوند. برای اسکریپت‌هایی که از قبل متوقف شده‌اند، این دستور نادیده گرفته می‌شود. در صورت عدم موفقیت در متوقف کردن اسکریپت‌ها، دستور با خطا مواجه خواهد شد (همچنین به پیکربندی PASSALL مراجعه کنید).
متوقف کردن و اجرای مجدد SCRIPTها.
نمایش وضعیت SCRIPTها و وابستگی‌های آن‌ها.
کامپایل کردن SCRIPTها بدون شروع اجرای آن‌ها. اگر اسکریپت‌ها از قبل کامپایل شده باشند، پیش از بازنویسی کش، برای تأیید پیام داده می‌شود. کامپایل برای هسته فعلی، یا نسخه انتشار هسته مشخص‌شده با گزینه -r انجام می‌شود.
قرار دادن SCRIPTها به عنوان بخشی از initramfs به طوری که در مراحل اولیه فرآیند بوت اجرا شوند. این دستور فقط در سیستم‌های مبتنی بر dracut در دسترس است. اگر هیچ اسکریپتی مشخص نشده باشد، یک initramfs عادی و فاقد هرگونه فایل SystemTap ایجاد می‌شود.

تصویر initramfs برای هسته فعلی، یا نسخه انتشار هسته مشخص‌شده توسط گزینه -r ایجاد می‌شود. مسیر فایل initramfs ایجادشده به صورت پیش‌فرض /boot/initramfs-KVER.img است، که در آن KVER خروجی دستور `uname -r` می‌باشد. بوت‌لودر نیز (با استفاده از new-kernel-pkg(8)) به‌روزرسانی می‌شود تا مدخل مربوط به هسته از فایل جدید initramfs استفاده کند. از گزینه -o برای تعیین مسیری متفاوت استفاده کنید (در این حالت پیکربندی بوت‌لودر به‌روزرسانی نخواهد شد).

اگر فایل خروجی از قبل وجود داشته باشد، بازنویسی می‌شود مگر آنکه سوییچ -b داده شده باشد، که در این صورت به جای بازنویسی، پسوند .bak به انتهای نام فایل اضافه می‌شود. با این حال، اگر نسخه‌ای با پسوند .bak از قبل وجود داشته باشد، فایل پشتیبان بازنویسی نخواهد شد.

هشدار: از گزینه -o دستور stap(1) همراه با اسکریپت‌های onboot استفاده نکنید، زیرا اسکریپت حتی پیش از مانت شدن فایل‌سیستم ریشه اجرا می‌شود. در صورت نیاز به فضای بیشتر، اندازه بافر را افزایش دهید.

حذف SCRIPTهای کامپایل‌شده از حافظه کش. اگر هیچ اسکریپتی مشخص نشود، تمام اسکریپت‌های کامپایل‌شده حذف می‌شوند. تنها کش مربوط به هسته فعلی، یا نسخه انتشار هسته مشخص‌شده با گزینه -r حذف خواهد شد. قبل از حذف، برای تأیید پیام داده می‌شود.

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

مشخص کردن یک فایل پیکربندی دیگر به جای فایل پیش‌فرض.
هنگام استفاده از دستورات start و stop ، وابستگی‌های اسکریپت‌ها را نیز (به صورت بازگشتی) در بر می‌گیرد.
هنگام استفاده از دستورات compile ، onboot و cleanup ، نسخه هسته هدف را به جای استفاده از هسته فعلی مشخص می‌کند. این مقدار باید در همان قالب خروجی `uname -r` باشد.
پاسخ بله (yes) به تمام پرسش‌های تأییدیه.
هنگام استفاده از دستور onboot ، مسیر خروجی فایل initramfs ایجادشده را مشخص می‌کند. در صورت مشخص شدن، پیکربندی بوت‌لودر به‌روزرسانی نمی‌شود.
هنگام استفاده از دستور onboot ، با افزودن پسوند .bak به جای بازنویسی، از تصویر initramfs موجود یک نسخه پشتیبان تهیه می‌کند. بدون این گزینه، فایل initramfs بازنویسی خواهد شد.

این پارامترها بر رفتار کلی سرویس اسکریپت راه‌انداز SystemTap تأثیر می‌گذارند. آن‌ها را می‌توان در فایل پیکربندی تعیین کرد.

مسیر مطلق دایرکتوری اسکریپت‌ها را مشخص می‌کند. این‌ها اسکریپت‌هایی هستند که اسکریپت راه‌انداز می‌تواند روی آن‌ها عملیات انجام دهد. اسکریپت‌ها باید پسوند .stp داشته باشند. مسیر پیش‌فرض /etc/systemtap/script.d است.
مسیر مطلق دایرکتوری پیکربندی اسکریپت‌ها را مشخص می‌کند. این فایل‌های پیکربندی شامل گزینه‌هایی برای اسکریپت‌های مشخص هستند. آن‌ها باید پسوند .conf داشته باشند. مسیر پیش‌فرض /etc/systemtap/conf.d است.
مسیر مطلق دایرکتوری کش را مشخص می‌کند. مسیر پیش‌فرض /var/cache/systemtap است.
مسیر مطلق دایرکتوری موقتی که SystemTap برای کامپایل اسکریپت‌ها پوشه‌های موقت در آن ایجاد می‌کند را مشخص می‌سازد. مسیر پیش‌فرض /tmp است.
مسیر مطلق دایرکتوری حاوی فایل‌های PID که برای ردیابی وضعیت اسکریپت‌های SystemTap به کار می‌روند را مشخص می‌کند. مسیر پیش‌فرض /var/run/systemtap است.
مسیر مطلق فایل لاگ را مشخص می‌کند. تمام پیام‌ها، از جمله خطاهای کامپایل و زمان اجرا، به این فایل ارسال می‌شوند. مسیر پیش‌فرض /var/log/systemtap.log است.
اگر روی yes تنظیم شده باشد، دستورات اسکریپت راه‌انداز که روی چند اسکریپت عملیات انجام می‌دهند، در صورت عدم امکان انجام عملیات روی حداقل یک اسکریپت، به عنوان شکست‌خورده گزارش می‌شوند. اگر روی no تنظیم شود، تنها یک هشدار صادر می‌شود. مقدار پیش‌فرض yes است.
اگر روی yes تنظیم شده باشد، اسکریپت راه‌انداز همواره وابستگی‌های اسکریپت را به صورت بازگشتی دنبال خواهد کرد. این بدان معناست که نیازی به تعیین گزینه -R نیست. این فلگ تنها در صورتی مؤثر است که اسکریپت(ها) را از طریق خط فرمان مشخص کنید. مقدار پیش‌فرض no است.
اگر روی yes تنظیم شده باشد، در صورت عدم وجود کش معتبر، اسکریپت راه‌انداز در هنگام نیاز به صورت خودکار اقدام به کامپایل اسکریپت‌های مشخص‌شده می‌کند. در غیر این صورت، دستور مربوطه به سادگی با شکست مواجه می‌شود. مقدار پیش‌فرض yes است.
اسکریپت‌هایی را مشخص می‌کند که باید به طور پیش‌فرض راه‌اندازی شوند. در صورت عدم درج (یا خالی بودن)، تمام اسکریپت‌های موجود در دایرکتوری اسکریپت‌ها راه‌اندازی خواهند شد. مقدار پیش‌فرض "" است.
اگر روی yes تنظیم شود، اسکریپت راه‌انداز اجازه عملیات روی اسکریپت‌هایی را که در دایرکتوری کش قرار دارند اما در دایرکتوری اسکریپت‌ها موجود نیستند نیز می‌دهد. مقدار پیش‌فرض no است.

هشدار: با فعال بودن این گزینه، اسکریپت راه‌انداز ممکن است کش‌های منسوخ و غیرمنتظره را بارگذاری کند. پیش از فعال کردن این گزینه، دایرکتوری کش باید بررسی شود.

از آنجا که اسکریپت‌های زمان بوت پیش از مانت شدن فایل‌سیستم ریشه اجرا می‌شوند، خروجی stderr دستور staprun را نمی‌توان طبق معمول در LOG_FILE ثبت کرد. با این حال، با تنظیم LOG_BOOT_ERR روی yes می‌توان خروجی لاگ را در مسیر /run/systemtap/$script.log ذخیره کرد. اگر STAT_PATH با مقدار پیش‌فرض تفاوت داشته باشد، فایل‌های لاگ پس از اجرای هر یک از دستورات اسکریپت راه‌انداز به آنجا منتقل خواهند شد. مقدار پیش‌فرض no است.

نمونه‌ای از یک فایل پیکربندی سراسری در اینجا آمده است:

SCRIPT_PATH=/var/systemtap/script.d/
PASSALL=yes
RECURSIVE=no

این پارامترها بر کامپایل یا رفتار زمان اجرای اسکریپت‌های خاص SystemTap تأثیر می‌گذارند. آن‌ها باید در فایل‌های پیکربندی واقع در دایرکتوری CONFIG_PATH قرار گیرند.

<SCRIPT>_OPT
گزینه‌های ارسالی به دستور stap(1) را برای SCRIPT مشخص می‌کند. در اینجا، SCRIPT نام فایل اسکریپت بدون پسوند .stp است. توجه داشته باشید که گزینه -F همواره اضافه می‌شود.

گزینه‌های زیر هنگام کامپایل اسکریپت‌ها نادیده گرفته می‌شوند: -p, -m, -r, -c, -x, -e, -s, -o, -h, -V, -k.

گزینه‌های زیر هنگام اجرای اسکریپت‌های در حال شروع نادیده گرفته می‌شوند: -h, -V, -v, -t, -p, -I, -e, -R, -r, -m, -k, -g, -P, -D, -b, -u, -q, -w, -l, -d, -L, -F و تمام گزینه‌های بلند (long options).

<SCRIPT>_REQ
وابستگی‌های اسکریپت را مشخص می‌کند (یعنی این اسکریپت به کدام اسکریپت نیاز دارد). برای مثال، اگر foo.stp به bar.stp نیاز داشته باشد (یا لازم باشد پس از آن اجرا شود)، مقدار زیر را تنظیم کنید: 
foo_REQ="bar"

چندین اسکریپت را با جدا کردن نام‌های آن‌ها با فاصله مشخص کنید.

نمونه‌ای از یک فایل پیکربندی اسکریپت در اینجا آمده است:

script1_OPT="-o /var/log/script1.out"
script2_OPT="-o /var/log/script2.out"
script2_REQ="script1"

نصب اسکریپت‌ها (INSTALLING SCRIPTS)
ابتدا یک اسکریپت SystemTap (برای مثال "script1.stp") را در دایرکتوری اسکریپت‌ها کپی می‌کنیم: 
# cp script1.stp /etc/systemtap/script.d/

سپس می‌توانیم گزینه‌های مورد نظر اسکریپت را تنظیم کنیم، به عنوان مثال:

# vi /etc/systemtap/conf.d/group1.conf
script1_OPT="-o /var/log/group1.out"

سپس اسکریپتی (برای مثال "script2.stp") را نصب می‌کنیم که لازم است پس از script1 اجرا شود. در این حالت، می‌توانیم مراحل زیر را انجام دهیم:

# cp script2.stp /etc/systemtap/script.d/
# vi /etc/systemtap/conf.d/group1.conf
script2_OPT="-o /var/log/group2.out"
script2_REQ="script1"

به این ترتیب، اگر دستور stap(1) در اجرای script1 با شکست مواجه شود، اسکریپت راه‌انداز حتی تلاشی برای اجرای script2 نخواهد کرد.

آزمودن (TESTING)
پس از نصب اسکریپت‌ها، می‌توانیم با انجام دستورات زیر اطمینان حاصل کنیم که آن‌ها کار می‌کنند: 
# systemtap-service start
# systemtap-service stop

همچنین می‌توانیم جزئیات بیشتری مشخص کنیم، برای مثال:

# systemtap-service start script1
# systemtap-service stop script1

اگر خطایی وجود نداشت، برای استفاده آماده هستیم.

فعال‌سازی سرویس (ENABLING SERVICE)
پس از رضایت از کارکرد اسکریپت‌ها و آزمایش آن‌ها، می‌توانیم سرویس اسکریپت راه‌انداز SystemTap را فعال کنیم: 
# chkconfig systemtap on
حذف اسکریپت‌ها (DELETING SCRIPTS)
اسکریپت‌ها به سادگی با پاک کردن آن‌ها از دایرکتوری اسکریپت‌ها و حذف خطوط پیکربندی مختص به آن‌ها پاک می‌شوند: 
# rm /etc/systemtap/script.d/script2.stp
# vi /etc/systemtap/conf.d/group1.conf

اگر اسکریپت هنوز در حال اجرا است، باید آن را متوقف کنیم:

# systemtap-service stop script2

سپس می‌توانیم کش مرتبط با اسکریپت را نیز حذف کنیم:

# systemtap-service cleanup script2
آماده‌سازی برای به‌روزرسانی‌های هسته (PREPARING FOR KERNEL UPDATES)
معمولاً هنگام بوت شدن با یک هسته جدید نیاز به انجام کاری نیست. اسکریپت راه‌انداز تفاوت نسخه هسته را متوجه شده و اسکریپت‌ها را کامپایل می‌کند. همچنین با استفاده از گزینه -r می‌توان کامپایل را از قبل انجام داد تا از انجام کامپایل در زمان بوت جلوگیری شود: 
# systemtap-service compile myscript -r <NEW_KERNEL_VERSION>
وارد کردن اسکریپت‌های کامپایل‌شده (IMPORTING COMPILED SCRIPTS)
برای محیط‌هایی که فاقد زیرساخت کامپایل هستند (برای مثال بدون کامپایلرها یا debuginfo)، مانند یک سیستم عملیاتی (production)، اسکریپت‌ها را می‌توان روی یک ماشین دیگر (محیط توسعه) کامپایل کرد و سپس به سیستم عملیاتی انتقال داد: 
# systemtap-service compile myscript -r .br
>   <KERNEL_VERSION_OF_TARGET_MACHINE>
# tar czf stap-scripts-<kernel-version>.tar.gz .br
>   /var/cache/systemtap/<kernel-version> .br
>   /etc/systemtap/conf.d/<configfile>

سپس این بسته را به ماشین هدف منتقل کرده و آن را استخراج کنید.

اجرای اسکریپت‌ها در زمان بوت اولیه (STARTING SCRIPTS DURING EARLY-BOOT)
اسکریپت راه‌انداز همچنین به ما اجازه می‌دهد تا اسکریپت‌ها را با ایجاد یک initramfs حاوی ماژول اسکریپت، زودتر در طول فرآیند بوت اجرا کنیم. سیستم برای کارکرد این قابلیت باید مبتنی بر dracut باشد. اجرای یک اسکریپت در این مرحله، امکان دسترسی به اطلاعاتی را فراهم می‌کند که در غیر این صورت دستیابی به آن‌ها بسیار دشوار خواهد بود.

ما ابتدا اسکریپت را طبق معمول با کپی کردن در دایرکتوری اسکریپت‌ها نصب کرده و هر گزینه‌ای را که می‌خواهیم تنظیم می‌کنیم:

# cp myscript.stp /etc/systemtap/script.d
# vi /etc/systemtap/conf.d/myscript.conf

برای افزودن اسکریپت به initramfs، از دستور onboot استفاده می‌کنیم:

# systemtap-service onboot myscript

اگر اسکریپت از قبل کامپایل و کش نشده باشد، در این مرحله انجام می‌شود. سپس یک initramfs جدید در محل پیش‌فرض ایجاد خواهد شد. می‌توانیم از گزینه -b استفاده کنیم تا اطمینان حاصل شود که از initramfs موجود نسخه پشتیبان تهیه می‌شود. سپس می‌توانیم سیستم را ری‌استارت کنیم.

استفاده از یک INITRAMFS متفاوت (USING A DIFFERENT INITRAMFS)
اگر ترجیح می‌دهیم اسکریپت را فقط برای یک بار بوت اجرا کنیم و نه دفعات دیگر، شاید آسان‌تر باشد که از گزینه -o برای تعیین یک فایل خروجی initramfs دیگر استفاده کنیم: 
# systemtap-service onboot myscript >   -o /boot/special_initramfs.img

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

ایجاد INITRAMFS برای یک هسته دیگر (CREATING AN INITRAMFS FOR A DIFFERENT KERNEL)
درست همانند دستور compile، می‌توانیم از گزینه -r برای مشخص کردن هسته‌ای که می‌خواهیم initramfs را برای آن بسازیم استفاده کنیم. این گزینه زمانی مفید است که قصد ارتقا داریم و می‌خواهیم از قبل آماده باشیم. به عنوان مثال: 
# systemtap-service onboot myscript >   -r 3.12.6-200.fc19.x86_64
حذف اسکریپت‌ها از INITRAMFS (REMOVING SCRIPTS FROM THE INITRAMFS)
در نهایت، برای حذف تمام اسکریپت‌ها از initramfs، کافی است دستور onboot را بدون مشخص کردن هیچ اسکریپتی اجرا کنیم: 
# systemtap-service onboot

این کار صرفاً یک initramfs استاندارد و بدون هیچ‌گونه ماژول تعبیه‌شده SystemTap ایجاد خواهد کرد.

عیب‌یابی مشکلات بوت اولیه (TROUBLESHOOTING EARLY-BOOT ISSUES)
دلایل زیادی می‌تواند وجود داشته باشد که چرا ماژول درج نشده یا مطابق انتظار کار نکرده است. فعال کردن عیب‌یابی dracut با افزودن 'rdinitdebug' به خط فرمان هسته و بررسی dmesg/journalctl -ae می‌تواند مفید باشد. همچنین، خروجی خطای استاندارد (stderr) مربوط به staprun را می‌توان با تنظیم گزینه LOG_BOOT_ERR روی yes ذخیره کرد.

stap(1) dracut(8) new-kernel-pkg(8)

از پیوند باگزیلا در صفحه وب پروژه یا فهرست پستی ما استفاده کنید. http://sourceware.org/systemtap, <systemtap@sourceware.org>.