نام (NAME)

tlsrpt-reportd - دیمنی برای ایجاد و تحویل گزارش‌های TLSRPT مطابق با RFC 8460

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

tlsrpt-reportd [گزینه]

توضیحات (DESCRIPTION)

برنامه tlsrpt-reportd مؤلفه نهایی در چارچوب کاری TLSRPT است. یک MTA (عامل انتقال ایمیل) تحویل موفقیت‌آمیز یا خطاهای رخ‌داده را از طریق libtlsrpt به یک tlsrpt-collectd گزارش می‌دهد که وظیفه جمع‌آوری و پیش‌تجمیع داده‌ها را بر عهده دارد. ابزار tlsrpt-fetcher مرتبط با یک tlsrpt-collectd، داده‌های پیش‌تجمیع‌شده را به tlsrpt-reportd منتقل می‌کند. برنامه tlsrpt-reportd می‌تواند داده‌ها را از چندین tlsrpt-fetcher دریافت کرده و داده‌های پیش‌تجمیع‌شده را در قالب گزارش‌های نهایی تجمیع کند. این گزارش‌ها با gzip فشرده شده و به مقاصدی ارسال می‌شوند که در رکوردهای DNS مربوط به TLSRPT دامنه‌های دریافت‌کننده ایمیل از MTA مشخص شده‌اند.

یک نمودار جریان داده ساده که نحوه تعامل مؤلفه‌ها را نشان می‌دهد به شرح زیر است:

(MTA)
v
libtlsrt
v
tlsrpt-collectd
v
(storage)
v
tlsrpt-fetcher
v
tlsrpt-reportd
v
(report destination)

گزینه‌ها (OPTIONS)

گزینه‌های ایجاد و پیکربندی گزارش (Report creation and configuration options)

--contact_info=addr

استفاده از addr به عنوان اطلاعات تماس در گزارش TLSRPT بر اساس RFC 8460.

--organization_name=descr

استفاده از descr به عنوان نام سازمان ارسال‌کننده گزارش TLSRPT بر اساس RFC 8460.

--sender_address=email

استفاده از email به عنوان نشانی «From:» هنگام ارسال گزارش‌ها از طریق ایمیل.

--fetchers=list

فهرستی از دستورات واکشی‌کننده (fetcher) جهت بازیابی داده‌ها. می‌توان چندین دستور واکشی‌کننده را با کاما جدا کرد.

--dbname=path

استفاده از پایگاه داده SQLite در مسیر path.

--compression_level=n

استفاده از سطح فشرده‌سازی n برای فشرده‌سازی گزارش‌های TLSRPT با الگوریتم gzip.

--keep_days=n

نگهداری داده‌های قدیمی به مدت n روز پیش از حذف از پایگاه داده.

گزینه‌های تحویل گزارش (Report delivery options)

--spread_out_delivery=sec

توزیع و پخش کردن زمان تحویل گزارش‌های TLSRPT در طول sec ثانیه. حداقل مقدار ۱ است و باعث می‌شود تمامی گزارش‌ها بلافاصله ارسال شوند. طبق بخش ۴.۱ از RFC 8460، این مقدار باید روی چند ساعت تنظیم شود. به عنوان مثال، برای پخش کردن زمان تحویل گزارش‌ها در طول چهار ساعت، مقدار spread_out_delivery را روی 14400 قرار دهید.

--sendmail_script=path

استفاده از اسکریپت path جهت ارسال گزارش TLSRPT از طریق ایمیل.

--sendmail_timeout=sec

تنظیم زمان انقضا (timeout) بر حسب sec ثانیه برای درخواست‌های ارسال ایمیل جهت تحویل گزارش‌ها.

--http_script=path

استفاده از اسکریپت path جهت بارگذاری گزارش TLSRPT از طریق پروتکل HTTP(S).

--http_timeout=sec

تنظیم زمان انقضا (timeout) بر حسب sec ثانیه برای درخواست‌های HTTP POST جهت تحویل گزارش‌ها.

--max_retries_delivery=n

صرف‌نظر کردن پس از n بار تلاش ناموفق برای تحویل یک گزارش به مقصد خود.

--min_wait_delivery=sec

حداقل زمان انتظار پیش از تلاش مجدد برای تحویل ناموفق گزارش.

