SIEVE-TEST(1) Dovecot SIEVE-TEST(1)

sieve-test - آزمون‌گر اسکریپت Sieve در Pigeonhole

sieve-test [options] script-file mail-file

دستور sieve-test بخشی از Pigeonhole (pigeonhole(7)) است که پشتیبانی از Sieve (RFC 5228) و ManageSieve (RFC 5804) را به Dovecot (dovecot(1)) اضافه می‌کند.

با استفاده از دستور sieve-test، می‌توان اجرای اسکریپت‌های Sieve را آزمایش کرد. این دستور اسکریپت را برای پیام مشخص‌شده ارزیابی کرده و مجموعه‌ای از کنش‌های Sieve را به دست می‌دهد. مگر در حالتی که گزینهٔ -e مشخص شده باشد، این دستور در عمل کنش‌ها را اجرا نمی‌کند؛ بدین معنا که پیام را در هیچ مکانی ذخیره یا بازفرستاد نمی‌کند. در عوض، فهرستی با جزئیات از کنش‌هایی که به‌طور معمول انجام می‌گرفت را چاپ می‌کند. توجه داشته باشید که حتی با مشخص بودن -e نیز هیچ پیامی به گیرندگان راه دور SMTP ارسال نمی‌شود. در عوض، پیام‌های خروجی همواره در stdout چاپ می‌شوند.

این ابزاری بسیار کاربردی برای اشکال‌زدایی اجرای اسکریپت‌های Sieve است. می‌توان از آن برای تایید رفتار مورد انتظار در اسکریپت‌های تازه‌نصب‌شده استفاده کرد، و همچنین اطلاعات دقیق‌تری را پیرامون مشکلات اجرای اسکریپت که توسط پلاگین Sieve گزارش می‌شوند، فراهم می‌آورد؛ برای نمونه از طریق ردگیری (tracing) اجرای دستورها و ارزیابی آزمون‌ها.

-a orig-recipient-address

نشانی اصلی گیرنده در پاکت نامه (envelope recipient address). این همان مقداری است که آزمون envelope در Sieve هنگام درخواست بخش "to" پاکت، با آن مقایسه خواهد کرد. برخی آزمون‌ها و کنش‌ها نیز از این نشانی به عنوان نشانی ایمیل مالک اسکریپت استفاده می‌کنند. اگر این گزینه نادیده گرفته شود، نشانی گیرنده از سرآیندهای پیام "Envelope-To:" یا "To:" دریافت می‌شود. اگر هیچ‌یک از این سرآیندها نیز وجود نداشته باشد، نشانی گیرنده به صورت پیش‌فرض ⟨recipient@example.com⟩ در نظر گرفته می‌شود.

-c config-file

مسیر پروندهٔ پیکربندی جایگزین Dovecot.

-C

کامپایل اجباری. به صورت پیش‌فرض، باینری کامپایل‌شده روی دیسک ذخیره می‌شود. هنگامی که این باینری در اجرای بعدی sieve-test پیدا شود و زمان تغییر آن تازه‌تر از پروندهٔ اسکریپت باشد، از آن استفاده شده و اسکریپت مجدداً کامپایل نمی‌شود. این گزینه اسکریپت را وادار به کامپایل می‌کند و در نتیجه هرگونه باینری موجود را نادیده می‌گیرد. برای اطلاعات بیشتر دربارهٔ کامپایل Sieve به sievec(1) مراجعه کنید.

-D

فعال‌سازی اشکال‌زدایی Sieve.

-d dump-file

باعث می‌شود نسخه‌ای از کُد تولیدشده (dump) در پروندهٔ مشخص‌شده نوشته شود. این نسخه دقیقاً مشابه خروجی تولیدشده توسط sieve-dump(1) است. استفاده از '-' به عنوان نام پرونده موجب نوشتن dump در stdout می‌شود.

-e

اجرای واقعی مجموعه کنش‌های حاصل از اجرای اسکریپت را فعال می‌کند. از پارامتر -o برای مشخص کردن mail_driver، mail_path و سایر تنظیمات ضروری ذخیره‌سازی استفاده کنید. این قابلیت اجازه می‌دهد تحویل واقعی پیام‌ها آزمایش شود. توجه داشته باشید که این کار هیچ پیامی را به گیرندگان SMTP راه دور مخابره نمی‌کند؛ چنین کنش‌هایی صرفاً پیام خروجی را در stdout چاپ می‌کنند.

-f envelope-sender

