نام (NAME)

rrdcgi - ساخت صفحات وب حاوی نمودارهای RRD بر اساس قالب‌ها

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

"#!/path/to/"rrdcgi [--filter|-f]

توضیحات (DESCRIPTION)

برنامه rrdcgi به نوعی یک مفسر اسکریپت بسیار محدود است. هدف آن اجرا به عنوان یک برنامه cgi و تجزیه قالب یک صفحه وب شامل برچسب‌های ویژه <RRD:: است. rrdcgi این برچسب‌ها را تفسیر کرده و بر اساس آن‌ها عمل می‌کند. در پایان، یک صفحه وب شامل سرآیندهای CGI لازم را چاپ می‌کند.

برنامه rrdcgi محتوای قالب را در ۳ مرحله تجزیه می‌کند. در هر مرحله تنها به دنبال زیرمجموعه‌ای از برچسب‌ها می‌گردد. این کار امکان تو در تو قرار دادن برچسب‌ها را فراهم می‌سازد.

تجزیه‌کننده آرگومان از همان معناشناسی آشنا در C-shell شما استفاده می‌کند.

--filter|-f: فرض می‌کند که rrdcgi به عنوان یک فیلتر اجرا می‌شود، نه به عنوان یک cgi.

کلیدواژه‌ها (Keywords)

RRD::CV name

متغیر CGI با نام مشخص‌شده را درج می‌کند.

RRD::CV::QUOTE name

متغیر CGI با نام مشخص‌شده را درج می‌کند، اما آن را نقل‌قول‌گذاری (quote) می‌کند تا برای استفاده به عنوان آرگومان در برچسب دیگر RRD:: آماده باشد. به این ترتیب حتی اگر در مقدار متغیر CGI فاصله وجود داشته باشد، همچنان به عنوان یک آرگومان در نظر گرفته می‌شود.

RRD::CV::PATH name

متغیر CGI با نام مشخص‌شده را درج کرده، آن را کوت می‌کند و اطمینان حاصل می‌کند که نه با '/' شروع شود و نه شامل '..' باشد. این کار برای اطمینان از این است که هیچ نام مسیر مشکل‌سازی نتواند از طریق رابط CGI وارد شود.

RRD::GETENV variable

مقدار یک متغیر محیطی را دریافت می‌کند.

<RRD::GETENV REMOTE_USER>

در صورتی که از نوعی کنترل دسترسی روی دایرکتوری استفاده کنید، ممکن است نام کاربر دوردست (remote user) را به شما بازگرداند.

RRD::GOODFOR seconds

تعداد ثانیه‌هایی که این صفحه باید معتبر بماند را مشخص می‌کند. این کار باعث می‌شود rrdcgi سرآیندهای Last-Modified و Expire و در صورتی که تعداد ثانیه‌ها منفی باشد، یک سرآیند Refresh در خروجی تولید کند.

RRD::INCLUDE filename

محتوای فایل مشخص‌شده را درون صفحه بازگردانده‌شده از cgi می‌گنجاند.

RRD::SETENV variable value

اگر می‌خواهید نمودارهای خود را در منطقه‌ی زمانی متفاوتی از منطقه‌ی خود نمایش دهید، می‌توانید از

<RRD::SETENV TZ UTC>

استفاده کنید تا اطمینان حاصل شود که همه‌چیز در زمان جهانی (Universal Time) نمایش داده می‌شود. توجه داشته باشید که مقادیر مجاز برای TZ به سیستم‌عامل شما بستگی دارد.

RRD::SETVAR variable value

مشابه SETENV، اما برای متغیرهای محلی.

RRD::GETVAR variable

مشابه GETENV، اما برای متغیرهای محلی.

RRD::TIME::LAST rrd-file strftime-format

این برچسب با زمان آخرین تغییر RRD انتخاب‌شده جایگزین می‌شود. زمان با رشته مشخص‌شده در آرگومان دوم و با قالب strftime قالب‌بندی می‌شود.

RRD::TIME::NOW strftime-format

این برچسب با زمان کنونی روز جایگزین می‌شود. زمان با رشته مشخص‌شده در آرگومان و با قالب strftime قالب‌بندی می‌شود.

توجه داشته باشید که اگر از قالب strftime خود دو نقطه (:) بازمی‌گردانید، چنانچه قرار است زمان به عنوان آرگومانی برای یک دستور GRAPH استفاده شود، ممکن است لازم باشد با استفاده از \ از آن‌ها گریز (escape) بگیرید.

RRD::TIME::STRFTIME START|END start-spec end-spec strftime-format

این برچسب با زمان قالب‌بندی‌شده توسط strftime با استفاده از قالب strftime-format روی start-spec یا end-spec (بسته به این که START یا END مشخص شده باشد) جایگزین می‌شود. هر دو مقدار start-spec و end-spec باید ارائه شوند زیرا هر کدام می‌توانند نسبت به دیگری تعریف شده باشند. هدف از این کار، فراهم آوردن عناوین زیبا روی نمودارها با زمان‌هایی است که درک آن‌ها برای افراد ناآشنا با RRDtool بسیار ساده‌تر از «-2weeks» باشد.