--max_wait_delivery=sec

حداکثر زمان انتظار پیش از تلاش مجدد برای تحویل ناموفق گزارش.

--http_upload_map=path

بارگذاری جدول نگاشت تبدیل برای مقاصد گزارش HTTPS از پرونده path. نمی‌توان هم‌زمان با --debug_send_http_dest استفاده کرد!

--mail_destination_map=path

بارگذاری جدول نگاشت تبدیل برای مقاصد گزارش SMTP از پرونده path. نمی‌توان هم‌زمان با --debug_send_mail_dest استفاده کرد!

--tlsrpt_record_map=path

بارگذاری جدول نگاشت تبدیل برای تمامی مقاصد گزارش بر اساس دامنه TLSRPT از پرونده path. نمی‌توان هم‌زمان با --debug_send_file_dest استفاده کرد!

گزینه‌های کنترل تعامل با یک یا چند tlsrpt-collectd (Options controlling the interaction with one or more tlsrpt-collectd)

--max_collectd_timediff=sec

ثبت یک هشدار در لاگ اگر ساعت اعلام‌شده collectd توسط واکشی‌کننده (fetcher) بیش از sec ثانیه با ساعت reportd اختلاف داشته باشد. برنامه reportd کار پرس‌وجو از واکشی‌کننده‌ها را sec ثانیه پس از تغییر روز به وقت UTC آغاز می‌کند؛ بنابراین اختلاف ساعت بیشتر از sec ثانیه نشان می‌دهد که collectd ممکن است هنوز برای ارائه داده‌های کامل روز قبل آماده نباشد.

--max_collectd_timeout=sec

حداکثر sec ثانیه انتظار برای اتمام درخواست داده توسط fetcher از collectd مربوطه.

--max_retries_domaindetails=n

صرف‌نظر کردن پس از n بار تلاش ناموفق در بازیابی جزئیات گزارش برای یک دامنه.

--min_wait_domaindetails=sec

حداقل زمان انتظار پیش از تلاش مجدد پس از یک تلاش ناموفق برای دریافت جزئیات گزارش دامنه از یک tlsrpt-collectd.

--max_wait_domaindetails=sec

حداکثر زمان انتظار پیش از تلاش مجدد پس از یک تلاش ناموفق برای دریافت جزئیات گزارش دامنه از یک tlsrpt-collectd.

--max_retries_domainlist=n

صرف‌نظر کردن پس از n بار تلاش ناموفق برای دریافت فهرست دامنه‌ها از یک tlsrpt-collectd.

--min_wait_domainlist=sec

حداقل زمان انتظار پیش از تلاش مجدد پس از یک تلاش ناموفق برای دریافت فهرست دامنه‌ها از یک tlsrpt-collectd.

--max_wait_domainlist=sec

حداکثر زمان انتظار پیش از تلاش مجدد پس از یک تلاش ناموفق برای دریافت فهرست دامنه‌ها از یک tlsrpt-collectd.

--interval_main_loop=sec

بیدار کردن حلقه اصلی در حالت بیکار حتی در صورتی که پس از sec ثانیه عدم فعالیت، هیچ وظیفه‌ای وجود نداشته باشد.

گزینه‌های اشکال‌زدایی و توسعه (Debug and development options)

--debug_db=n

کنترل اشکال‌زدایی پایگاه داده: مقدار 0 اشکال‌زدایی پایگاه داده را خاموش می‌کند، مقدار 1 ثبت عبارت‌های پایگاه داده را در لاگ فعال می‌سازد.

--debug_send_file_dest=dir

ذخیره گزارش‌ها در دایرکتوری dir علاوه بر ارسال آن‌ها از طریق ایمیل یا درخواست‌های HTTP POST. نمی‌توان هم‌زمان با --tlsrpt_record_map استفاده کرد!

--debug_send_mail_dest=path

بازنویسی مقصد ایمیل برای ارسال گزارش‌ها از طریق ایمیل. لطفاً توجه داشته باشید: با فعال بودن این گزینه، گزارش‌ها به مقصد درخواستی در رکورد DNS مربوط به TLSRPT ارسال نمی‌شوند، بلکه به این نشانی جایگزین فرستاده خواهند شد! این گزینه نباید در سیستم‌های عملیاتی (production) استفاده شود! نمی‌توان هم‌زمان با --mail_destination_map استفاده کرد!