نشانی فرستنده در پاکت نامه (return path). این مقداری است که آزمون envelope در Sieve هنگام درخواست بخش "from" پاکت، با آن مقایسه خواهد کرد. همچنین پیام‌های پاسخ به این نشانی «ارسال» می‌شوند. اگر این گزینه نادیده گرفته شود، نشانی فرستنده از سرآیندهای پیام "Return-Path:"، "Sender:" یا "From:" بازیابی می‌شود. چنانچه هیچ‌یک از این سرآیندها نیز موجود نباشد، نشانی فرستنده در پاکت به صورت پیش‌فرض ⟨sender@example.com⟩ خواهد بود.

-m default-mailbox

صندوق پستی (mailbox) که کنش keep پیام را در آن ذخیره می‌کند. این مقدار به صورت پیش‌فرض "INBOX" است.

-o setting=value

تنظیم پیکربندی setting را از /etc/dovecot/dovecot.conf و از userdb با مقدار داده‌شده value بازنویسی (override) می‌کند. به منظور بازنویسی چندین تنظیم، می‌توان گزینهٔ -o را چندین بار مشخص کرد.

-r recipient-address

نشانی نهایی گیرنده در پاکت نامه. برخی آزمون‌ها و کنش‌ها از این نشانی به عنوان نشانی ایمیل مالک اسکریپت استفاده می‌کنند. برای مثال، این همان مقداری است که توسط کنش vacation برای بررسی مناسب بودن ارسال پاسخ استفاده می‌شود. اگر گزینهٔ -r نادیده گرفته شود، نشانی اصلی گیرنده در پاکت به‌جای آن استفاده خواهد شد (برای اطلاعات بیشتر به گزینهٔ -a مراجعه کنید).

-s script-file

اسکریپت‌های دیگری را برای اجرا پیش از اسکریپت اصلی مشخص می‌کند. مشخص کردن چندین آرگومان -s مجاز است و اسکریپت‌های مشخص‌شده به ترتیب تعیین‌شده در خط فرمان، به صورت متوالی اجرا می‌شوند.

-t trace-file

اشکال‌زدایی ردگیری زمان اجرا (runtime trace debugging) را فعال می‌کند. اشکال‌زدایی ردگیری دید دقیقی نسبت به عملیات انجام‌شده توسط اسکریپت Sieve ارائه می‌دهد. به بخش اشکال‌زدایی ردگیری زمان اجرا در زیر مراجعه کنید. اطلاعات ردگیری در پروندهٔ مشخص‌شده نوشته می‌شود. استفاده از '-' به عنوان نام پرونده موجب نوشتن داده‌های ردگیری در stdout خواهد شد.

-T trace-option

اشکال‌زدایی ردگیری زمان اجرا را که با گزینهٔ -t فعال می‌شود، پیکربندی می‌کند. به بخش اشکال‌زدایی ردگیری زمان اجرا در زیر مراجعه کنید.

-u user/mask

دستور command را تنها برای کاربر مشخص‌شده (user) اجرا می‌کند. همچنین امکان استفاده از نویسه‌های عام (wildcard) '*' و '?' نیز وجود دارد (مانند ‎-u *@example.org‎).

-x auth_info

مقدار auth_info شرایط بیشتری را برای دستور user مشخص می‌کند. رشتهٔ گزینهٔ auth_info باید به صورت یک جفت name = value ارائه شود. برای شرایط چندگانه، گزینهٔ -x می‌تواند چندین بار وارد شود.

نام‌های مجاز برای auth_info عبارتند از:

service

سرویسی که جستجوی userdb باید برای آن آزمایش شود. این مقدار می‌تواند نام سرویسی باشد که معمولاً در Dovecot استفاده می‌شود؛ برای نمونه: imap، pop3 یا smtp.

session

شناسهٔ نشست (session identifier).

lip

نشانی IP محلی (سرور) برای آزمایش.

rip

نشانی IP راه دور (کلاینت) برای آزمایش.

lport

پورت محلی، برای مثال 143

rport

پورت راه دور، برای مثال 24567

real_lip

نشانی IP محلی در این میزبان که کلاینت به آن متصل شده است.

real_rip

نشانی IP راه دوری که کلاینت از آن به این میزبان متصل شده است.

real_lport

پورت محلی در این میزبان که کلاینت به آن متصل شده است.

real_rport

پورت راه دوری که کلاینت از آن به این میزبان متصل شده است.

forward_<field>

فیلدی که باید به‌عنوان %{forward:field} به فرایند auth ارسال شود.

script-file

اسکریپت مورد نظر را برای (کامپایل و) اجرا مشخص می‌کند.

توجه داشته باشید که این ابزار به دنبال یک فایل باینری از پیش کامپایل‌شده با پسوند .svbin و با نام پایه (basename) و مسیری یکسان با اسکریپت مشخص‌شده می‌گردد. با استفاده از گزینهٔ -C می‌توانید این رفتار را غیرفعال کرده و اسکریپت را مجبور به کامپایل در یک فایل باینری جدید کنید.

mail-file

