نام (NAME)

slapo-retcode - لایه روکش شبیهسازی کدهای برگشتی خطا برای slapd

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

/etc/openldap/slapd.conf

توضیحات (DESCRIPTION)

روکش retcode برای slapd(8) جهت آزمایش رفتار کلاینت‌ها هنگام وقوع پاسخ‌های نادرست و/یا غیرمعمول تولیدشده توسط سرور مانند کدهای خطا، ارجاعات (referrals)، زمان‌های پاسخ‌دهی بیش از حد و موارد مشابه مفید است.

پاسخ‌های خطا بر اساس راهبردهای متفاوتی تولید می‌شوند.

در حالت اول، تمام عملیاتی که زیردرخت پیکربندی‌پذیر خاصی را هدف قرار می‌دهند باعث می‌شوند شیء مرتبط با DN درخواست جستجو شده و از نظر داده‌های کد بازگشتی بررسی شود: یک کد پاسخ، به همراه یک پیام متنی اختیاری، یک تأخیر پیکربندی‌پذیر اختیاری، یک فیلد DN تطبیق‌یافته اختیاری و هنگامی که کد پاسخ «referral» است، (فهرستی از) ارجاع(ها).

کدهای پاسخ شناخته‌شده از اسناد استاندارد در retcode.conf ارائه شده‌اند که می‌توان آن را پس از نمونه‌سازی روکش، پیوست (include) کرد.

در حالت دوم، اشیای کلاس‌های مشتق‌شده از errAbsObject، مانند errObject یا errAuxObject، هنگامی که به عنوان پاسخ‌های میانی یک درخواست جستجو بازگردانده می‌شوند، به پاسخی که توسط محتوای آن‌ها دیکته شده تغییر می‌یابند.

حالت سوم باعث می‌شود اشیاء از پایگاه داده زیرین جستجو شوند تا مشخص شود آیا کلاس آن‌ها از errAbsObject ارث‌بری می‌کند یا خیر؛ در این صورت، از محتوای آن‌ها برای محاسبه پاسخ مربوطه استفاده می‌شود.

این رفتار با استفاده از کنترل manageDSAit (RFC 3296) غیرفعال می‌شود؛ در این صورت، شیء حاصل (چه در دایرکتوری موجود باشد، چه به صورت پویا توسط روکش تولید شده باشد، یا در درخواست گنجانده شده باشد) طبق روال معمول مدیریت می‌شود.

دستورالعمل‌های پیکربندی ویژه روکش retcode باید دارای پیشوند retcode- باشند تا از تداخل با دستورالعمل‌های خاص پایگاه داده زیرین یا سایر روکش‌های روی هم چیده‌شده (stacked) جلوگیری شود. دستورالعمل‌های خاص زیر می‌توانند برای پیکربندی روکش retcode استفاده شوند:

retcode-parent <DN>: این دستورالعمل DN والد را مشخص می‌کند که مدخل‌های تولیدشده به‌صورت پویا در آن قرار می‌گیرند. اگر تعریف نشده باشد، از پسوند پایگاه داده استفاده می‌شود.

retcode-item <RDN> <errCode> [op=<oplist>] [text=<message>] [ref=<referral>] [sleeptime=<sec>] [matched=<DN>] [unsolicited=<OID>[:<data>]] [flags=[pre|post-]disconnect[,...]]

یک مدخل تولیدشده به‌صورت پویا که زیر retcode-parent قرار دارد. مقدار errCode شماره کد پاسخ است؛ می‌تواند در هر قالبی که توسط strtol(3) پشتیبانی می‌شود باشد. پارامتر اختیاری oplist فهرستی از عملیات است که باعث تولید کد پاسخ می‌شوند؛ در صورت عدم وجود، تمام عملیات تحت تأثیر قرار می‌گیرند. فیلد matched همان DN تطبیق‌یافته‌ای است که همراه با خطا بازگردانده می‌شود، در حالی که فیلد text یک پیام تشخیصی اختیاری است. فیلد ref تنها برای کد پاسخ referral مجاز است. فیلد sleeptime باعث می‌شود slapd(8) پیش از ادامه عملیات، به تعداد ثانیه‌های مشخص‌شده به حالت خواب برود (مکث کند). فیلد unsolicited می‌تواند برای بازگرداندن یک پیام پاسخ ناخواسته طبق RFC 4511 استفاده شود؛ اگر OID برابر با «0» نباشد، یک پاسخ گسترش‌یافته به همراه داده‌های اختیاری data پیوست‌شده تولید می‌شود. اگر flags شامل disconnect یا pre-disconnect باشد، slapd(8) به صورت ناگهانی و بدون اطلاع قبلی اتصال را قطع می‌کند؛ مقدار post-disconnect باعث قطع اتصال بلافاصله پس از ارسال پاسخ مناسب می‌شود.

retcode-indir: بهره‌برداری از errAbsObject ذخیره‌شده در دایرکتوری را فعال می‌کند. ممکن است منجر به بار پردازشی اضافی غیرضروری زیادی شود.
retcode-sleep [-]<n>: مدت زمان خواب بر حسب ثانیه را مشخص می‌کند که پیش از رسیدگی واقعی به هر عملیاتی سپری می‌شود. اگر منفی باشد، یک زمان تصادفی بین ۰ و مقدار قدر مطلق آرگومان استفاده می‌شود.