--debug_send_http_dest=path

بازنویسی مقصد HTTP POST برای ارسال گزارش‌ها از طریق درخواست‌های HTTP POST. لطفاً توجه داشته باشید: با فعال بودن این گزینه، گزارش‌ها به مقصد درخواستی در رکورد DNS مربوط به TLSRPT ارسال نمی‌شوند، بلکه به این نشانی اینترنتی جایگزین فرستاده خواهند شد! این گزینه نباید در سیستم‌های عملیاتی (production) استفاده شود! نمی‌توان هم‌زمان با --http_upload_map استفاده کرد!

گزینه‌های عمومی (General options)

--config_file=filename

خواندن گزینه‌ها از بخش tlsrpt_reportd در پرونده پیکربندی با ساختار INI به نام filename. متغیرهای محیطی بر تنظیمات پرونده پیکربندی اولویت دارند و گزینه‌های خط فرمان بر هر دو تقدم دارند.

--help

چاپ پیام راهنما که تمامی گزینه‌ها را شرح می‌دهد.

--pidfilename=path

تعیین پرونده‌ای که شناسه فرآیند (PID) دیمن tlsrpt-reportd را نگه می‌دارد. یک رشته خالی مانع ایجاد پرونده PID می‌شود.

گزینه‌های ثبت وقایع (Logging options)

--logfilename=filename

استفاده از filename به عنوان پرونده ثبت لاگ.

--log_level=level

تنظیم سطح گزارش‌گیری لاگ روی level؛ مقادیر مجاز: debug، info، warn، error.

محیط (ENVIRONMENT)

تمامی گزینه‌های پیکربندی به جز --help و --config_file را می‌توان از طریق متغیرهای محیطی نیز تنظیم کرد. متغیر محیطی متناظر با هر گزینه پیکربندی، شامل پیشوند TLSRPT_REPORTD_ به همراه نام تنظیم پیکربندی با حروف بزرگ انگلیسی است. برای نمونه، گزینه --log_level را می‌توان با استفاده از متغیر محیطی TLSRPT_REPORTD_LOG_LEVEL پیکربندی کرد.

نگاشت مقصد (DESTINATION MAPPING)

گزینه‌های --tlsrpt_record_map، --http_upload_map و --mail_destination_map امکان نگاشت مقاصد گزارش استخراج‌شده از رکورد TLSRPT را بر اساس دامنه‌ای که گزارش برای آن ایجاد می‌شود فراهم می‌کنند.

تمام جداول نگاشت بر اساس قاعده «اولین تطابق برنده است» (first match wins) پردازش می‌شوند. پس از تطابق یک قانون، هیچ قانون دیگری بررسی و پردازش نخواهد شد.

گزینه --tlsrpt_record_map در ابتدا برای تبدیل کل مجموعه مقاصد به کار می‌رود. گزینه‌های --http_upload_map و --mail_destination_map امکان اعمال تغییرات بیشتر روی مقاصد گزارشی که با طرحواره‌های «mailto:» یا «https:» مطابقت دارند را فراهم می‌سازند و این گزینه‌ها خود مقصد گزارش را برای اعمال قانون بررسی می‌کنند، نه دامنه‌ای که گزارش برای آن ساخته شده است.

هر خط از جدول نگاشت دارای ساختار زیر است: match action [parameters]

بخش match به صورت «matchtype:pattern» است. انواع تطابق پشتیبانی‌شده عبارتند از: «domain:» و «regexp:».

پیشوند «domain:» را می‌توان حذف کرد؛ یعنی در صورت عدم تعیین نوع تطابق، شیوه تطابق «domain:» حالت پیش‌فرض است. یک تطابق «domain:» با بخش دامنه در یک نشانی «mailto:» در --mail_destination_map و با بخش دامنه در یک نشانی «https:» در --http_upload_map تطبیق داده می‌شود. تطابق «domain:» می‌تواند با یک نام دامنه کامل تطابق یابد یا اگر با یک «.» آغاز شود با تمامی زیردامنه‌ها تطبیق پیدا می‌کند. یک «.» منفرد با تمام نام‌های دامنه تطبیق دارد. علامت «.» در انتهای نام دامنه نادیده گرفته می‌شود.