فایل حاوی پیام ایمیل را برای انجام آزمایش مشخص می‌کند.

با استفاده از گزینهٔ -t، می‌توان ابزار sieve-test را طوری پیکربندی کرد که اطلاعات دقیق ردیابی اجرای اسکریپت Sieve را در یک فایل یا خروجی استاندارد چاپ کند. برای نمونه، دستورهای مواجه‌شده، آزمایش‌های انجام‌شده و مقادیر تطبیق‌یافته قابل چاپ هستند.

ردیابی زمان اجرا را می‌توان با استفاده از گزینهٔ -T پیکربندی کرد که می‌تواند چندین بار مشخص شود. این گزینه را می‌توان به صورت زیر به کار برد:

-T level=...

تعیین سطح جزئیات اشکال‌زدایی ردیابی. یکی از مقادیر زیر

می‌تواند ارائه شود:

actions (پیش‌فرض) : تنها چاپ دستورهای کنشی اجراشده، مانند keep، fileinto، reject و redirect.

commands : چاپ هر دستور اجراشده، به استثنای دستورهای آزمایش (test).

tests : چاپ تمام دستورهای اجراشده و آزمایش‌های انجام‌گرفته.

matching : چاپ تمام دستورهای اجراشده، آزمایش‌های انجام‌گرفته و مقادیر تطبیق‌یافته در آن آزمایش‌ها.

-T debug

پیام‌های اشکال‌زدایی را نیز چاپ می‌کند. این مورد معمولاً فقط برای توسعه‌دهندگان مفید است و احتمالاً خروجی درهم‌ریخته‌ای تولید خواهد کرد.

-T addresses

نشانی‌های بایت‌کد را برای خروجی ردیابی فعلی چاپ می‌کند. به طور معمول، تنها موقعیت فعلی سورس‌کد Sieve (شماره خط) چاپ می‌شود. نشانی‌های بایت‌کد برابر با نشانی‌های فهرست‌شده در تخلیهٔ باینری (binary dump) تولیدشده با گزینهٔ -d یا دستور sieve-dump(1) هستند.

برای بهبود اشکال‌زدایی اسکریپت، این پیاده‌سازی Sieve از یک افزونهٔ سفارشی زبان Sieve به نام 'vnd.dovecot.debug' پشتیبانی می‌کند. این افزونه دستور debug_log را اضافه می‌کند که امکان ثبت گزارش پیام‌های اشکال‌زدایی را فراهم می‌سازد.

مثال:

require "vnd.dovecot.debug";
if header :contains "subject" "hello" {
  debug_log "Subject header contains hello!";
}

ابزارهایی مانند sieve-test، sievec(1) و sieve-dump(1) پشتیبانی از افزونهٔ vnd.dovecot.debug را به طور پیش‌فرض فعال دارند و نیازی به فعال‌سازی آن نیست و همچنین غیرفعال کردن دسترسی به این افزونهٔ اشکال‌زدایی با گزینهٔ -x امکان‌پذیر نمی‌باشد. در این حالت، پیام‌های ثبت‌شده در stdout نوشته می‌شوند.

در مقابل، برای افزایهٔ واقعی Sieve مربوط به Dovecot LDA (dovecot-lda(1))، افزونهٔ vnd.dovecot.debug باید صریحاً با استفاده از تنظیمات sieve_extensions یا sieve_global_extensions فعال شود. سپس پیام‌ها در فایل گزارش خصوصی اسکریپت کاربر ثبت می‌شوند. در صورت استفاده در یک اسکریپت سراسری، پیام‌ها از طریق سازوکار پیش‌فرض ثبت گزارش Dovecot لاگ می‌شوند.

ابزار sieve-test با یکی از مقادیر زیر خارج خواهد شد:

0

اجرا موفقیت‌آمیز بود. (EX_OK، EXIT_SUCCESS)

1

عملیات شکست خورد. این مقدار تقریباً برای تمامی خرابی‌ها بازگردانده می‌شود. (EXIT_FAILURE)

64

پارامتر نامعتبر داده شده است. (EX_USAGE)

/etc/dovecot/dovecot.conf

فایل پیکربندی اصلی Dovecot.

/etc/dovecot/conf.d/90-sieve.conf

تنظیمات مفسر Sieve (گنجانده‌شده از فایل پیکربندی اصلی Dovecot)

گزارش باگ‌ها، شامل خروجی doveconf -n را به فهرست پستی Dovecot به نشانی ⟨dovecot@dovecot.org⟩ ارسال کنید. اطلاعات درباره گزارش باگ‌ها در این نشانی در دسترس است: ⟨https://dovecot.org/bugreport.html⟩

dovecot(1), dovecot-lda(1), sieve-dump(1), sieve-filter(1), sievec(1), pigeonhole(7)

May 2026 e5ac02a