مجدداً توجه داشته باشید که اگر از قالب strftime خود دو نقطه (:) بازمی‌گردانید، چنانچه قرار است زمان به عنوان آرگومانی برای یک دستور GRAPH استفاده شود، ممکن است لازم باشد با استفاده از \ از آن گریز بگیرید.

RRD::GRAPH rrdgraph arguments

این برچسب نمودار RRD تعریف‌شده با آرگومان‌هایش را ایجاد کرده و سپس با یک برچسب مناسب <IMG ... > که به نمودار ارجاع می‌دهد جایگزین می‌شود. گزینه --lazy در rrdgraph می‌تواند برای اطمینان از این که نمودارها تنها در صورت منقضی شدن دوباره تولید شوند، استفاده شود. آرگومان‌های برچسب RRD::GRAPH مطابق با توضیحات موجود در صفحه راهنمای rrdgraph کار می‌کنند.

برای کاهش بار روی سرور خود، از گزینه --lazy در برچسب‌های RRD::GRAPH استفاده کنید. این گزینه تضمین می‌کند که نمودارها فقط هنگامی که نسخه‌های قدیمی منقضی شده باشند، دوباره تولید شوند.

اگر قالب --imginfo اختصاصی خود را مشخص نکنید، مورد زیر استفاده خواهد شد:

<IMG SRC="%s" WIDTH="%lu" HEIGHT="%lu">

توجه داشته باشید که %s بیانگر بخش نام فایل نمودار ایجاد شده است؛ تمامی دایرکتوری‌های مشخص‌شده در آرگومان فایل PNG نادیده گرفته خواهند شد.

RRD::PRINT number

اگر برچسب RRD::GRAPH قبلی شامل هرگونه آرگومان PRINT بوده باشد، می‌توانید با این برچسب به خروجی آن‌ها دسترسی پیدا کنید. آرگومان number به شماره آرگومان PRINT اشاره دارد. نخستین PRINT دارای شماره 0 است.

RRD::INTERNAL <var>

این برچسب با یک متغیر داخلی جایگزین می‌شود. در حال حاضر این متغیرها شناخته شده‌اند: VERSION و COMPILETIME. این متغیرها مقادیر کامپایل‌شده در برنامه را نشان می‌دهند.

مثال ۱ (EXAMPLE 1)

مثال زیر یک صفحه وب با یک نمودار RRD منفرد ایجاد می‌کند.

#!/usr/local/bin/rrdcgi
<HTML>
<HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
<BODY>
<H1>RRDCGI Example Page</H1>
<P>
<RRD::GRAPH demo.png --lazy --title="Temperatures"
         DEF:cel=demo.rrd:exhaust:AVERAGE
         LINE2:cel#00a000:"D. Celsius">
</P>
</BODY>
</HTML>

مثال ۲ (EXAMPLE 2)

این اسکریپت کمی پیشرفته‌تر است؛ به شما اجازه می‌دهد تا آن را از طریق فرمی که متغیر RRD_NAME را تنظیم می‌کند اجرا کنید. سپس از RRD_NAME برای انتخاب RRD مورد نظر به عنوان منبع نمودار استفاده می‌شود.

#!/usr/local/bin/rrdcgi
<HTML>
<HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
<BODY>
<H1>RRDCGI Example Page for <RRD::CV RRD_NAME></H1>
<H2>Selection</H2>
<FORM><INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomA> Room A,
      <INPUT NAME=RRD_NAME TYPE=RADIO VALUE=roomB> Room B.
      <INPUT TYPE=SUBMIT></FORM>
<H2>Graph</H2>
<P>
<RRD::GRAPH <RRD::CV::PATH RRD_NAME>.png --lazy
         --title "Temperatures for "<RRD::CV::QUOTE RRD_NAME>
         DEF:cel=<RRD::CV::PATH RRD_NAME>.rrd:exhaust:AVERAGE
         LINE2:cel#00a000:"D. Celsius">
</P>
</BODY>
</HTML>

مثال ۳ (EXAMPLE 3)

این مثال نحوه مدیریت وضعیتی را نشان می‌دهد که در آن فایل‌های RRD، نمودارها و cgi-binها در دایرکتوری‌های جداگانه‌ای قرار دارند.

#!/.../bin/rrdcgi
<HTML>
<HEAD><TITLE>RRDCGI Demo</TITLE></HEAD>
<BODY>
<H1>RRDCGI test Page</H1>
<RRD::GRAPH
 /.../web/pngs/testhvt.png
 --imginfo '<IMG SRC=/.../pngs/%s WIDTH=%lu HEIGHT=%lu >'
 --lazy --start -1d --end now
 DEF:http_src=/.../rrds/test.rrd:http_src:AVERAGE
 AREA:http_src#00ff00:http_src
>
</BODY>
</HTML>

نکته ۱: بخش /.../ را با دایرکتوری‌های مربوطه جایگزین کنید.

نکته ۲: مقدار SRC=/.../pngs باید از دیدگاه وب‌سرور/مرورگر یک مسیر معتبر باشد.

نویسنده (AUTHOR)

Tobias Oetiker <tobi@oetiker.ch>