طرح‌واره (SCHEMA)

روکش retcode از طرح‌واره «کد بازگشتی» که در اینجا شرح داده شده استفاده می‌کند. این طرح‌واره به‌طور خاص برای استفاده با این روکش طراحی شده و برای کاربردهای دیگر در نظر گرفته نشده است. همچنین باید توجه داشت که طرح‌واره شرح داده شده در اینجا در حال توسعه است و بنابراین ممکن است بدون اطلاع قبلی تغییر کند. طرح‌واره به‌طور خودکار توسط روکش بارگذاری می‌شود.

این طرح‌واره شامل تعدادی کلاس شیء و انواع مشخصه‌های مرتبط است که در زیر شرح داده شده‌اند:

کد خطا:

( 1.3.6.1.4.1.4203.666.11.4.1.1
NAME ( 'errCode' )
DESC 'LDAP error code'
EQUALITY integerMatch
ORDERING integerOrderingMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
SINGLE-VALUE )

عملیاتی که محرک کد پاسخ هستند:

( 1.3.6.1.4.1.4203.666.11.4.1.2
NAME ( 'errOp' )
DESC 'Operations the errObject applies to'
EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )

پیام متنی:

( 1.3.6.1.4.1.4203.666.11.4.1.3
NAME ( 'errText' )
DESC 'LDAP error textual description'
EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
SINGLE-VALUE )

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

( 1.3.6.1.4.1.4203.666.11.4.1.4
NAME ( 'errSleepTime' )
DESC 'Time to wait before returning the error'
EQUALITY integerMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
SINGLE-VALUE )

مقدار DN تطبیق‌یافته بازگردانده‌شده به کلاینت:

( 1.3.6.1.4.1.4203.666.11.4.1.5
NAME ( 'errMatchedDN' )
DESC 'Value to be returned as matched DN'
EQUALITY distinguishedNameMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
SINGLE-VALUE )

شناسه OID برای بازگرداندن به عنوان OID پاسخ گسترش‌یافته در پاسخ‌های ناخواسته RFC 4511 (مقدار «0» یک پاسخ عادی با msgid تنظیم‌شده روی 0 تولید می‌کند):

( 1.3.6.1.4.1.4203.666.11.4.1.6
NAME ( 'errUnsolicitedOID' )
DESC 'OID to be returned within unsolicited response'
EQUALITY objectIdentifierMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.38
SINGLE-VALUE )

رشته هشت‌بیتی (octet string) برای بازگرداندن به عنوان داده‌های پاسخ گسترش‌یافته در پاسخ ناخواسته RFC 4511:

( 1.3.6.1.4.1.4203.666.11.4.1.7
NAME ( 'errUnsolicitedData' )
DESC 'Data to be returned within unsolicited response'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
SINGLE-VALUE )

در صورت TRUE، slapd(8) بدون اطلاع قبلی به صورت ناگهانی اتصال را قطع می‌کند؛ در صورت FALSE، پس از ارسال پاسخ مقتضی، اتصال را قطع می‌نماید:

( 1.3.6.1.4.1.4203.666.11.4.1.8
NAME ( 'errDisconnect' )
DESC 'Disconnect without notice'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
SINGLE-VALUE )

کلاس انتزاعی (abstract class) که روکش را فعال می‌کند:

( 1.3.6.1.4.1.4203.666.11.4.3.0
NAME ( 'errAbsObject' )
SUP top ABSTRACT
MUST ( errCode )
MAY ( cn $ description $ errOp $ errText $ errSleepTime
$ errMatchedDN ) )

کلاس شیء ساختاری مستقل برای داده‌های اختصاصی ایجادشده:

( 1.3.6.1.4.1.4203.666.11.4.3.1
NAME ( 'errObject' )
SUP errAbsObject STRUCTURAL )

کلاس شیء کمکی برای تغییر رفتار اشیاء موجود:

( 1.3.6.1.4.1.4203.666.11.4.3.2
NAME ( 'errAuxObject' )
SUP errAbsObject AUXILIARY )

مثال‌ها (EXAMPLE)

overlay         retcode
retcode-parent  "ou=RetCodes,dc=example,dc=com"
# فایل retcode.conf در tests/data/ از درخت کد منبع یافت می‌شود
include         ./retcode.conf
# ۱۰ ثانیه صبر کرده، سپس وضعیت موفقیت (0x00) را بازمی‌گرداند
retcode-item    "cn=Success after 10 seconds" 0x00 sleeptime=10
# ۱۰ ثانیه صبر کرده، سپس وضعیت timelimitExceeded (0x03) را بازمی‌گرداند
retcode-item    "cn=Timelimit after 10 seconds" 0x03 sleeptime=10

فایل‌ها (FILES)

/etc/openldap/slapd.conf: فایل پیکربندی پیش‌فرض slapd

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

slapd.conf(5), slapd-config(5), slapd(8).

روکش slapo-retcode(5) از پیکربندی پویا از طریق back-config پشتیبانی می‌کند.

قدردانی (ACKNOWLEDGEMENTS)

این ماژول در سال ۲۰۰۵ توسط Pierangelo Masarati برای SysNet s.n.c نوشته شده است.