نام دامنه «many.sub.domains.example.com» بدون نقطه در ابتدا، با «sub.domains.example.com» یا «sub.domains.example.com.» تطابق نمی‌یابد، اما با این عبارات تطابق دامنه مطابقت خواهد داشت:

•many.sub.domains.example.com.

•many.sub.domains.example.com

•.sub.domains.example.com.

•.sub.domains.example.com

•.domains.example.com.

•.domains.example.com

•.example.com.

•.example.com

•.com.

•.com

•.

یک تطابق به سبک «regexp:» در --tlsrpt_record_map با نام دامنه‌ای که گزارش برای آن ایجاد می‌شود تطبیق می‌یابد. یک تطابق به سبک «regexp:» در جداول نگاشت --http_upload_map و --mail_destination_map با کل رشته مقصد گزارش تطبیق داده می‌شود، نه فقط بخش دامنه استخراج‌شده.

بخش action می‌تواند یکی از موارد «ACCEPT»، «DISCARD»، «APPEND»، «REPLACE» و «REGEXP» باشد. عملیات «ACCEPT» مقاصد گزارش را همان‌گونه که هستند می‌پذیرد. عملیات «DISCARD» مجموعه‌ای خالی از مقاصد گزارش برمی‌گرداند و هیچ گزارشی ارسال نخواهد شد. عملیات «APPEND» مقاصد گزارش اضافی ارائه می‌دهد. عملیات «REPLACE» مقاصد گزارش را با مقاصد دیگری جایگزین می‌کند. عملیات «REGEXP» هر مقصد گزارش تطابق‌یافته را بر اساس دو پارامتر خود تبدیل می‌کند: یک عبارت باقاعده (regexp) منطبق و یک جایگزین (substitution).

عملیات‌های «APPEND»، «REPLACE» و «REGEXP» می‌توانند طرحواره‌های نشانی (URI schemes) دیگری را معرفی کنند. علاوه بر طرحواره‌های «mailto:» و «https:» تعریف‌شده در RFC 8460، دیمن tlsrpt-reportd طرحواره اضافی «directory:» را به عنوان دایرکتوری در سیستم فایل می‌شناسد که در آن گزارش‌ها برای بررسی و اشکال‌زدایی به صورت فایل ذخیره می‌شوند.

قوانین موجود در --mail_destination_map می‌توانند نشانی‌های «https:» و «directory:» را نیز به عنوان مقصد گزارش معرفی کنند. قوانین موجود در --http_upload_map نیز می‌توانند نشانی‌های «https:» و «directory:» را به عنوان مقصد گزارش معرفی کنند. هیچ پردازش دیگری روی این مقاصد انجام نمی‌شود؛ به این معنی که نشانی «https:» معرفی‌شده در --mail_destination_map از تبدیل‌های --http_upload_map عبور داده نمی‌شود و برعکس.

با این حال، نتایج حاصل از --tlsrpt_record_map که ابتدا پردازش می‌شود، حتی در صورتی که --tlsrpt_record_map مقاصد گزارش را تغییر داده باشد، از فیلتر تبدیل‌های --http_upload_map و --mail_destination_map عبور داده می‌شوند.

مثال‌ها (EXAMPLES)

دریافت داده از یک واکشی‌کننده محلی با پیکربندی استاندارد و از یک واکشی‌کننده محلی دیگر با فضای ذخیره‌سازی متفاوت:

tlsrpt-reportd --fetchers "tlsrpt-fetcher, tlsrpt-fetcher --storage sqlite:///tmp/test.sqlite"

دریافت داده از یک واکشی‌کننده محلی و یک واکشی‌کننده از راه دور:

tlsrpt-reportd --fetchers "tlsrpt-fetcher, ssh user@remote tlsrpt-fetcher"

وضعیت خروج (EXIT STATUS)

0

موفقیت‌آمیز.

1

شکست.

همچنین ببینید (SEE ALSO)

man:tlsrpt-collectd[1], man:tlsrpt-fetcher[1]

نویسنده (AUTHOR)

Boris Lohner