." Automatically generated from the sudo_plugin.mdoc.in file. Do not edit. ." ." SPDX-License-Identifier: ISC ." ." Copyright (c) 2009-2024 Todd C. Miller ." ." Permission to use, copy, modify, and distribute this software for any ." purpose with or without fee is hereby granted, provided that the above ." copyright notice and this permission notice appear in all copies. ." ." THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES ." WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF ." MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ." ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES ." WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ." ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF ." OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ." .Dd August 14, 2024 .Dt SUDO_PLUGIN 5 .Os Sudo 1.9.17p2 .Sh "نام (NAME)" .Nm sudo_plugin .Nd رابط افزونههای sudo .Sh "توضیحات (DESCRIPTION)" از نسخه ۱.۸ به بعد، .Nm sudo از یک رابط برنامه‌نویسی (API) افزونه برای سیاست‌گذاری (policy) و ثبت نشست‌ها (session logging) پشتیبانی می‌کند. افزونه‌ها می‌توانند به‌صورت اشیاء اشتراکی پویا (dynamic shared objects - حالت پیش‌فرض در سیستم‌هایی که از آن‌ها پشتیبانی می‌کنند) کامپایل شوند، یا به‌صورت ایستا (statically) درون خود باینری .Nm sudo کامپایل گردند. به‌طور پیش‌فرض، افزونه .Nm sudoers قابلیت‌های بازرسی (audit)، سیاست‌گذاری امنیتی و ثبت ورودی/خروجی (I/O) را فراهم می‌کند. از طریق API افزونه، .Nm sudo می‌تواند برای استفاده از افزونه‌های جایگزینِ ارائه‌شده توسط اشخاص ثالث پیکربندی شود. افزونه‌های مورد استفاده در فایل .Xr sudo.conf 5 مشخص می‌شوند. .Pp این API با شماره‌های نسخه اصلی (major) و فرعی (minor) نسخه‌گذاری می‌شود. با اعمال تغییرات افزایشی، شماره نسخه فرعی افزایش می‌یابد. با اعمال تغییرات ناسازگار، شماره نسخه اصلی افزایش می‌یابد. یک افزونه باید نسخه‌ای که به آن ارسال شده است را بررسی کند و مطمئن شود که نسخه اصلی مطابقت دارد. .Pp رابط API افزونه توسط فایل سرآیند .In sudo_plugin.h تعریف شده است. .Ss رابط API افزونه سیاست‌گذاری (Policy plugin API) یک افزونه سیاست‌گذاری باید یک .Vt struct policy_plugin را در دامنه سراسری (global scope) اعلان کرده و مقداردهی کند. این ساختار شامل اشاره‌گرهایی به توابعی است که بررسی‌های سیاست‌گذاری .Nm sudo را پیاده‌سازی می‌کنند. نام نماد (symbol) باید در .Xr sudo.conf 5 همراه با مسیری به افزونه مشخص شود تا .Nm sudo بتواند آن را بارگذاری کند. .Bd -literal struct policy_plugin { #define SUDO_POLICY_PLUGIN 1 unsigned int type; /* always SUDO_POLICY_PLUGIN */ unsigned int version; /* always SUDO_API_VERSION */ int (*open)(unsigned int version, sudo_conv_t conversation, sudo_printf_t sudo_plugin_printf, char * const settings[], char * const user_info[], char * const user_env[], char * const plugin_options[], const char **errstr); void (*close)(int exit_status, int error); int (*show_version)(int verbose); int (*check_policy)(int argc, char * const argv[], char *env_add[], char **command_info[], char **argv_out[], char **user_env_out[], const char **errstr); int (*list)(int argc, char * const argv[], int verbose, const char *user, const char **errstr); int (*validate)(const char **errstr); void (*invalidate)(int rmcred); int (*init_session)(struct passwd *pwd, char **user_env[], const char **errstr); void (*register_hooks)(int version, int (*register_hook)(struct sudo_hook *hook)); void (*deregister_hooks)(int version, int (*deregister_hook)(struct sudo_hook *hook)); struct sudo_plugin_event * (*event_alloc)(void); }; .Ed .Pp یک .Vt struct policy_plugin دارای فیلدهای زیر است: .Bl -tag -width 4n .It Fa type فیلد .Fa type همیشه باید روی SUDO_POLICY_PLUGIN تنظیم شود. .It Fa version فیلد .Fa version باید روی .Dv SUDO_API_VERSION تنظیم شود. .Pp این به .Nm sudo اجازه می‌دهد تا نسخه API که افزونه بر اساس آن ساخته شده است را تعیین کند. .It Fa open .Bd -literal -compact int (*open)(unsigned int version, sudo_conv_t conversation, sudo_printf_t sudo_plugin_printf, char * const settings[], char * const user_info[], char * const user_env[], char * const plugin_options[], const char **errstr); .Ed .Pp در صورت موفقیت مقدار ۱، در صورت شکست ۰، در صورت بروز خطای عمومی \-۱، و در صورت خطای نحوه استفاده (usage error) مقدار \-۲ را برمی‌گرداند. در حالت آخر، .Nm sudo پیش از خروج پیام نحوه استفاده را چاپ خواهد کرد. اگر خطایی رخ دهد، افزونه می‌تواند به صورت اختیاری تابع .Fn conversation یا .Fn sudo_plugin_printf را با .Dv SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری را به کاربر نمایش دهد. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa version نسخه‌ای که توسط .Nm sudo ارسال می‌شود، به افزونه امکان می‌دهد شماره نسخه اصلی و فرعی API افزونه که توسط .Nm sudo پشتیبانی می‌شود را تعیین کند. .It Fa conversation اشاره‌گری به تابع .Fn conversation که می‌تواند توسط افزونه برای تعامل با کاربر استفاده شود (برای جزئیات به .Sx Conversation API مراجعه کنید). در صورت موفقیت ۰ و در صورت شکست \-۱ برمی‌گرداند. .It Fa sudo_plugin_printf اشاره‌گری به یک تابع به سبک .Fn printf که می‌تواند برای نمایش پیام‌های اطلاعاتی یا خطا استفاده شود (برای جزئیات به .Sx Conversation API مراجعه کنید). در صورت موفقیت تعداد نویسه‌های چاپ‌شده و در صورت شکست \-۱ برمی‌گرداند. .It Fa settings یک بردار از تنظیمات ارائه‌شده توسط کاربر برای .Nm sudo به صورت رشته‌های .Dq name=value است. این بردار با یک اشاره‌گر .Dv NULL خاتمه می‌یابد. این تنظیمات مربوط به گزینه‌هایی است که کاربر هنگام اجرای .Nm sudo مشخص کرده است. بنابراین، آن‌ها تنها زمانی وجود خواهند داشت که گزینه متناظر در خط فرمان مشخص شده باشد. .Pp هنگام تجزیه .Fa settings ، افزونه باید آن را بر اساس .Sy اولین علامت مساوی .Pq Ql = تقسیم کند، زیرا فیلد .Em name هرگز شامل مساوی نخواهد بود، اما مقدار .Em value ممکن است شامل آن باشد. .Pp مقادیر زیر ممکن است توسط .Nm sudo تنظیم شوند: .Bl -tag -width 4n .It bsdauth_type=string نوع احراز هویت، در صورت مشخص شدن با گزینه .Fl a ، جهت استفاده در سیستم‌هایی که از احراز هویت .Bx پشتیبانی می‌کنند. .It closefrom=number در صورت مشخص شدن، کاربر از طریق گزینه .Fl C درخواست کرده است که .Nm sudo تمام توصیف‌کننده‌های فایل (file descriptors) با مقدار .Em number یا بالاتر را ببندد. افزونه می‌تواند به صورت اختیاری این مقدار یا مقدار دیگری را در لیست .Fa command_info بازگرداند. .It cmnd_chroot=string دایرکتوری ریشه (به .Xr chroot 2 مراجعه کنید) برای اجرای دستور در آن، همان‌طور که توسط کاربر از طریق گزینه .Fl R مشخص شده است. افزونه ممکن است توانایی کاربر برای تعیین یک دایرکتوری ریشه جدید را نادیده گرفته یا محدود کند. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است. .It cmnd_cwd=string دایرکتوری کاری برای اجرای دستور در آن، همان‌طور که توسط کاربر از طریق گزینه .Fl D مشخص شده است. افزونه ممکن است توانایی کاربر برای تعیین یک دایرکتوری کاری جدید را نادیده گرفته یا محدود کند. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است. .It debug_flags=string نام مسیر فایل اشکال‌زدایی به همراه یک فاصله و یک لیست جداشده با کاما از فلگ‌های اشکال‌زدایی که متناظر با مدخل .Em Debug افزونه در .Xr sudo.conf 5 است (در صورت وجود). فلگ‌ها دقیقاً همان‌طور که در .Xr sudo.conf 5 آمده‌اند به افزونه ارسال می‌شوند. نحو مورد استفاده توسط .Nm sudo و افزونه .Nm sudoers به صورت .Em subsystem Ns @ Ns Em priority است، اما یک افزونه تا زمانی که از کاما .Pq Ql ,\& استفاده نکند، در انتخاب قالبی متفاوت آزاد است. پیش از .Nm sudo نسخه 1.8.12، راهی برای تعیین .Em debug_flags مخصوص افزونه وجود نداشت، بنابراین مقدار آن همیشه همان مقداری بود که توسط بخش فرانت‌اند .Nm sudo استفاده می‌شد و شامل نام مسیر نبود، بلکه تنها خود فلگ‌ها را دربرداشت. از نسخه ۱.۷ رابط افزونه، .Nm sudo تنها در صورتی .Em debug_flags را ارسال می‌کند که .Xr sudo.conf 5 شامل یک مدخل .Em Debug مخصوص آن افزونه باشد. .It ignore_ticket=bool اگر کاربر گزینه .Fl k را همراه با یک دستور مشخص کرده باشد، روی true تنظیم می‌شود و نشان می‌دهد که کاربر مایل است از هرگونه اعتبارنامه‌های احراز هویت ذخیره‌شده (cached) چشم‌پوشی کند. .Em implied_shell به true. این به .Nm sudo بدون هیچ آرگومانی امکان می‌دهد تا به روشی مشابه با .Xr su 1 مورد استفاده قرار گیرد. اگر افزونه از این شیوه استفاده پشتیبانی نکند، می‌تواند مقدار \-۲ را از تابع .Fn check_policy برگرداند، که باعث می‌شود .Nm sudo پیام نحوه استفاده را چاپ کرده و خارج شود. .It implied_shell=bool اگر کاربر برنامه‌ای را در خط فرمان مشخص نکند، .Nm sudo مسیر پوسته کاربر را به افزونه ارسال کرده و .Em implied_shell را تنظیم می‌کند. .It intercept_ptrace=bool مشخص می‌کند که آیا سیستم از حالت رهگیری (intercept mode) با استفاده از .Xr ptrace 2 پشتیبانی می‌کند یا خیر. این مورد در حال حاضر تنها برای سیستم‌های لینوکسی صادق است که از فیلتر کردن .Xr seccomp 2 و عمل .Dq trap پشتیبانی می‌کنند. سایر سیستم‌ها برای پیاده‌سازی رهگیری از یک شیء اشتراکی پویا استفاده خواهند کرد. تنها از نسخه ۱.۱۹ رابط API به بعد در دسترس است. .It intercept_setid=bool مشخص می‌کند که آیا سیستم از اجرای باینری‌های set-user-ID و set-group-ID در حالت رهگیری پشتیبانی می‌کند یا خیر. این مورد در حال حاضر تنها برای سیستم‌های لینوکسی صادق است که از فیلتر کردن .Xr seccomp 2 و عمل .Dq trap پشتیبانی می‌کنند. در سیستم‌هایی که برای پیاده‌سازی رهگیری از یک شیء اشتراکی پویا استفاده می‌کنند، پیونددهنده پویا (ld.so یا معادل آن) پیش‌بارگذاری اشیاء اشتراکی را هنگام اجرای باینری‌های set-user-ID یا set-group-ID غیرفعال می‌کند. این امر حالت رهگیری را برای آن برنامه و هر برنامه دیگری که توسط آن اجرا می‌شود غیرفعال خواهد کرد. افزونه سیاست‌گذاری می‌تواند برای جلوگیری از این وضعیت، از اجرای یک باینری set-user-ID یا set-group-ID در حالت رهگیری خودداری کند. تنها از نسخه ۱.۱۹ رابط API به بعد در دسترس است. .It login_class=string کلاس ورود .Bx جهت استفاده هنگام تنظیم محدودیت‌های منابع و مقدار nice، در صورت مشخص شدن با گزینه .Fl c . .It login_shell=bool اگر کاربر گزینه .Fl i را مشخص کرده باشد روی true تنظیم می‌شود و نشان می‌دهد که کاربر مایل است یک پوسته ورود (login shell) را اجرا کند. .It max_groups=int حداکثر تعداد گروه‌هایی که یک کاربر می‌تواند عضو آن‌ها باشد. این مقدار تنها در صورتی وجود خواهد داشت که تنظیم متناظر در .Xr sudo.conf 5 موجود باشد. .It network_addrs=list یک لیست جداشده با فاصله از آدرس‌های شبکه IP و ماسک‌های شبکه به فرم .Dq addr/netmask ، به عنوان مثال، .Dq 192.168.1.2/255.255.255.0 . جفت‌های آدرس و ماسک شبکه بسته به پشتیبانی سیستم‌عامل می‌توانند IPv4 یا IPv6 باشند. اگر آدرس شامل دونقطه .Pq Ql :\& باشد، یک آدرس IPv6 است، در غیر این صورت IPv4 است. .It noninteractive=bool اگر کاربر گزینه .Fl n را مشخص کرده باشد روی true تنظیم می‌شود و نشان می‌دهد که .Nm sudo باید در حالت غیرتعاملی عمل کند. اگر تعامل با کاربر مورد نیاز باشد، افزونه ممکن است فرمانی را که در حالت غیرتعاملی اجرا شده است رد کند. .It plugin_dir=string پوشه پیش‌فرض افزونه‌ها که توسط بخش فرانت‌اند .Nm sudo استفاده می‌شود. این دایرکتوری پیش‌فرضی است که در زمان کامپایل تنظیم شده و ممکن است با دایرکتوری که افزونه در حال اجرا از آن بارگذاری شده است، مطابقت نداشته باشد. این مقدار ممکن است توسط افزونه برای یافتن فایل‌های پشتیبان استفاده شود. .It plugin_path=string نام مسیر افزونه‌ای که توسط فرانت‌اند .Nm sudo بارگذاری شده است. این نام مسیر به صورت کامل (fully-qualified) خواهد بود، مگر اینکه افزونه به صورت ایستا درون .Nm sudo کامپایل شده باشد. .It preserve_environment=bool اگر کاربر گزینه .Fl E را مشخص کرده باشد روی true تنظیم می‌شود و نشان می‌دهد که کاربر مایل به حفظ محیط متغیرها است. .It preserve_groups=bool اگر کاربر گزینه .Fl P را مشخص کرده باشد روی true تنظیم می‌شود و نشان می‌دهد که کاربر مایل است بردار گروه‌ها را به جای تنظیم بر اساس کاربر هدف (runas user)، حفظ کند. .It progname=string نام دستوری که sudo تحت عنوان آن اجرا شده است، معمولاً .Dq sudo یا .Dq sudoedit . .It prompt=string اعلانی که هنگام درخواست گذرواژه باید استفاده شود، در صورت مشخص شدن از طریق گزینه .Fl p . .It remote_host=string نام میزبان راه دور برای اجرای دستور روی آن، در صورت مشخص شدن از طریق گزینه .Fl h . پشتیبانی از اجرای دستور روی میزبان راه دور به گونه‌ای طراحی شده که از طریق یک برنامه کمکی که به جای دستور تعیین‌شده توسط کاربر اجرا می‌شود، پیاده‌سازی گردد. فرانت‌اند .Nm sudo تنها قادر به اجرای دستورات روی میزبان محلی است. تنها از نسخه ۱.۴ رابط API به بعد در دسترس است. .It run_shell=bool اگر کاربر گزینه .Fl s را مشخص کرده باشد روی true تنظیم می‌شود و نشان می‌دهد که کاربر مایل به اجرای یک پوسته است. .It runas_group=string نام گروه یا شناسه گروه (group-ID) برای اجرای دستور با آن، در صورت مشخص شدن از طریق گزینه .Fl g . .It runas_user=string نام کاربر یا شناسه کاربر (user-ID) برای اجرای دستور با آن، در صورت مشخص شدن از طریق گزینه .Fl u . .It selinux_role=string نقش SELinux مورد استفاده هنگام اجرای دستور، در صورت مشخص شدن با گزینه .Fl r . .It selinux_type=string نوع SELinux مورد استفاده هنگام اجرای دستور، در صورت مشخص شدن با گزینه .Fl t . .It set_home=bool اگر کاربر گزینه .Fl H را مشخص کرده باشد روی true تنظیم می‌شود. در صورت true بودن، متغیر محیطی .Ev HOME روی پوشه خانگی کاربر هدف تنظیم می‌شود. .It sudoedit=bool هنگامی که گزینه .Fl e مشخص شده باشد یا دستور به صورت .Nm sudoedit فراخوانی گردد، روی true تنظیم می‌شود. افزونه باید یک ویرایشگر را در .Fa argv در تابع .Fn check_policy جایگزین کند، یا در صورتی که افزونه از .Em sudoedit پشتیبانی نکند مقدار \-۲ را همراه با خطای نحوه استفاده بازگرداند. برای اطلاعات بیشتر، بخش .Fn check_policy را ببینید. .It timeout=string مهلت زمانی (timeout) دستور که توسط کاربر از طریق گزینه .Fl T مشخص شده است. همه افزونه‌ها از مهلت زمانی دستور پشتیبانی نمی‌کنند و توانایی کاربر در تعیین مهلت زمانی ممکن است توسط سیاست‌گذاری محدود شده باشد. قالب رشته مهلت زمانی وابسته به هر افزونه است. .It update_ticket=bool اگر کاربر گزینه .Fl N را مشخص کرده باشد روی false تنظیم می‌شود و نشان می‌دهد که کاربر می‌خواهد از به‌روزرسانی هرگونه اعتبارنامه احراز هویت ذخیره‌شده خودداری کند. تنها از نسخه ۱.۲۰ رابط API به بعد در دسترس است. .El .Pp ممکن است تنظیمات بیشتری در آینده اضافه شوند، بنابراین افزونه باید تنظیماتی را که نمی‌شناسد، بدون خطا نادیده بگیرد. .It Fa user_info برداری از اطلاعات مربوط به کاربری که دستور را اجرا می‌کند در قالب رشته‌های .Dq name=value است. این بردار با یک اشاره‌گر .Dv NULL خاتمه می‌یابد. .Pp هنگام تجزیه .Fa user_info ، افزونه باید آن را بر اساس .Sy اولین علامت مساوی .Pq Ql = تقسیم کند، زیرا فیلد .Em name هرگز شامل مساوی نخواهد بود، اما مقدار .Em value ممکن است شامل آن باشد. .Pp مقادیر زیر ممکن است توسط .Nm sudo تنظیم شوند: .Bl -tag -width 4n .It cols=int تعداد ستون‌هایی که ترمینال کاربر پشتیبانی می‌کند. اگر هیچ دستگاه ترمینالی در دسترس نباشد، مقدار پیش‌فرض ۸۰ استفاده می‌شود. .It cwd=string دایرکتوری کاری فعلی کاربر. .It egid=gid_t شناسه گروه موثر (effective group-ID) کاربری که .Nm sudo را فراخوانی کرده است. .It euid=uid_t شناسه کاربر موثر (effective user-ID) کاربری که .Nm sudo را فراخوانی کرده است. .It gid=gid_t شناسه گروه واقعی (real group-ID) کاربری که .Nm sudo را فراخوانی کرده است. .It groups=list لیست گروه‌های تکمیلی کاربر در قالب رشته‌ای از شناسه‌های گروه جداشده با کاما. .It host=string نام میزبان (hostname) ماشین محلی که توسط فراخوانی سیستمی .Xr gethostname 2 بازگردانده شده است. .It lines=int تعداد خطوطی که ترمینال کاربر پشتیبانی می‌کند. اگر هیچ دستگاه ترمینالی در دسترس نباشد، مقدار پیش‌فرض ۲۴ استفاده می‌شود. .It pgid=int شناسه گروه فرآیندی که فرآیند در حال اجرای .Nm sudo عضو آن است. تنها از نسخه ۱.۲ رابط API به بعد در دسترس است. .It pid=int شناسه فرآیند (PID) مربوط به فرآیند در حال اجرای .Nm sudo . تنها از نسخه ۱.۲ رابط API به بعد در دسترس است. .It ppid=int شناسه فرآیند والد (PPID) فرآیند در حال اجرای .Nm sudo . تنها از نسخه ۱.۲ رابط API به بعد در دسترس است. .It rlimit_as=soft,hard حداکثر اندازه‌ای که فضای آدرس‌دهی فرآیند می‌تواند رشد کند (به بایت)، در صورت پشتیبانی سیستم‌عامل. حدود نرم (soft) و سخت (hard) با کاما از هم جدا شده‌اند. مقدار .Dq infinity نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است. .It rlimit_core=soft,hard بزرگ‌ترین اندازه فایل core dump که می‌تواند ایجاد شود (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار .Dq infinity نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است. .It rlimit_cpu=soft,hard حداکثر زمان پردازنده (CPU time) که فرآیند می‌تواند استفاده کند (به ثانیه). حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار .Dq infinity نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است. .It rlimit_data=soft,hard حداکثر اندازه بخش داده (data segment) برای فرآیند (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار .Dq infinity نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است. .It rlimit_fsize=soft,hard بزرگ‌ترین اندازه فایلی که فرآیند می‌تواند ایجاد کند (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار .Dq infinity نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است. .It rlimit_locks=soft,hard حداکثر تعداد قفل‌هایی که فرآیند می‌تواند ایجاد کند، در صورت پشتیبانی سیستم‌عامل. حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار .Dq infinity نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است. .It rlimit_memlock=soft,hard حداکثر اندازه‌ای که فرآیند می‌تواند در حافظه قفل کند (به بایت)، در صورت پشتیبانی سیستم‌عامل. حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار .Dq infinity نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است. .It rlimit_nofile=soft,hard حداکثر تعداد فایل‌هایی که فرآیند می‌تواند همزمان باز نگه دارد. حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار .Dq infinity نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است. .It rlimit_nproc=soft,hard حداکثر تعداد فرآیندهایی که کاربر می‌تواند به طور همزمان اجرا کند. حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار .Dq infinity نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است. .It rlimit_rss=soft,hard حداکثر اندازه‌ای که مقدار فضای مقیم (resident set size) فرآیند می‌تواند رشد کند (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار .Dq infinity نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است. .It rlimit_stack=soft,hard حداکثر اندازه‌ای که پشته (stack) فرآیند می‌تواند رشد کند (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار .Dq infinity نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است. .It sid=int شناسه نشست (session ID) مربوط به فرآیند در حال اجرای .Nm sudo یا ۰ اگر .Nm sudo بخشی از یک نشست کنترل کار (job control) سازگار با POSIX نباشد. تنها از نسخه ۱.۲ رابط API به بعد در دسترس است. .It tcpgid=int شناسه گروه فرآیند پیش‌زمینه مرتبط با دستگاه ترمینال متصل به فرآیند .Nm sudo یا ۰ اگر هیچ ترمینالی موجود نباشد. تنها از نسخه ۱.۲ رابط API به بعد در دسترس است. .It tty=string مسیر به دستگاه ترمینال کاربر، در صورت وجود. این مدخل تنها در صورتی موجود است که کاربر دستگاه ترمینال مرتبط با نشست داشته باشد. .It ttydev=dev_t شماره دستگاه ترمینال کاربر، در صورت وجود، قالب‌بندی‌شده به عنوان یک مقدار .Vt long long . این مدخل تنها در صورتی وجود دارد که کاربر دستگاه ترمینال مرتبط با این نشست داشته باشد. تنها از نسخه ۱.۲۲ رابط API به بعد در دسترس است. .It uid=uid_t شناسه کاربر واقعی (real user-ID) کاربری که .Nm sudo را فراخوانی می‌کند. .It umask=octal ماسک ایجاد فایل کاربر فراخوان. تنها از نسخه ۱.۱۰ رابط API به بعد در دسترس است. .It user=string نام کاربری که .Nm sudo را فراخوانی می‌کند. .El .It Fa user_env محیط متغیرهای کاربر در قالب یک بردار خاتمه‌یافته با .Dv NULL از رشته‌های .Dq name=value است. .Pp هنگام تجزیه .Fa user_env ، افزونه باید آن را بر اساس .Sy اولین علامت مساوی .Pq Ql = تقسیم کند، زیرا فیلد .Em name هرگز شامل مساوی نخواهد بود، اما مقدار .Em value ممکن است شامل آن باشد. .It Fa plugin_options هر رشته‌ای (غیر از کامنت‌ها) که بلافاصله پس از مسیر افزونه قرار گیرد، به عنوان آرگومان به افزونه ارسال می‌شود. این آرگومان‌ها با فاصله جدا می‌شوند و در قالب یک آرایه از رشته‌ها که با .Dv NULL خاتمه یافته است به افزونه ارسال می‌گردند. اگر هیچ آرگومانی مشخص نشده باشد، .Fa plugin_options یک اشاره‌گر .Dv NULL خواهد بود. .Pp پارامتر .Fa plugin_options تنها از نسخه ۱.۲ رابط API به بعد در دسترس است. یک افزونه .Sy باید پیش از استفاده از .Fa plugin_options ، نسخه API مشخص‌شده توسط فرانت‌اند .Nm sudo را بررسی کند. کوتاهی در این کار ممکن است منجر به کرش و فروپاشی برنامه شود. .It Fa errstr اگر تابع .Fn open مقداری غیر از ۱ برگرداند، افزونه ممکن است پیامی را برای توصیف شکست یا خطا در .Fa errstr ذخیره کند. سپس فرانت‌اند .Nm sudo این مقدار را به تمام افزونه‌های بازرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمانی که تابع .Fn close افزونه فراخوانی شود معتبر بماند. .Pp پارامتر .Fa errstr تنها از نسخه ۱.۱۵ رابط API به بعد در دسترس است. یک افزونه .Sy باید پیش از استفاده از .Fa errstr ، نسخه API مشخص‌شده توسط فرانت‌اند .Nm sudo را بررسی کند. کوتاهی در این کار ممکن است منجر به کرش و فروپاشی برنامه شود. .El .It Fa close .Bd -literal -compact void (*close)(int exit_status, int error); .Ed .Pp تابع .Fn close هنگامی فراخوانی می‌شود که کار .Nm sudo به پایان رسیده باشد، اندکی پیش از خروج آن. از نسخه ۱.۱۵ رابط API به بعد، .Fn close صرف‌نظر از اینکه دستوری واقعاً اجرا شده باشد یا خیر فراخوانی می‌شود. این امر به افزونه‌ها امکان می‌دهد تا حتی در صورت اجرا نشدن یک دستور نیز عملیات پاکسازی را انجام دهند. تنها بر اساس آرگومان‌های ارائه‌شده به تابع .Fn close نمی‌توان تشخیص داد که آیا دستوری اجرا شده است یا خیر. برای تعیین اینکه آیا یک دستور واقعاً اجرا شده است یا نه، افزونه باید پیگیری کند که آیا تابع .Fn check_policy با موفقیت بازگشته است یا خیر. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa exit_status وضعیت خروج دستور، همان‌طور که توسط فراخوانی سیستمی .Xr wait 2 برگردانده شده است، یا صفر در صورتی که هیچ دستوری اجرا نشده باشد. اگر مقدار .Fa error غیر صفر باشد، مقدار .Fa exit_status تعریف‌نشده است. .It Fa error اگر دستور نتواند اجرا شود، این فیلد روی مقدار .Va errno تنظیم می‌شود که توسط فراخوانی سیستمی .Xr execve 2 ایجاد شده است. افزونه مسئول نمایش اطلاعات خطا از طریق تابع .Fn conversation یا .Fn sudo_plugin_printf است. اگر دستور با موفقیت اجرا شده باشد، مقدار .Fa error صفر است. .El .Pp اگر هیچ تابع .Fn close تعریف نشده باشد، هیچ افزونه ثبت ورودی/خروجی (I/O logging) بارگذاری نشده باشد، و هیچ‌یک از گزینه‌های .Em timeout یا .Em use_pty در لیست .Fa command_info تنظیم نشده باشند، فرانت‌اند .Nm sudo ممکن است به جای اجرای دستور به عنوان یک فرآیند فرزند، آن را مستقیماً اجرا کند. .It Fa show_version .Bd -literal -compact int (*show_version)(int verbose); .Ed .Pp تابع .Fn show_version توسط .Nm sudo هنگامی فراخوانی می‌شود که کاربر گزینه .Fl V را مشخص کرده باشد. افزونه می‌تواند اطلاعات نسخه خود را از طریق تابع .Fn conversation یا .Fn sudo_plugin_printf با استفاده از .Dv SUDO_CONV_INFO_MSG به کاربر نمایش دهد. اگر کاربر اطلاعات دقیق نسخه را درخواست کند، فلگ .Fa verbose غیر صفر خواهد بود. .Pp در صورت موفقیت ۱، در صورت شکست ۰، در صورت خطای عمومی \-۱، و در صورت خطای نحوه استفاده \-۲ برمی‌گرداند، اگرچه مقدار بازگشتی در حال حاضر نادیده گرفته می‌شود. .It Fa check_policy .Bd -literal -compact int (*check_policy)(int argc, char * const argv[], char *env_add[], char **command_info[], char **argv_out[], char **user_env_out[], const char **errstr); .Ed .Pp تابع .Fn check_policy توسط .Nm sudo فراخوانی می‌شود تا مشخص گردد آیا کاربر مجاز به اجرای دستورات مشخص‌شده هست یا خیر. .Pp اگر گزینه .Em sudoedit در آرایه .Fa settings که به تابع .Fn open ارسال شده است فعال شده باشد، کاربر حالت .Em sudoedit را درخواست کرده است. .Em sudoedit مکانیزمی برای ویرایش یک یا چند فایل است که در آن ویرایشگر به جای دسترسی‌های ارتقاءیافته، با اعتبارنامه‌های خود کاربر اجرا می‌شود. .Nm sudo این کار را با ایجاد نسخه‌های موقت قابل نوشتن توسط کاربر از فایل‌های مورد نظر و سپس رونویسی نسخه‌های اصلی با این نسخه‌های موقت پس از اتمام ویرایش انجام می‌دهد. اگر افزونه از .Em sudoedit پشتیبانی کند، باید .Em sudoedit=true را در لیست .Fa command_info تنظیم نماید. افزونه مسئول انتخاب ویرایشگر مورد استفاده است، که می‌تواند از یک متغیر در محیط کاربر مانند .Ev EDITOR انتخاب شده و باید در .Fa argv_out ذخیره شود (متغیرهای محیطی ممکن است شامل گزینه‌های خط فرمان باشند). فایل‌هایی که باید ویرایش شوند باید از .Fa argv به .Fa argv_out کپی شوند و با یک عنصر .Ql -- از ویرایشگر و آرگومان‌های آن جدا گردند. این .Ql -- پیش از اجرای ویرایشگر توسط .Nm sudo حذف خواهد شد. افزونه همچنین می‌تواند .Em sudoedit_nfiles را روی تعداد فایل‌های مورد ویرایش در لیست .Fa command_info تنظیم کند؛ این مقدار تنها از نسخه ۱.۲۱ رابط API به بعد توسط فرانت‌اند .Nm sudo استفاده خواهد شد. .Pp تابع .Fn check_policy در صورتی که دستور مجاز باشد مقدار ۱، در صورت عدم مجاز بودن ۰، در صورت خطای عمومی \-۱، و در صورت خطای نحوه استفاده یا در صورتی که .Em sudoedit مشخص شده باشد ولی توسط افزونه پشتیبانی نشود، مقدار \-۲ را بازمی‌گرداند. در حالت آخر، .Nm sudo پیش از خروج، پیام نحوه استفاده را چاپ خواهد کرد. اگر خطایی رخ دهد، افزونه می‌تواند به صورت اختیاری تابع .Fn conversation یا .Fn sudo_plugin_printf را با .Dv SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری را به کاربر نمایش دهد. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa argc تعداد عناصر موجود در .Fa argv ، بدون احتساب اشاره‌گر پایانی .Dv NULL . .It Fa argv بردار آرگومان که دستوری را که کاربر مایل به اجرای آن است توصیف می‌کند، به همان شکلی که به فراخوانی سیستمی .Xr execve 2 ارسال می‌شود. این بردار با یک اشاره‌گر .Dv NULL خاتمه می‌یابد. .It Fa env_add متغیرهای محیطی اضافی که توسط کاربر در خط فرمان مشخص شده‌اند، در قالب یک بردار خاتمه‌یافته با .Dv NULL از رشته‌های .Dq name=value . افزونه در صورتی که یک یا چند متغیر مجاز به تنظیم نباشند می‌تواند دستور را رد کند، یا ممکن است چنین متغیرهایی را بدون اعلام خطا نادیده بگیرد. .Pp هنگام تجزیه .Fa env_add ، افزونه باید بر اساس .Sy اولین علامت مساوی .Pq Ql = تقسیم کند، زیرا فیلد .Em name هرگز شامل مساوی نخواهد بود، اما مقدار .Em value ممکن است شامل آن باشد. .It Fa command_info اطلاعات مربوط به دستوری که اجرا می‌شود در قالب رشته‌های .Dq name=value . این مقادیر توسط .Nm sudo برای تنظیم محیط اجرا هنگام اجرای یک دستور استفاده می‌شوند. این افزونه مسئول ایجاد و پر کردن بردار است، که باید با یک اشاره‌گر .Dv NULL خاتمه یابد. مقادیر زیر توسط .Nm sudo شناسایی می‌شوند: .Bl -tag -width 4n .It apparmor_profile=string پروفایل AppArmor برای انتقال به آن هنگام اجرای دستور. تنها از نسخه 1.19 به بعد API در دسترس است. .It chroot=string دایرکتوری ریشه برای استفاده هنگام اجرای دستور. .It closefrom=number در صورت مشخص شدن، .Nm sudo تمام توصیف‌کننده‌های فایل با مقداری برابر با .Em number یا بالاتر را خواهد بست. .It command=string مسیر کامل دستوری که باید اجرا شود. .It cwd=string دایرکتوری کاری فعلی برای تغییر به آن هنگام اجرای دستور. اگر .Nm sudo نتواند به دایرکتوری کاری جدید تغییر مسیر دهد، دستور اجرا نخواهد شد مگر اینکه .Em cwd_optional نیز تنظیم شده باشد (به زیر نگاه کنید). .It cwd_optional=bool در صورت تنظیم، .Nm sudo ناتوانی در تغییر به دایرکتوری کاری جدید را به عنوان خطای غیرمهلک در نظر می‌گیرد. این تنظیم هیچ تاثیری ندارد مگر اینکه .Em cwd نیز تنظیم شده باشد. .It exec_background=bool به‌طور پیش‌فرض، .Nm sudo تا زمانی که خودش در پیش‌زمینه در حال اجرا است، دستور را به عنوان فرایند پیش‌زمینه اجرا می‌کند. هنگامی که .Em exec_background فعال باشد و دستور در یک شبه‌ترمینال اجرا شود (به دلیل ثبت لاگ I/O یا تنظیم .Em use_pty )، دستور به عنوان یک فرایند پس‌زمینه اجرا خواهد شد. تلاش‌ها برای خواندن از ترمینال کنترلی (یا تغییر تنظیمات ترمینال) منجر به تعلیق دستور با سیگنال .Dv SIGTTIN (یا در مورد تنظیمات ترمینال، .Dv SIGTTOU ) خواهد شد. اگر این اتفاق زمانی بیفتد که .Nm sudo یک فرایند پیش‌زمینه است، ترمینال کنترلی به دستور واگذار شده و بدون نیاز به دخالت کاربر، در پیش‌زمینه از سر گرفته می‌شود. مزیت اجرای اولیه دستور در پس‌زمینه این است که .Nm sudo نیازی به خواندن از ترمینال ندارد مگر اینکه دستور صریحاً آن را درخواست کند. در غیر این صورت، هر ورودی ترمینال باید به دستور تحویل داده شود، چه به آن نیاز داشته باشد و چه نداشته باشد (هسته سیستم‌عامل ترمینال‌ها را بافر می‌کند، بنابراین نمی‌توان تشخیص داد که آیا دستور واقعاً ورودی را می‌خواهد یا خیر). این با رفتار تاریخی .Nm sudo یا وضعیتی که دستور در شبه‌ترمینال اجرا نمی‌شود تفاوت دارد. .Pp برای اینکه این سازوکار بدون مشکل کار کند، سیستم‌عامل باید از راه‌اندازی مجدد خودکار فراخوان‌های سیستمی پشتیبانی کند. متاسفانه همه سیستم‌عامل‌ها به‌طور پیش‌فرض این کار را انجام نمی‌دهند، و حتی سیستم‌هایی که انجام می‌دهند نیز ممکن است اشکالاتی داشته باشند. برای مثال، macOS در راه‌اندازی مجدد فراخوان‌های سیستمی .Fn tcgetattr و .Fn tcsetattr ناموفق است (این یک باگ در macOS است). علاوه بر این، از آنجا که این رفتار به متوقف شدن دستور با سیگنال‌های .Dv SIGTTIN یا .Dv SIGTTOU وابسته است، برنامه‌هایی که این سیگنال‌ها را دریافت کرده و خود را با سیگنال دیگری (معمولاً .Dv SIGTOP ) معلق می‌کنند، به‌طور خودکار به پیش‌زمینه منتقل نخواهند شد. برخی از نسخه‌های دستور .Xr su 1 در لینوکس به این شکل رفتار می‌کنند. به همین دلیل، یک افزونه نباید .Em exec_background را تنظیم کند مگر اینکه صریحاً توسط مدیر سیستم فعال شده باشد و باید راهی برای فعال یا غیرفعال کردن آن بر مبنای هر دستور وجود داشته باشد. .Pp این تنظیم هیچ تاثیری ندارد مگر اینکه ثبت لاگ I/O فعال باشد یا .Em use_pty فعال شده باشد. .It execfd=number در صورت مشخص شدن، .Nm sudo از فراخوان سیستمی .Xr fexecve 2 به جای .Xr execve 2 برای اجرای دستور استفاده خواهد کرد. مقدار مشخص‌شده .Em number باید به یک توصیف‌کننده فایل باز ارجاع داشته باشد. .It intercept=bool در صورت تنظیم، .Nm sudo تلاش‌ها برای اجرای یک دستور بعدی را رهگیری کرده و با استفاده از تابع .Fn check_policy افزونه خط‌مشی، یک بررسی خط‌مشی انجام می‌دهد تا مشخص کند که آیا اجرای دستور مجاز است یا خیر. از این سازوکار می‌توان برای جلوگیری از گریز به پوسته در پلتفرم‌های پشتیبانی‌شده استفاده کرد، اما دارای محدودیت‌های متعددی است. برای جزئیات بیشتر به بخش .Sy Preventing shell escapes در .Xr sudoers 5 مراجعه کنید. تنها از نسخه 1.18 به بعد API در دسترس است. .It intercept_verify=bool در صورت تنظیم، .Nm sudo تلاش خواهد کرد تا بررسی کند که دستوری که در حالت رهگیری اجرا می‌شود، نام مسیر، آرگومان‌های خط فرمان و محیط مورد انتظار را دارد یا خیر. این تنظیم هیچ تاثیری ندارد مگر اینکه .Em use_ptrace نیز فعال باشد. تنها از نسخه 1.20 به بعد API در دسترس است. .It iolog_compress=bool اگر افزونه‌های ثبت لاگ I/O (در صورت وجود) باید داده‌های لاگ را فشرده کنند، روی true تنظیم شود. این یک راهنمایی (hint) برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد. .It iolog_group=string گروهی که مالک فایل‌ها و دایرکتوری‌های لاگ I/O تازه ایجادشده خواهد بود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد. .It iolog_mode=octal حالت دسترسی فایل برای استفاده هنگام ایجاد فایل‌ها و دایرکتوری‌های لاگ I/O. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد. .It iolog_user=string کاربری که مالک فایل‌ها و دایرکتوری‌های لاگ I/O تازه ایجادشده خواهد بود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد. .It iolog_path=string مسیر کامل فایل یا دایرکتوری‌ای که لاگ I/O در آن ذخیره می‌شود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد. اگر هیچ افزونه ثبت لاگ I/O بارگذاری نشده باشد، این تنظیم هیچ تاثیری ندارد. .It iolog_stdin=bool اگر افزونه‌های ثبت لاگ I/O (در صورت وجود) باید ورودی استاندارد را در صورتی که به یک دستگاه ترمینال متصل نیست ثبت کنند، روی true تنظیم شود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد. .It iolog_stdout=bool اگر افزونه‌های ثبت لاگ I/O (در صورت وجود) باید خروجی استاندارد را در صورتی که به یک دستگاه ترمینال متصل نیست ثبت کنند، روی true تنظیم شود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد. .It iolog_stderr=bool اگر افزونه‌های ثبت لاگ I/O (در صورت وجود) باید خطای استاندارد را در صورتی که به یک دستگاه ترمینال متصل نیست ثبت کنند، روی true تنظیم شود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد. .It iolog_ttyin=bool اگر افزونه‌های ثبت لاگ I/O (در صورت وجود) باید تمام ورودی‌های ترمینال را ثبت کنند، روی true تنظیم شود. این فقط شامل ورودی تایپ‌شده توسط کاربر است و شامل ورودی از طریق لوله (pipe) یا تغییرمسیریافته از یک فایل نمی‌شود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد. .It iolog_ttyout=bool اگر افزونه‌های ثبت لاگ I/O (در صورت وجود) باید تمام خروجی‌های ترمینال را ثبت کنند، روی true تنظیم شود. این فقط شامل خروجی نمایش‌یافته بر روی صفحه است، نه خروجی ارسال‌شده به لوله یا فایل. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد. .It login_class=string کلاس ورود .Bx برای استفاده هنگام تنظیم محدودیت‌های منابع و مقدار nice (اختیاری). این گزینه فقط روی سیستم‌هایی تنظیم می‌شود که از کلاس‌های ورود پشتیبانی می‌کنند. .It nice=int مقدار nice (اولویت) برای استفاده هنگام اجرای دستور. مقدار nice، در صورت مشخص شدن، اولویت مرتبط با .Em login_class را در سیستم‌های .Bx نادیده می‌گیرد. .It log_subcmds=bool در صورت تنظیم، .Nm sudo تابع .Fn accept افزونه ممیزی را فراخوانی می‌کند تا هنگام اجرای یک دستور بعدی توسط دستور اصلی، در صورت پشتیبانی سیستم، آن را ثبت کند. اگر .Em intercept نیز مشخص شده باشد، .Em log_subcmds نادیده گرفته خواهد شد. برای اطلاعات بیشتر به بخش .Sy Preventing shell escapes در .Xr sudoers 5 مراجعه کنید. تنها از نسخه 1.18 به بعد API در دسترس است. .It noexec=bool در صورت تنظیم، از اجرای سایر برنامه‌ها توسط دستور جلوگیری می‌کند. .It preserve_fds=list فهرستی از توصیف‌کننده‌های فایل که با کاما از یکدیگر جدا شده‌اند و باید صرف‌نظر از مقدار تنظیم .Em closefrom حفظ شوند. تنها از نسخه 1.5 به بعد API در دسترس است. .It preserve_groups=bool در صورت تنظیم، .Nm sudo بردار گروه‌های کاربر را به جای مقداردهی اولیه بر اساس .Em runas_user حفظ خواهد کرد. .It rlimit_as=soft,hard حداکثر اندازه‌ای که فضای آدرس فرایند می‌تواند تا آن گسترش یابد (به بایت)، در صورت پشتیبانی سیستم‌عامل. حدود نرم (soft) و سخت (hard) با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار .Dq infinity نشان‌دهنده عدم وجود محدودیت است. مقدار .Dq user باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار .Dq default باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است. .It rlimit_core=soft,hard بزرگ‌ترین اندازه فایل تخلیه حافظه (core dump) که ممکن است ایجاد شود (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار .Dq infinity نشان‌دهنده عدم وجود محدودیت است. مقدار .Dq user باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار .Dq default باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است. .It rlimit_cpu=soft,hard حداکثر مدت زمان پردازنده که فرایند می‌تواند استفاده کند (به ثانیه). حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار .Dq infinity نشان‌دهنده عدم وجود محدودیت است. مقدار .Dq user باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار .Dq default باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است. .It rlimit_data=soft,hard حداکثر اندازه بخش داده برای فرایند (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار .Dq infinity نشان‌دهنده عدم وجود محدودیت است. مقدار .Dq user باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار .Dq default باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است. .It rlimit_fsize=soft,hard بزرگ‌ترین اندازه فایلی که فرایند می‌تواند ایجاد کند (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار .Dq infinity نشان‌دهنده عدم وجود محدودیت است. مقدار .Dq user باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار .Dq default باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است. .It rlimit_locks=soft,hard حداکثر تعداد قفل‌هایی که فرایند می‌تواند برقرار کند، در صورت پشتیبانی سیستم‌عامل. حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار .Dq infinity نشان‌دهنده عدم وجود محدودیت است. مقدار .Dq user باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار .Dq default باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است. .It rlimit_memlock=soft,hard حداکثر اندازه‌ای که فرایند می‌تواند در حافظه قفل کند (به بایت)، در صورت پشتیبانی سیستم‌عامل. حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار .Dq infinity نشان‌دهنده عدم وجود محدودیت است. مقدار .Dq user باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار .Dq default باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است. .It rlimit_nofile=soft,hard حداکثر تعداد فایل‌هایی که فرایند می‌تواند باز داشته باشد. حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار .Dq infinity نشان‌دهنده عدم وجود محدودیت است. مقدار .Dq user باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار .Dq default باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است. .It rlimit_nproc=soft,hard حداکثر تعداد فرایندهایی که کاربر می‌تواند به‌طور همزمان اجرا کند. حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار .Dq infinity نشان‌دهنده عدم وجود محدودیت است. مقدار .Dq user باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار .Dq default باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است. .It rlimit_rss=soft,hard حداکثر اندازه‌ای که اندازه مجموعه مقیم (resident set size) فرایند می‌تواند تا آن گسترش یابد (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار .Dq infinity نشان‌دهنده عدم وجود محدودیت است. مقدار .Dq user باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار .Dq default باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است. .It rlimit_stack=soft,hard حداکثر اندازه‌ای که پشته فرایند می‌تواند تا آن گسترش یابد (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار .Dq infinity نشان‌دهنده عدم وجود محدودیت است. مقدار .Dq user باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار .Dq default باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است. .It runas_egid=gid شناسه گروه مؤثر (effective group-ID) برای اجرای دستور با آن. در صورت عدم تعیین، مقدار .Em runas_gid استفاده می‌شود. .It runas_euid=uid شناسه کاربر مؤثر (effective user-ID) برای اجرای دستور با آن. در صورت عدم تعیین، مقدار .Em runas_uid استفاده می‌شود. .It runas_gid=gid شناسه گروه (group-ID) برای اجرای دستور با آن. .It runas_group=string نام گروهی که دستور با آن اجرا خواهد شد، در صورتی که با گروه پیش‌فرض .Em runas_user متفاوت باشد. این مقدار صرفاً برای مقاصد ممیزی ارائه شده است؛ پیشخوان .Nm sudo هنگام اجرای دستور از .Em runas_egid و .Em runas_gid استفاده می‌کند. .It runas_groups=list بردار گروه‌های کمکی (supplementary group vector) برای استفاده در دستور به شکل فهرستی از شناسه‌های گروه جداشده با کاما. اگر .Em preserve_groups تنظیم شده باشد، این گزینه نادیده گرفته می‌شود. .It runas_uid=uid شناسه کاربر (user-ID) برای اجرای دستور با آن. .It runas_user=string نام کاربری که دستور با آن اجرا خواهد شد، که باید با .Em runas_euid (یا در صورت عدم تنظیم .Em runas_euid ، با .Em runas_uid ) مطابقت داشته باشد. این مقدار صرفاً برای مقاصد ممیزی ارائه شده است؛ پیشخوان .Nm sudo هنگام اجرای دستور از .Em runas_euid و .Em runas_uid استفاده می‌کند. .It selinux_role=string نقش SELinux برای استفاده هنگام اجرای دستور. .It selinux_type=string نوع SELinux برای استفاده هنگام اجرای دستور. .It set_utmp=bool ایجاد یک ورودی utmp (یا utmpx) هنگام تخصیص یک شبه‌ترمینال. به‌طور پیش‌فرض، ورودی جدید یک کپی از ورودی utmp موجود کاربر (در صورت وجود) خواهد بود، همراه با به‌روزرسانی فیلدهای tty، time، type و pid. .It sudoedit=bool روی true تنظیم می‌شود هنگامی که در حالت .Em sudoedit باشد. این افزونه ممکن است حالت .Em sudoedit را فعال کند حتی اگر .Nm sudo به‌عنوان .Nm sudoedit فراخوانی نشده باشد. این به افزونه اجازه می‌دهد تا جایگزینی دستور را انجام داده و در صورت تلاش کاربر برای اجرای یک ویرایشگر، حالت .Em sudoedit را به‌طور شفاف فعال سازد. .It sudoedit_checkdir=bool برای غیرفعال کردن بررسی‌های قابلیت نوشتن در دایرکتوری در .Nm sudoedit روی false تنظیم کنید. به‌طور پیش‌فرض، .Nm sudoedit نسخه 1.8.16 و بالاتر، تمام بخش‌های دایرکتوری در مسیر مورد ویرایش را از نظر قابلیت نوشتن توسط کاربر فراخواننده بررسی می‌کند. پیوندهای نمادین در دایرکتوری‌های قابل نوشتن دنبال نخواهند شد و .Nm sudoedit از ویرایش فایلی که در یک دایرکتوری قابل نوشتن قرار دارد خودداری می‌کند. این محدودیت‌ها زمانی که .Nm sudoedit توسط root اجرا شود اعمال نمی‌گردند. گزینه .Em sudoedit_checkdir می‌تواند روی false تنظیم شود تا این بررسی غیرفعال گردد. تنها از نسخه 1.8 به بعد API در دسترس است. .It sudoedit_follow=bool روی true تنظیم شود تا به .Nm sudoedit اجازه ویرایش فایل‌هایی که پیوند نمادین هستند داده شود. به‌طور پیش‌فرض، .Nm sudoedit نسخه 1.8.15 و بالاتر از باز کردن یک پیوند نمادین خودداری می‌کند. گزینه .Em sudoedit_follow می‌تواند برای بازگرداندن رفتار قدیمی‌تر و مجاز ساختن .Nm sudoedit به باز کردن پیوندهای نمادین استفاده شود. تنها از نسخه 1.8 به بعد API در دسترس است. .It sudoedit_nfiles=number تعداد فایل‌هایی که باید توسط کاربر ویرایش شوند. در صورت وجود، این مقدار توسط پیشخوان .Nm sudo استفاده خواهد شد تا مشخص شود کدام عناصر بردار .Fa argv_out فایل‌های مورد ویرایش هستند. عنصر .Ql -- باید بلافاصله پیش از اولین فایل مورد ویرایش قرار گیرد. اگر .Em sudoedit_nfiles مشخص نشده باشد، پیشخوان .Nm sudo از موقعیت عنصر .Ql -- برای تعیین محل شروع فهرست فایل‌ها استفاده خواهد کرد. تنها از نسخه 1.21 به بعد API در دسترس است. .It timeout=int مهلت زمانی دستور. اگر غیرصفر باشد، پس از انقضای مهلت زمانی دستور خاتمه داده خواهد شد (کشته می‌شود). .It umask=octal ماسک ایجاد فایل برای استفاده هنگام اجرای دستور. این مقدار ممکن است در برخی سیستم‌ها توسط PAM یا login.conf نادیده گرفته شود، مگر اینکه گزینه .Em umask_override نیز تنظیم شده باشد. .It umask_override=bool مقدار مشخص‌شده توسط گزینه .Em umask را مجبور می‌کند تا هر umask تعیین‌شده توسط PAM یا login.conf را نادیده بگیرد. .It use_ptrace=bool در صورت تنظیم، .Nm sudo از .Xr ptrace 2 برای پیاده‌سازی حالت رهگیری در صورت پشتیبانی سیستم استفاده خواهد کرد. این تنظیم هیچ تاثیری ندارد مگر اینکه .Em intercept نیز تنظیم شده باشد. تنها از نسخه 1.19 به بعد API در دسترس است. .It use_pty=bool صرف‌نظر از اینکه لاگ‌گیری I/O در حال استفاده باشد یا خیر، یک شبه‌ترمینال برای اجرای دستور در آن تخصیص می‌دهد. به‌طور پیش‌فرض، .Nm sudo تنها زمانی دستور را در یک شبه‌ترمینال اجرا می‌کند که یک افزونه ثبت لاگ I/O بارگذاری شده باشد. .It utmp_user=string نام کاربری برای استفاده هنگام ساخت یک ورودی utmp (یا utmpx) جدید در زمانی که .Em set_utmp فعال است. این گزینه می‌تواند برای تنظیم فیلد کاربر در ورودی utmp روی کاربری که دستور با آن اجرا می‌شود به جای کاربر فراخواننده استفاده گردد. در صورت عدم تنظیم، .Nm sudo ورودی جدید را بر اساس ورودی موجود کاربر فراخواننده پایه‌گذاری خواهد کرد. .El .Pp مقادیر پشتیبانی‌نشده نادیده گرفته خواهند شد. .It Fa argv_out بردار آرگومان‌های خاتمه‌یافته با .Dv NULL برای ارسال به فراخوان سیستمی .Xr execve 2 هنگام اجرای دستور. افزونه مسئول تخصیص حافظه و پر کردن این بردار است. .It Fa user_env_out بردار محیطی خاتمه‌یافته با .Dv NULL برای استفاده هنگام اجرای دستور. افزونه مسئول تخصیص حافظه و پر کردن این بردار است. .It Fa errstr اگر تابع .Fn check_policy مقداری به جز 1 بازگرداند، افزونه می‌تواند پیامی حاوی شرح شکست یا خطا را در .Fa errstr ذخیره کند. سپس پیشخوان .Nm sudo این مقدار را به تمام افزونه‌های ممیزی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمانی که تابع .Fn close افزونه فراخوانی شود معتبر باقی بماند. .Pp پارامتر .Fa errstr تنها از نسخه 1.15 به بعد API در دسترس است. یک افزونه .Sy باید نسخه API مشخص‌شده توسط پیشخوان .Nm sudo را قبل از استفاده از .Fa errstr بررسی کند. عدم انجام این کار ممکن است منجر به کرش شود. .El .It Fa list .Bd -literal -compact int (*list)(int argc, char * const argv[], int verbose, const char *user, const char **errstr); .Ed .Pp فهرست کردن اختیارات موجود برای کاربر فراخواننده. در صورت موفقیت 1، در صورت شکست 0، و در صورت بروز خطا \-1 بازمی‌گرداند. در صورت بروز خطا، افزونه می‌تواند به صورت اختیاری تابع .Fn conversation یا .Fn sudo_plugin_printf را با .Dv SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری به کاربر ارائه دهد. .Pp اختیارات باید از طریق تابع .Fn conversation یا .Fn sudo_plugin_printf با استفاده از .Dv SUDO_CONV_INFO_MSG ارائه شوند. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa argc تعداد عناصر موجود در .Fa argv ، بدون احتساب اشاره‌گر پایانی .Dv NULL . .It Fa argv اگر غیر از .Dv NULL باشد، یک بردار آرگومان است که دستوری را که کاربر مایل است در برابر خط‌مشی بررسی کند توصیف می‌نماید، به همان صورتی که به فراخوان سیستمی .Xr execve 2 ارسال می‌شد. اگر دستور توسط خط‌مشی مجاز باشد، مسیر کامل دستور باید همراه با هرگونه آرگومان خط فرمان نمایش داده شود. .It Fa verbose فلگی که مشخص می‌کند فهرست‌بندی در حالت پرگو (verbose) انجام شود یا خیر. .It Fa user نام یک کاربر دیگر برای فهرست کردن اختیارات او در صورتی که خط‌مشی اجازه دهد. اگر .Dv NULL باشد، افزونه باید اختیارات کاربر فراخواننده را فهرست کند. .It Fa errstr اگر تابع .Fn list مقداری به جز 1 بازگرداند، افزونه می‌تواند پیامی حاوی شرح شکست یا خطا را در .Fa errstr ذخیره کند. سپس پیشخوان .Nm sudo این مقدار را به تمام افزونه‌های ممیزی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمانی که تابع .Fn close افزونه فراخوانی شود معتبر باقی بماند. .Pp پارامتر .Fa errstr تنها از نسخه 1.15 به بعد API در دسترس است. یک افزونه .Sy باید نسخه API مشخص‌شده توسط پیشخوان .Nm sudo را قبل از استفاده از .Fa errstr بررسی کند. عدم انجام این کار ممکن است منجر به کرش شود. .El .It Fa validate .Bd -literal -compact int (*validate)(const char **errstr); .Ed .Pp تابع .Fn validate زمانی فراخوانی می‌شود که .Nm sudo با گزینه .Fl v اجرا شده باشد. برای افزونه‌های خط‌مشی مانند .Nm sudoers که گواهی‌های احراز هویت را کش می‌کنند، این تابع گواهی‌ها را اعتبارسنجی کرده و در کش قرار می‌دهد. .Pp اگر افزونه از کش کردن گواهی‌های احراز هویت پشتیبانی نمی‌کند، تابع .Fn validate باید .Dv NULL باشد. .Pp در صورت موفقیت 1، در صورت شکست 0، و در صورت بروز خطا \-1 بازمی‌گرداند. در صورت بروز خطا، افزونه می‌تواند به صورت اختیاری تابع .Fn conversation یا .Fn sudo_plugin_printf را با .Dv SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری به کاربر ارائه دهد. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Va errstr اگر تابع .Fn validate مقداری به جز 1 بازگرداند، افزونه می‌تواند پیامی حاوی شرح شکست یا خطا را در .Fa errstr ذخیره کند. سپس پیشخوان .Nm sudo این مقدار را به تمام افزونه‌های ممیزی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمانی که تابع .Fn close افزونه فراخوانی شود معتبر باقی بماند. .Pp پارامتر .Fa errstr تنها از نسخه 1.15 به بعد API در دسترس است. یک افزونه .Sy باید نسخه API مشخص‌شده توسط پیشخوان .Nm sudo را قبل از استفاده از .Fa errstr بررسی کند. عدم انجام این کار ممکن است منجر به کرش شود. .El .It Fa invalidate .Bd -literal -compact void (*invalidate)(int rmcred); .Ed .Pp تابع .Fn invalidate زمانی فراخوانی می‌شود که .Nm sudo با گزینه .Fl k یا .Fl K اجرا شده باشد. برای افزونه‌های خط‌مشی مانند .Nm sudoers که گواهی‌های احراز هویت را کش می‌کنند، این تابع گواهی‌ها را باطل می‌سازد. اگر فلگ .Fa rmcred غیرصفر باشد، افزونه ممکن است گواهی‌ها را به جای باطل‌سازیِ ساده حذف کند. .Pp اگر افزونه از کش کردن گواهی‌های احراز هویت پشتیبانی نمی‌کند، تابع .Fn invalidate باید .Dv NULL باشد. .It Fa init_session .Bd -literal -compact int (*init_session)(struct passwd *pwd, char **user_env[], const char **errstr); .Ed .Pp تابع .Fn init_session قبل از اینکه .Nm sudo محیط اجرا را برای دستور آماده کند فراخوانی می‌شود. این تابع در فرایند والد .Nm sudo قبل از هرگونه تغییر شناسه کاربر یا شناسه گروه اجرا می‌شود. از این تابع می‌توان برای راه‌اندازی نشست‌هایی استفاده کرد که توسط .Fa command_info پشتیبانی نمی‌شوند، مانند باز کردن یک نشست PAM. از تابع .Fn close می‌توان برای بستن نشستی که توسط .Fn init_session باز شده است استفاده کرد. .Pp در صورت موفقیت 1، در صورت شکست 0، و در صورت بروز خطا \-1 بازمی‌گرداند. در صورت بروز خطا، افزونه می‌تواند به صورت اختیاری تابع .Fn conversation یا .Fn sudo_plugin_printf را با .Dv SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری به کاربر ارائه دهد. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa pwd اگر شناسه کاربری که دستور با آن اجرا می‌شود در پایگاه داده گذرواژه‌ها پیدا شده باشد، .Fa pwd آن کاربر را توصیف خواهد کرد، در غیر این صورت .Dv NULL خواهد بود. .It Fa user_env_out بردار محیطی خاتمه‌یافته با .Dv NULL برای استفاده هنگام اجرای دستور. این همان رشته‌ای است که از طریق پارامتر .Fa user_env_out افزونه خط‌مشی به پیشخوان بازگردانده می‌شود. اگر تابع .Fn init_session نیاز به اصلاح محیط کاربر داشته باشد، باید اشاره‌گر ذخیره‌شده در .Fa user_env_out را به‌روز کند. کاربرد مورد انتظار، ادغام محتویات محیط PAM (در صورت وجود) با محتویات .Fa user_env_out است. پارامتر .Fa user_env_out تنها از نسخه 1.2 به بعد API در دسترس است. یک افزونه .Sy باید نسخه API مشخص‌شده توسط پیشخوان .Nm sudo را قبل از استفاده از .Fa user_env_out بررسی کند. عدم انجام این کار ممکن است منجر به کرش شود. .It Fa errstr اگر تابع .Fn init_session مقداری به جز 1 بازگرداند، افزونه می‌تواند پیامی حاوی شرح شکست یا خطا را در .Fa errstr ذخیره کند. سپس پیشخوان .Nm sudo این مقدار را به تمام افزونه‌های ممیزی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمانی که تابع .Fn close افزونه فراخوانی شود معتبر باقی بماند. .Pp پارامتر .Fa errstr تنها از نسخه 1.15 به بعد API در دسترس است. یک افزونه .Sy باید نسخه API مشخص‌شده توسط پیشخوان .Nm sudo را قبل از استفاده از .Fa errstr بررسی کند. عدم انجام این کار ممکن است منجر به کرش شود. .El .It Fa register_hooks .Bd -literal -compact void (*register_hooks)(int version, int (*register_hook)(struct sudo_hook *hook)); .Ed .Pp تابع .Fn register_hooks توسط پیشخوان sudo برای ثبت هرگونه قلابی که افزونه نیاز دارد فراخوانی می‌شود. اگر افزونه از قلاب‌ها پشتیبانی نمی‌کند، .Fa register_hooks باید روی اشاره‌گر .Dv NULL تنظیم شود. .Pp آرگومان .Fa version نسخه API قلاب‌های پشتیبانی‌شده توسط پیشخوان .Nm sudo را توصیف می‌کند. .Pp تابع .Fn register_hook باید برای ثبت هر قلاب پشتیبانی‌شده‌ای که افزونه به آن نیاز دارد استفاده شود. این تابع در صورت موفقیت 0، در صورتی که نوع قلاب پشتیبانی نشود 1، و در صورتی که نسخه اصلی در .Vt struct sudo_hook با نسخه اصلی API قلاب‌های پیشخوان مطابقت نداشته باشد \-1 بازمی‌گرداند. .Pp برای اطلاعات بیشتر درباره قلاب‌ها به بخش .Sx Hook function API در زیر مراجعه کنید. .Pp تابع .Fn register_hooks تنها از نسخه 1.2 به بعد API در دسترس است. اگر پیشخوان .Nm sudo از نسخه 1.2 یا بالاتر API پشتیبانی نکند، .Fn register_hooks فراخوانی نخواهد شد. .It Fa deregister_hooks .Bd -literal -compact void (*deregister_hooks)(int version, int (*deregister_hook)(struct sudo_hook *hook)); .Ed .Pp تابع .Fn deregister_hooks توسط پیشخوان sudo برای لغو ثبت هر قلابی که توسط افزونه ثبت شده است فراخوانی می‌شود. اگر افزونه از قلاب‌ها پشتیبانی نمی‌کند، .Fa deregister_hooks باید روی اشاره‌گر .Dv NULL تنظیم شود. .Pp آرگومان .Fa version نسخه API قلاب‌های پشتیبانی‌شده توسط پیشخوان .Nm sudo را توصیف می‌کند. .Pp تابع .Fn deregister_hook باید برای لغو ثبت هر قلابی که توسط تابع .Fn register_hook به کار گرفته شده بود استفاده شود. اگر افزونه تلاش کند قلابی را لغو ثبت کند که پیشخوان از آن پشتیبانی نمی‌کند، .Fn deregister_hook یک خطا بازمی‌گرداند. .Pp برای اطلاعات بیشتر درباره قلاب‌ها به بخش .Sx Hook function API در زیر مراجعه کنید. .Pp تابع .Fn deregister_hooks تنها از نسخه 1.2 به بعد API در دسترس است. اگر پیشخوان .Nm sudo از نسخه 1.2 یا بالاتر API پشتیبانی نکند، .Fn deregister_hooks فراخوانی نخواهد شد. .It Fa event_alloc .Bd -literal -compact struct sudo_plugin_event * (*event_alloc)(void); .Ed .Pp تابع .Fn event_alloc برای تخصیص یک .Vt struct sudo_plugin_event استفاده می‌شود که دسترسی به حلقه رویدادهای اصلی .Nm sudo را فراهم می‌کند. برخلاف سایر فیلدها، اشاره‌گر .Fa event_alloc توسط پیشخوان .Nm sudo پر می‌شود، نه توسط افزونه. .Pp برای اطلاعات بیشتر درباره رویدادها به بخش .Sx Event API در زیر مراجعه کنید. .Pp تابع .Fn event_alloc تنها از نسخه 1.15 به بعد API در دسترس است. اگر پیشخوان .Nm sudo از نسخه 1.15 یا بالاتر API پشتیبانی نکند، .Fa event_alloc تنظیم نخواهد شد. .El .Pp .Em ماکروهای نسخه افزونه خط‌مشی (Policy Plugin Version Macros) .Bd -literal /* Plugin API version major/minor. */ #define SUDO_API_VERSION_MAJOR 1 #define SUDO_API_VERSION_MINOR 13 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y) #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\e SUDO_API_VERSION_MINOR) /* Getters and setters for API version */ #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16) #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff) #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \e *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e } while(0) #define SUDO_API_VERSION_SET_MINOR(vp, n) do { \e *(vp) = (*(vp) & 0xffff0000) | (n); \e } while(0) .Ed .Ss "رابط افزونههای ورودی/خروجی (I/O plugin API)" .Bd -literal struct io_plugin { #define SUDO_IO_PLUGIN 2 unsigned int type; /* always SUDO_IO_PLUGIN */ unsigned int version; /* always SUDO_API_VERSION */ int (*open)(unsigned int version, sudo_conv_t conversation, sudo_printf_t sudo_plugin_printf, char * const settings[], char * const user_info[], char * const command_info[], int argc, char * const argv[], char * const user_env[], char * const plugin_options[], const char **errstr); void (*close)(int exit_status, int error); /* wait status or error */ int (*show_version)(int verbose); int (*log_ttyin)(const char *buf, unsigned int len, const char **errstr); int (*log_ttyout)(const char *buf, unsigned int len, const char **errstr); int (*log_stdin)(const char *buf, unsigned int len, const char **errstr); int (*log_stdout)(const char *buf, unsigned int len, const char **errstr); int (*log_stderr)(const char *buf, unsigned int len, const char **errstr); void (*register_hooks)(int version, int (*register_hook)(struct sudo_hook *hook)); void (*deregister_hooks)(int version, int (*deregister_hook)(struct sudo_hook *hook)); int (*change_winsize)(unsigned int lines, unsigned int cols, const char **errstr); int (*log_suspend)(int signo, const char **errstr); struct sudo_plugin_event * (*event_alloc)(void); }; .Ed .Pp هنگامی که یک افزونه ورودی/خروجی بارگذاری می‌شود، .Nm sudo دستور را در یک شبه‌ترمینال اجرا می‌کند. این امر ثبت ورودی و خروجی نشست کاربر را امکان‌پذیر می‌سازد. اگر هر یک از ورودی استاندارد، خروجی استاندارد یا خطای استاندارد به یک tty مربوط نباشد، .Nm sudo یک لوله (pipe) باز می‌کند تا ورودی/خروجی را پیش از ارسال، برای ثبت دریافت کند. .Pp تابع .Fn log_ttyin ورودی خام کاربر را از دستگاه ترمینال دریافت می‌کند (این شامل ورودی حتی در زمان غیرفعال بودن انعکاس .Pq echo ، مانند زمانی که یک گذرواژه خوانده می‌شود، نیز خواهد بود). تابع .Fn log_ttyout خروجی را از شبه‌ترمینال دریافت می‌کند که برای بازپخش نشست کاربر در آینده مناسب است. توابع .Fn log_stdin ، .Fn log_stdout و .Fn log_stderr تنها در صورتی فراخوانی می‌شوند که به ترتیب، ورودی استاندارد، خروجی استاندارد یا خطای استاندارد به چیزی غیر از یک tty مربوط باشند. .Pp در صورتی که قرار نباشد هیچ ثبتی انجام شود، هر یک از توابع ثبت وقایع می‌توانند روی اشاره‌گر .Dv NULL تنظیم شوند. اگر تابع open مقدار 0 بازگرداند، هیچ ورودی/خروجی‌ای به افزونه ارسال نخواهد شد. .Pp اگر یک تابع ثبت وقایع خطایی .Pq \-1 بازگرداند، دستور در حال اجرا پایان خواهد یافت و تمام توابع ثبت وقایع افزونه غیرفعال خواهند شد. سایر افزونه‌های ثبت وقایع ورودی/خروجی همچنان هرگونه ورودی یا خروجی باقی‌مانده‌ای را که هنوز پردازش نشده است دریافت خواهند کرد. .Pp اگر یک تابع ثبت وقایع ورودی، داده را با بازگرداندن 0 رد کند، دستور پایان خواهد یافت و داده به دستور منتقل نخواهد شد، هرچند همچنان به سایر افزونه‌های ثبت وقایع ورودی/خروجی ارسال می‌شود. اگر یک تابع ثبت وقایع خروجی، داده را با بازگرداندن 0 رد کند، دستور پایان خواهد یافت و داده در ترمینال نوشته نخواهد شد، هرچند همچنان به سایر افزونه‌های ثبت وقایع ورودی/خروجی ارسال می‌شود. .Pp یک .Vt struct audit_plugin دارای فیلدهای زیر است: .Bl -tag -width 4n .It Fa type فیلد .Fa type همیشه باید روی .Dv SUDO_IO_PLUGIN تنظیم شود. .It Fa version فیلد .Fa version باید روی .Dv SUDO_API_VERSION تنظیم شود. .Pp این به .Nm sudo امکان می‌دهد تا نسخه API که افزونه بر اساس آن ساخته شده است را تعیین کند. .It Fa open .Bd -literal -compact int (*open)(unsigned int version, sudo_conv_t conversation, sudo_printf_t sudo_plugin_printf, char * const settings[], char * const user_info[], char * const command_info[], int argc, char * const argv[], char * const user_env[], char * const plugin_options[]); .Ed .Pp تابع .Fn open پیش از فراخوانی توابع .Fn log_ttyin ، .Fn log_ttyout ، .Fn log_stdin ، .Fn log_stdout ، .Fn log_stderr ، .Fn log_suspend ، .Fn change_winsize یا .Fn show_version اجرا می‌شود. این تابع تنها در صورتی فراخوانی می‌شود که نسخه درخواست شده باشد یا تابع .Fn check_policy افزونه خط‌مشی با موفقیت بازگشته باشد. در صورت موفقیت مقدار 1، در صورت شکست 0، در صورت بروز خطای عمومی \-1 و در صورت خطای نحوه استفاده \-2 را برمی‌گرداند. در حالت اخیر، .Nm sudo پیش از خروج پیامی درباره نحوه استفاده چاپ خواهد کرد. اگر خطایی رخ دهد، افزونه می‌تواند به صورت اختیاری تابع .Fn conversation یا .Fn sudo_plugin_printf را با .Dv SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری به کاربر ارائه دهد. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa version نسخه ارائه‌شده توسط .Nm sudo به افزونه امکان می‌دهد شماره نسخه اصلی و فرعی API افزونه پشتیبانی‌شده توسط .Nm sudo را تعیین کند. .It Fa conversation اشاره‌گری به تابع .Fn conversation که ممکن است توسط تابع .Fn Fa show_version جهت نمایش اطلاعات نسخه استفاده شود (به .Fn show_version در زیر مراجعه کنید). تابع .Fn conversation همچنین ممکن است برای نمایش پیام خطای اضافی به کاربر استفاده شود. تابع .Fn conversation در صورت موفقیت مقدار 0 و در صورت شکست \-1 بازمی‌گرداند. .It Fa sudo_plugin_printf اشاره‌گری به یک تابع به سبک .Fn printf Ns -style که ممکن است توسط تابع .Fn show_version جهت نمایش اطلاعات نسخه استفاده شود (به show_version در زیر مراجعه کنید). تابع .Fn sudo_plugin_printf همچنین می‌تواند برای نمایش پیام خطای اضافی به کاربر استفاده شود. تابع .Fn sudo_plugin_printf در صورت موفقیت تعداد نویسه‌های چاپ‌شده و در صورت شکست \-1 بازمی‌گرداند. .It Fa settings برداری از تنظیمات ارائه‌شده توسط کاربر برای .Nm sudo به شکل رشته‌های .Dq name=value . این بردار با اشاره‌گر .Dv NULL پایان می‌یابد. این تنظیمات مربوط به گزینه‌هایی هستند که کاربر هنگام اجرای .Nm sudo مشخص کرده است. بنابراین، آن‌ها تنها زمانی وجود خواهند داشت که گزینه متناظر در خط فرمان مشخص شده باشد. .Pp هنگام تجزیه .Fa settings ، افزونه باید بر اساس .Sy اولین علامت مساوی .Pq Ql = تفکیک را انجام دهد، چرا که فیلد .Em name هرگز خودش شامل علامت مساوی نخواهد بود، اما .Em value ممکن است باشد. .Pp برای فهرستی از تمامی تنظیمات ممکن، بخش .Sx Policy plugin API را ببینید. .It Fa user_info برداری از اطلاعات مربوط به کاربری که دستور را اجرا می‌کند به شکل رشته‌های .Dq name=value . این بردار با اشاره‌گر .Dv NULL پایان می‌یابد. .Pp هنگام تجزیه .Fa user_info ، افزونه باید بر اساس .Sy اولین علامت مساوی .Pq Ql = تفکیک را انجام دهد، چرا که فیلد .Em name هرگز خودش شامل مساوی نخواهد بود، اما .Em value ممکن است باشد. .Pp برای فهرستی از تمامی رشته‌های ممکن، بخش .Sx Policy plugin API را ببینید. .It Fa command_info برداری از اطلاعات توصیف‌کننده دستور در حال اجرا به شکل رشته‌های .Dq name=value . این بردار با اشاره‌گر .Dv NULL پایان می‌یابد. .Pp هنگام تجزیه .Fa command_info ، افزونه باید بر اساس .Sy اولین علامت مساوی .Pq Ql = تفکیک را انجام دهد، چرا که فیلد .Em name هرگز خودش شامل مساوی نخواهد بود، اما .Em value ممکن است باشد. .Pp برای فهرستی از تمامی رشته‌های ممکن، بخش .Sx Policy plugin API را ببینید. .It Fa argc تعداد عناصر موجود در .Fa argv ، بدون احتساب اشاره‌گر پایانی .Dv NULL . این مقدار می‌تواند صفر باشد، مانند زمانی که .Nm sudo با گزینه .Fl V فراخوانی می‌شود. .It Fa argv در صورت غیر .Dv NULL بودن .No ( non- Ns Dv NULL ) ، یک بردار آرگومان است که دستوری را که کاربر مایل به اجرای آن است توصیف می‌کند، به همان شکلی که به فراخوانی سیستمی .Xr execve 2 ارسال می‌گردد. .It Fa user_env محیط کاربر به شکل یک بردار پایان‌یافته با .Dv NULL از رشته‌های .Dq name=value . .Pp هنگام تجزیه .Fa user_env ، افزونه باید بر اساس .Sy اولین علامت مساوی .Pq Ql = تفکیک را انجام دهد، چرا که فیلد .Em name هرگز خودش شامل مساوی نخواهد بود، اما .Em value ممکن است باشد. .It Fa plugin_options هر رشته‌ای (غیر از کامنت) بلافاصله پس از مسیر افزونه، به عنوان آرگومان‌های افزونه تلقی می‌شود. این آرگومان‌ها در مرزهای فاصله خالی تفکیک شده و در قالب یک آرایه از رشته‌ها که با .Dv NULL خاتمه می‌یابد به افزونه ارسال می‌شوند. اگر هیچ آرگومانی مشخص نشده باشد، .Fa plugin_options اشاره‌گر .Dv NULL خواهد بود. .Pp پارامتر .Fa plugin_options تنها با شروع از نسخه 1.2 از API در دسترس است. یک افزونه .Sy باید پیش از استفاده از .Fa plugin_options ، نسخه API ارائه‌شده توسط بخش فرانت‌اند .Nm sudo را بررسی کند. عدم انجام این کار ممکن است منجر به از کار افتادن برنامه شود. .It Fa errstr اگر تابع .Fn open مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در .Fa errstr ذخیره کند. سپس فرانت‌اند .Nm sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمان فراخوانی تابع .Fn close افزونه معتبر بماند. .Pp پارامتر .Fa errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه .Sy باید پیش از استفاده از .Fa errstr ، نسخه API مشخص‌شده توسط بخش فرانت‌اند .Nm sudo را بررسی کند. عدم انجام این کار ممکن است منجر به از کار افتادن برنامه شود. .El .It Fa close .Bd -literal -compact void (*close)(int exit_status, int error); .Ed .Pp تابع .Fn close زمانی که کار .Nm sudo پایان یابد، اندکی پیش از خروج فراخوانی می‌شود. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa exit_status وضعیت خروج دستور، همان‌طور که توسط فراخوانی سیستمی .Xr wait 2 بازگردانده شده است، یا در صورتی که هیچ دستوری اجرا نشده باشد صفر است. اگر .Fa error غیر صفر باشد، مقدار .Fa exit_status تعریف‌نشده است. .It Fa error اگر دستور نتواند اجرا شود، این مقدار روی مقدار .Va errno تنظیم‌شده توسط فراخوانی سیستمی .Xr execve 2 تنظیم می‌شود. اگر دستور با موفقیت اجرا شده باشد، مقدار .Fa error صفر است. .El .It Fa show_version .Bd -literal -compact int (*show_version)(int verbose); .Ed .Pp تابع .Fn show_version زمانی توسط .Nm sudo فراخوانی می‌شود که کاربر گزینه .Fl V را مشخص کرده باشد. افزونه می‌تواند اطلاعات نسخه خود را از طریق تابع .Fn conversation یا .Fn sudo_plugin_printf با استفاده از .Dv SUDO_CONV_INFO_MSG به کاربر نمایش دهد. اگر کاربر اطلاعات دقیق نسخه را درخواست کند، پرچم .Fa verbose غیر صفر خواهد بود. .Pp در صورت موفقیت 1، در صورت شکست 0، در صورت بروز خطای عمومی \-1، یا اگر خطای نحوه استفاده وجود داشته باشد \-2 بازمی‌گرداند، هرچند مقدار بازگشتی در حال حاضر نادیده گرفته می‌شود. .It Fa log_ttyin .Bd -literal -compact int (*log_ttyin)(const char *buf, unsigned int len, const char **errstr); .Ed .Pp تابع .Fn log_ttyin هر زمان که داده‌ای از کاربر قابل خواندن باشد، اما پیش از انتقال آن به دستور در حال اجرا، فراخوانی می‌شود. این به افزونه امکان می‌دهد تا در صورت تمایل داده را رد کند (مثلاً اگر ورودی شامل محتوای ممنوعه باشد). اگر داده باید به دستور منتقل شود مقدار 1، اگر داده رد شود مقدار 0 (که دستور در حال اجرا را خاتمه می‌دهد)، یا در صورت بروز خطا مقدار \-1 بازمی‌گرداند. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa buf بافر حاوی ورودی کاربر. .It Fa len طول .Fa buf به بایت. .It Fa errstr اگر تابع .Fn log_ttyin مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در .Fa errstr ذخیره کند. سپس بخش فرانت‌اند .Nm sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمان فراخوانی تابع .Fn close افزونه معتبر بماند. .Pp پارامتر .Fa errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه .Sy باید پیش از استفاده از .Fa errstr ، نسخه API ارائه‌شده توسط بخش فرانت‌اند .Nm sudo را بررسی کند. عدم انجام این کار ممکن است منجر به از کار افتادن برنامه شود. .El .It Fa log_ttyout .Bd -literal -compact int (*log_ttyout)(const char *buf, unsigned int len, const char **errstr); .Ed .Pp تابع .Fn log_ttyout هر زمان که داده‌ای از دستور قابل خواندن باشد، اما پیش از نوشته شدن در ترمینال کاربر، فراخوانی می‌شود. این به افزونه اجازه می‌دهد تا در صورت تمایل داده را رد کند (مثلاً اگر خروجی شامل محتوای ممنوعه باشد). اگر داده باید به کاربر تحویل داده شود مقدار 1، اگر داده رد شود مقدار 0 (که دستور در حال اجرا را متوقف می‌کند)، یا در صورت بروز خطا مقدار \-1 بازمی‌گرداند. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa buf بافر حاوی خروجی دستور. .It Fa len طول .Fa buf به بایت. .It Fa errstr اگر تابع .Fn log_ttyout مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در .Fa errstr ذخیره کند. سپس بخش فرانت‌اند .Nm sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمان فراخوانی تابع .Fn close افزونه معتبر بماند. .Pp پارامتر .Fa errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه .Sy باید پیش از استفاده از .Fa errstr ، نسخه API ارائه‌شده توسط فرانت‌اند .Nm sudo را بررسی کند. عدم انجام این کار ممکن است منجر به خرابی برنامه شود. .El .It Fa log_stdin .Bd -literal -compact int (*log_stdin)(const char *buf, unsigned int len, const char **errstr); .Ed .Pp تابع .Fn log_stdin تنها در صورتی استفاده می‌شود که ورودی استاندارد مربوط به یک دستگاه tty نباشد. این تابع هر زمان که داده‌ای از ورودی استاندارد قابل خواندن باشد، اما پیش از انتقال آن به دستور در حال اجرا فراخوانی می‌شود. این به افزونه امکان می‌دهد در صورت تمایل داده را رد کند (مثلاً اگر ورودی شامل محتوای ممنوعه باشد). اگر داده باید به دستور ارسال شود مقدار 1، اگر داده رد شود مقدار 0 (که دستور در حال اجرا را متوقف می‌کند)، یا در صورت بروز خطا مقدار \-1 بازمی‌گرداند. .Pp آرگومان‌های تابع به شرح زیر است: .Bl -tag -width 4n .It Fa buf بافر حاوی ورودی کاربر. .It Fa len طول .Fa buf به بایت. .It Fa errstr اگر تابع .Fn log_stdin مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در .Fa errstr ذخیره کند. سپس بخش فرانت‌اند .Nm sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمان فراخوانی تابع .Fn close افزونه معتبر بماند. .Pp پارامتر .Fa errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه .Sy باید پیش از استفاده از .Fa errstr ، نسخه API ارائه‌شده توسط فرانت‌اند .Nm sudo را بررسی کند. عدم انجام این کار ممکن است منجر به خرابی برنامه شود. .El .It Fa log_stdout .Bd -literal -compact int (*log_stdout)(const char *buf, unsigned int len, const char **errstr); .Ed .Pp تابع .Fn log_stdout تنها در صورتی استفاده می‌شود که خروجی استاندارد به یک دستگاه tty مربوط نباشد. این تابع هر زمان که داده‌ای از دستور قابل خواندن باشد، اما پیش از نوشته شدن در خروجی استاندارد، فراخوانی می‌شود. این به افزونه امکان می‌دهد تا در صورت تمایل داده را رد کند (مثلاً اگر خروجی شامل محتوای ممنوعه باشد). اگر داده باید به کاربر تحویل شود مقدار 1، اگر داده رد شود مقدار 0 (که دستور در حال اجرا را خاتمه می‌دهد)، یا در صورت بروز خطا مقدار \-1 بازمی‌گرداند. .Pp آرگومان‌های تابع به شرح زیر است: .Bl -tag -width 4n .It Fa buf بافر حاوی خروجی دستور. .It Fa len طول .Fa buf به بایت. .It Fa errstr اگر تابع .Fn log_stdout مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در .Fa errstr ذخیره کند. سپس بخش فرانت‌اند .Nm sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمان فراخوانی تابع .Fn close افزونه معتبر بماند. .Pp پارامتر .Fa errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه .Sy باید پیش از استفاده از .Fa errstr ، نسخه API ارائه‌شده توسط فرانت‌اند .Nm sudo را بررسی کند. عدم انجام این کار ممکن است منجر به خرابی برنامه شود. .El .It Fa log_stderr .Bd -literal -compact int (*log_stderr)(const char *buf, unsigned int len, const char **errstr); .Ed .Pp تابع .Fn log_stderr تنها در صورتی استفاده می‌شود که خطای استاندارد به یک دستگاه tty مربوط نباشد. این تابع هر زمان که داده‌ای از دستور قابل خواندن باشد، اما پیش از نوشته شدن در خطای استاندارد، فراخوانی می‌شود. این به افزونه امکان می‌دهد تا در صورت تمایل داده را رد کند (مثلاً اگر خروجی شامل محتوای ممنوعه باشد). اگر داده باید به کاربر تحویل شود مقدار 1، اگر داده رد شود مقدار 0 (که دستور در حال اجرا را متوقف می‌کند)، یا در صورت بروز خطا مقدار \-1 بازمی‌گرداند. .Pp آرگومان‌های تابع به شرح زیر است: .Bl -tag -width 4n .It Fa buf بافر حاوی خروجی دستور. .It Fa len طول .Fa buf به بایت. .It Fa errstr اگر تابع .Fn log_stderr مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در .Fa errstr ذخیره کند. سپس بخش فرانت‌اند .Nm sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمان فراخوانی تابع .Fn close افزونه معتبر بماند. .Pp پارامتر .Fa errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه .Sy باید پیش از استفاده از .Fa errstr ، نسخه API ارائه‌شده توسط فرانت‌اند .Nm sudo را بررسی کند. عدم انجام این کار ممکن است منجر به خرابی برنامه شود. .El .It Fa register_hooks برای شرح .Fn register_hooks به بخش .Sx Policy plugin API مراجعه کنید. .It Fa deregister_hooks برای شرح .Fn deregister_hooks به بخش .Sx Policy plugin API مراجعه کنید. .It Fa change_winsize .Bd -literal -compact int (*change_winsize)(unsigned int lines, unsigned int cols, const char **errstr); .Ed .Pp تابع .Fn change_winsize هر زمان که اندازه پنجره ترمینال از مقادیر اولیه مشخص‌شده در فهرست .Fa user_info تغییر کند، فراخوانی می‌شود. در صورت بروز خطا \-1 بازمی‌گرداند که در این حالت تماس دیگری با .Fn change_winsize برقرار نخواهد شد، .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa lines تعداد خطوط (سطرها) در ترمینال تغییراندازه‌یافته. .It Fa cols تعداد ستون‌ها در ترمینال تغییراندازه‌یافته. .It Fa errstr اگر تابع .Fn change_winsize مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در .Fa errstr ذخیره کند. سپس بخش فرانت‌اند .Nm sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمان فراخوانی تابع .Fn close افزونه معتبر بماند. .Pp پارامتر .Fa errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه .Sy باید پیش از استفاده از .Fa errstr ، نسخه API ارائه‌شده توسط فرانت‌اند .Nm sudo را بررسی کند. عدم انجام این کار ممکن است منجر به خرابی برنامه شود. .El .It Fa log_suspend .Bd -literal -compact int (*log_suspend)(int signo, const char **errstr); .Ed .Pp تابع .Fn log_suspend هر زمان که دستوری معلق شده یا ازسرگرفته شود فراخوانی می‌شود. ثبت این اطلاعات، صرف‌نظر کردن از بازه زمانی تعلیق بودن دستور در زمان بازپخش یک نشست را امکان‌پذیر می‌سازد. در صورت بروز خطا \-1 بازمی‌گرداند که در این حالت تماس دیگری با .Fn log_suspend برقرار نخواهد شد، .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa signo سیگنالی که باعث معلق شدن دستور شده است، یا .Dv SIGCONT در صورتی که اجرای دستور ازسرگرفته شده باشد. .It Fa errstr اگر تابع .Fn log_suspend مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در .Fa errstr ذخیره کند. سپس بخش فرانت‌اند .Nm sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمان فراخوانی تابع .Fn close افزونه معتبر بماند. .Pp پارامتر .Fa errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه .Sy باید پیش از استفاده از .Fa errstr ، نسخه API ارائه‌شده توسط فرانت‌اند .Nm sudo را بررسی کند. عدم انجام این کار ممکن است منجر به خرابی برنامه شود. .It Fa event_alloc .Bd -literal -compact struct sudo_plugin_event * (*event_alloc)(void); .Ed .Pp تابع .Fn event_alloc برای تخصیص دادن یک .Vt struct sudo_plugin_event استفاده می‌شود که دسترسی به حلقه رویداد اصلی .Nm sudo را فراهم می‌کند. برخلاف سایر فیلدها، اشاره‌گر .Fn event_alloc توسط بخش فرانت‌اند .Nm sudo پر می‌شود، نه توسط افزونه. .Pp برای اطلاعات بیشتر درباره رویدادها، بخش .Sx Event API در زیر را ببینید. .Pp تابع .Fn event_alloc تنها با شروع از نسخه 1.15 از API در دسترس است. اگر فرانت‌اند .Nm sudo از نسخه 1.15 یا بالاتر API پشتیبانی نکند، .Fn event_alloc تنظیم نخواهد شد. .El .Pp .Em ماکروهای نسخه افزونه ورودی/خروجی (I/O Plugin Version Macros) .Pp مشابه موارد بخش .Sx Policy plugin API . .El .Ss "رابط افزونههای حسابرسی (Audit plugin API)" .Bd -literal /* Audit plugin close function status types. */ #define SUDO_PLUGIN_NO_STATUS 0 #define SUDO_PLUGIN_WAIT_STATUS 1 #define SUDO_PLUGIN_EXEC_ERROR 2 #define SUDO_PLUGIN_SUDO_ERROR 3 #define SUDO_AUDIT_PLUGIN 3 struct audit_plugin { unsigned int type; /* always SUDO_AUDIT_PLUGIN */ unsigned int version; /* always SUDO_API_VERSION */ int (*open)(unsigned int version, sudo_conv_t conversation, sudo_printf_t sudo_plugin_printf, char * const settings[], char * const user_info[], int submit_optind, char * const submit_argv[], char * const submit_envp[], char * const plugin_options[], const char **errstr); void (*close)(int status_type, int status); int (*accept)(const char *plugin_name, unsigned int plugin_type, char * const command_info[], char * const run_argv[], char * const run_envp[], const char **errstr); int (*reject)(const char *plugin_name, unsigned int plugin_type, const char *audit_msg, char * const command_info[], const char **errstr); int (*error)(const char *plugin_name, unsigned int plugin_type, const char *audit_msg, char * const command_info[], const char **errstr); int (*show_version)(int verbose); void (*register_hooks)(int version, int (*register_hook)(struct sudo_hook *hook)); void (*deregister_hooks)(int version, int (*deregister_hook)(struct sudo_hook *hook)); struct sudo_plugin_event * (*event_alloc)(void); } .Ed .Pp یک افزونه حسابرسی می‌تواند برای ثبت تلاش‌های موفق و ناموفق جهت اجرای .Nm sudo مستقل از خط‌مشی یا هر یک از افزونه‌های I/O استفاده شود. می‌توان چندین افزونه حسابرسی را در .Xr sudo.conf 5 مشخص کرد. .Pp یک .Vt struct audit_plugin دارای فیلدهای زیر است: .Bl -tag -width 4n .It Fa type فیلد .Fa type باید همیشه روی .Dv SUDO_AUDIT_PLUGIN تنظیم شود. .It Fa version فیلد .Fa version باید روی .Dv SUDO_API_VERSION تنظیم شود. .Pp این به .Nm sudo امکان می‌دهد تا نسخه API که افزونه بر اساس آن ساخته شده است را تعیین کند. .It Fa open .Bd -literal -compact int (*open)(unsigned int version, sudo_conv_t conversation, sudo_printf_t sudo_plugin_printf, char * const settings[], char * const user_info[], int submit_optind, char * const submit_argv[], char * const submit_envp[], char * const plugin_options[], const char **errstr); .Ed .Pp تابع .Fn open حسابرسی، پیش از هر تابع API افزونه دیگر .Nm sudo اجرا می‌شود. این کار امکان حسابرسی خرابی‌ها در سایر افزونه‌ها را ممکن می‌سازد. این تابع در صورت موفقیت مقدار 1، در صورت شکست 0، در صورت بروز یک خطای عمومی \-1، یا در صورت بروز خطای نحوه استفاده مقدار \-2 را برمی‌گرداند. در حالت اخیر، .Nm sudo پیش از خروج پیامی درباره نحوه استفاده چاپ خواهد کرد. در صورت بروز خطا، افزونه می‌تواند به صورت اختیاری تابع .Fn conversation یا .Fn plugin_printf را با .Dv SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای اضافی را به کاربر نمایش دهد. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa version نسخه ارسال‌شده توسط .Nm sudo به افزونه امکان می‌دهد تا شماره نسخه اصلی و فرعی API افزونه پشتیبانی‌شده توسط .Nm sudo را تعیین کند. .It Fa conversation اشاره‌گری به تابع .Fn conversation که ممکن است توسط تابع .Fn show_version برای نمایش اطلاعات نسخه استفاده شود (به .Fn show_version در زیر مراجعه کنید). همچنین تابع .Fn conversation می‌تواند برای نمایش پیام خطای اضافی به کاربر استفاده شود. تابع .Fn conversation در صورت موفقیت مقدار 0 و در صورت شکست مقدار \-1 را برمی‌گرداند. .It Fa plugin_printf اشاره‌گری به تابعی به سبک .Fn printf که ممکن است توسط تابع .Fn show_version برای نمایش اطلاعات نسخه استفاده شود (به .Fn show_version در زیر مراجعه کنید). همچنین تابع .Fn plugin_printf می‌تواند برای نمایش پیام خطای اضافی به کاربر استفاده شود. تابع .Fn plugin_printf در صورت موفقیت تعداد کاراکترهای چاپ‌شده و در صورت شکست مقدار \-1 را برمی‌گرداند. .It Fa settings برداری از تنظیمات ارائه‌شده توسط کاربر برای .Nm sudo در قالب رشته‌های .Dq name=value . این بردار با یک اشاره‌گر .Dv NULL خاتمه می‌یابد. این تنظیمات متناظر با گزینه‌هایی هستند که کاربر هنگام اجرای .Nm sudo مشخص کرده است. به این ترتیب، آن‌ها تنها زمانی وجود خواهند داشت که گزینه متناظر در خط فرمان مشخص شده باشد. .Pp هنگام تجزیه کردن .Fa settings Ns ، افزونه باید آن را بر اساس .Sy اولین علامت مساوی .Pq Ql = تفکیک کند، زیرا خود فیلد .Em name هرگز شامل مساوی نخواهد بود، اما .Em value ممکن است شامل آن باشد. .Pp برای فهرستی از تمام تنظیمات ممکن، به بخش .Sx Policy plugin API مراجعه کنید. .It Fa user_info برداری از اطلاعات درباره کاربر اجراکننده دستور در قالب رشته‌های .Dq name=value . این بردار با یک اشاره‌گر .Dv NULL خاتمه می‌یابد. .Pp هنگام تجزیه کردن .Fa user_info Ns ، افزونه باید آن را بر اساس .Sy اولین علامت مساوی .Pq Ql = تفکیک کند، زیرا خود فیلد .Em name هرگز شامل مساوی نخواهد بود، اما .Em value ممکن است شامل آن باشد. .Pp برای فهرستی از تمام رشته‌های ممکن، به بخش .Sx Policy plugin API مراجعه کنید. .It Fa submit_optind اندیس درون .Fa submit_argv که متناظر با اولین ورودی است که یک گزینه خط فرمان نیست. اگر .Fa submit_argv تنها شامل گزینه‌ها باشد، که ممکن است در مورد گزینه‌های .Fl l یا .Fl v رخ دهد، .Fa submit_argv Ns [ Fa submit_optind ] به اشاره‌گر NULL ارزیابی می‌شود. .It Fa submit_argv بردار آرگومانی که .Nm sudo با آن فراخوانی شده بود، شامل تمام گزینه‌های خط فرمان. از آرگومان .Fa submit_optind می‌توان برای تعیین انتهای گزینه‌های خط فرمان استفاده کرد. .It Fa submit_envp محیط کاربر فراخواننده در قالب برداری از رشته‌های .Dq name=value که با .Dv NULL خاتمه می‌یابد. .Pp هنگام تجزیه کردن .Fa submit_envp Ns ، افزونه باید آن را بر اساس .Sy اولین علامت مساوی .Pq Ql = تفکیک کند، زیرا خود فیلد .Em name هرگز شامل مساوی نخواهد بود، اما .Em value ممکن است شامل آن باشد. .It Fa plugin_options هر رشته (غیر از کامنت) که بلافاصله پس از مسیر افزونه قرار گیرد به عنوان آرگومان‌های افزونه در نظر گرفته می‌شود. این آرگومان‌ها بر اساس مرز فاصله‌های خالی تفکیک شده و در قالب آرایه‌ای از رشته‌ها با خاتمه‌دهنده .Dv NULL به افزونه ارسال می‌شوند. اگر هیچ آرگومانی مشخص نشده باشد، .Fa plugin_options برابر با اشاره‌گر .Dv NULL خواهد بود. .It Fa errstr اگر تابع .Fn open مقداری غیر از 1 برگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا را در .Fa errstr ذخیره کند. سپس بخش فرانت‌اند .Nm sudo این مقدار را به تمام افزونه‌های حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمانی که تابع .Fn close افزونه فراخوانی شود، معتبر باقی بماند. .El .It Fa close .Bd -literal -compact void (*close)(int status_type, int status); .Ed .Pp تابع .Fn close زمانی که کار .Nm sudo تمام می‌شود، اندکی پیش از خروج آن فراخوانی می‌گردد. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa status_type نوع وضعیتی که ارسال می‌شود. یکی از مقادیر .Dv SUDO_PLUGIN_NO_STATUS ، .Dv SUDO_PLUGIN_WAIT_STATUS ، .Dv SUDO_PLUGIN_EXEC_ERROR یا .Dv SUDO_PLUGIN_SUDO_ERROR . .It Fa status بسته به مقدار .Fa status_type ، این مقدار یا نادیده گرفته می‌شود، یا وضعیت خروج دستور برگشتی توسط فراخوانی سیستمی .Xr wait 2 ، یا مقدار .Va errno تنظیم‌شده توسط فراخوانی سیستمی .Xr execve 2 ، یا مقدار .Va errno ناشی از بروز خطا در فرانت‌اند .Nm sudo است. .El .It Fa accept .Bd -literal -compact int (*accept)(const char *plugin_name, unsigned int plugin_type, char * const command_info[], char * const run_argv[], char * const run_envp[], const char **errstr); .Ed .Pp تابع .Fn accept زمانی فراخوانی می‌شود که یک دستور یا کنش توسط یک افزونه خط‌مشی یا تأیید پذیرفته شود. آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa plugin_name نام افزونه‌ای که دستور را پذیرفته است یا .Dq sudo برای فرانت‌اند .Nm sudo . .It Fa plugin_type نوع افزونه‌ای که دستور را پذیرفته است، که در حال حاضر یکی از مقادیر .Dv SUDO_POLICY_PLUGIN ، .Dv SUDO_POLICY_APPROVAL یا .Dv SUDO_FRONT_END است. تابع .Fn accept چندین بار فراخوانی می‌شود \(en یک بار به ازای هر افزونه خط‌مشی یا تأیید که موفق شود و یک بار برای فرانت‌اند sudo. هنگامی که به نمایندگی از فرانت‌اند sudo فراخوانی شود، .Fa command_info ممکن است شامل اطلاعاتی از یک افزونه ثبت وقایع I/O نیز باشد. .Pp معمولاً یک افزونه حسابرسی یا علاقه‌مند به وضعیت پذیرش از سوی فرانت‌اند .Nm sudo است یا از سوی افزونه‌های مختلف خط‌مشی و تأیید، اما نه هر دوی آن‌ها. این امکان وجود دارد که افزونه خط‌مشی دستوری را بپذیرد که بعداً توسط یک افزونه تأیید رد شود، که در این صورت هر .Em دو تابع .Fn accept و .Fn reject افزونه حسابرسی فراخوانی خواهند شد. .It Fa command_info برداری اختیاری از اطلاعات توصیف‌کننده دستور در حال اجرا در قالب رشته‌های .Dq name=value . این بردار با یک اشاره‌گر .Dv NULL خاتمه می‌یابد. .Pp هنگام تجزیه کردن .Fa command_info Ns ، افزونه باید آن را بر اساس .Sy اولین علامت مساوی .Pq Ql = تفکیک کند، زیرا خود فیلد .Em name هرگز شامل مساوی نخواهد بود، اما .Em value ممکن است شامل آن باشد. .Pp برای فهرستی از تمام رشته‌های ممکن، به بخش .Sx Policy plugin API مراجعه کنید. .It Fa run_argv یک بردار آرگومان خاتمه‌یافته با .Dv NULL که دستوری را توصیف می‌کند که قرار است اجرا شود، در همان قالبی که به فراخوانی سیستمی .Xr execve 2 ارسال می‌گردد. .It Fa run_envp محیطی که دستور با آن اجرا خواهد شد در قالب برداری از رشته‌های .Dq name=value که با .Dv NULL خاتمه می‌یابد. .Pp هنگام تجزیه کردن .Fa run_envp Ns ، افزونه باید آن را بر اساس .Sy اولین علامت مساوی .Pq Ql = تفکیک کند، زیرا خود فیلد .Em name هرگز شامل مساوی نخواهد بود، اما .Em value ممکن است شامل آن باشد. .It Fa errstr اگر تابع .Fn accept مقداری غیر از 1 برگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا را در .Fa errstr ذخیره کند. سپس بخش فرانت‌اند .Nm sudo این مقدار را به تمام افزونه‌های حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمانی که تابع .Fn close افزونه فراخوانی شود، معتبر باقی بماند. .El .It Fa reject .Bd -literal -compact int (*reject)(const char *plugin_name, unsigned int plugin_type, const char *audit_msg, char * const command_info[], const char **errstr); .Ed .Pp تابع .Fn reject زمانی فراخوانی می‌شود که یک دستور یا کنش توسط یک افزونه رد شود. آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa plugin_name نام افزونه‌ای که دستور را رد کرده است. .It Fa plugin_type نوع افزونه‌ای که دستور را رد کرده است، که در حال حاضر یکی از مقادیر .Dv SUDO_POLICY_PLUGIN ، .Dv SUDO_APPROVAL_PLUGIN یا .Dv SUDO_IO_PLUGIN است. .Pp برخلاف تابع .Fn accept Ns ، تابع .Fn reject به نمایندگی از فرانت‌اند .Nm sudo فراخوانی نمی‌شود. .It Fa audit_msg رشته‌ای اختیاری در توصیف دلیل رد شدن دستور توسط افزونه. اگر افزونه دلیلی ارائه نداده باشد، .Fa audit_msg برابر با اشاره‌گر .Dv NULL خواهد بود. .It Fa command_info برداری اختیاری از اطلاعات توصیف‌کننده دستور در حال اجرا در قالب رشته‌های .Dq name=value . این بردار با یک اشاره‌گر .Dv NULL خاتمه می‌یابد. .Pp هنگام تجزیه کردن .Fa command_info Ns ، افزونه باید آن را بر اساس .Sy اولین علامت مساوی .Pq Ql = تفکیک کند، زیرا خود فیلد .Em name هرگز شامل مساوی نخواهد بود، اما .Em value ممکن است شامل آن باشد. .Pp برای فهرستی از تمام رشته‌های ممکن، به بخش .Sx Policy plugin API مراجعه کنید. .It Fa errstr اگر تابع .Fn reject مقداری غیر از 1 برگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا را در .Fa errstr ذخیره کند. سپس بخش فرانت‌اند .Nm sudo این مقدار را به تمام افزونه‌های حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمانی که تابع .Fn close افزونه فراخوانی شود، معتبر باقی بماند. .El .It Fa error .Bd -literal -compact int (*error)(const char *plugin_name, unsigned int plugin_type, const char *audit_msg, char * const command_info[], const char **errstr); .Ed .Pp تابع .Fn error زمانی فراخوانی می‌شود که یک افزونه یا فرانت‌اند .Nm sudo خطایی را برگرداند. آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa plugin_name نام افزونه‌ای که خطا را ایجاد کرده است یا .Dq sudo برای فرانت‌اند .Nm sudo . .It Fa plugin_type نوع افزونه‌ای که خطا را ایجاد کرده است، یا .Dv SUDO_FRONT_END برای فرانت‌اند .Nm sudo . .It Fa audit_msg رشته‌ای اختیاری در توصیف خطای افزونه. اگر افزونه توضیحی ارائه نداده باشد، .Fa audit_msg برابر با اشاره‌گر .Dv NULL خواهد بود. .It Fa command_info برداری اختیاری از اطلاعات توصیف‌کننده دستور در حال اجرا در قالب رشته‌های .Dq name=value . این بردار با یک اشاره‌گر .Dv NULL خاتمه می‌یابد. .Pp هنگام تجزیه کردن .Fa command_info Ns ، افزونه باید آن را بر اساس .Sy اولین علامت مساوی .Pq Ql = تفکیک کند، زیرا خود فیلد .Em name هرگز شامل مساوی نخواهد بود، اما .Em value ممکن است شامل آن باشد. .Pp برای فهرستی از تمام رشته‌های ممکن، به بخش .Sx Policy plugin API مراجعه کنید. .It Fa errstr اگر تابع .Fn error مقداری غیر از 1 برگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا را در .Fa errstr ذخیره کند. سپس بخش فرانت‌اند .Nm sudo این مقدار را به تمام افزونه‌های حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمانی که تابع .Fn close افزونه فراخوانی شود، معتبر باقی بماند. .El .It Fa show_version .Bd -literal -compact int (*show_version)(int verbose); .Ed .Pp تابع .Fn show_version توسط .Nm sudo زمانی فراخوانی می‌شود که کاربر گزینه .Fl V را مشخص کند. افزونه می‌تواند اطلاعات نسخه خود را از طریق تابع .Fn conversation یا .Fn plugin_printf با استفاده از .Dv SUDO_CONV_INFO_MSG به کاربر نمایش دهد. اگر کاربر اطلاعات نسخه همراه با جزئیات را درخواست کند، فلگ verbose تنظیم خواهد شد. .Pp در صورت موفقیت مقدار 1، در صورت شکست 0، در صورت بروز یک خطای عمومی \-1، یا در صورت بروز خطای نحوه استفاده مقدار \-2 را برمی‌گرداند، اگرچه مقدار بازگشتی در حال حاضر نادیده گرفته می‌شود. .It Fa register_hooks برای توضیحات مربوط به .Fn register_hooks به بخش .Sx Policy plugin API مراجعه کنید. .It Fa deregister_hooks برای توضیحات مربوط به .Fn deregister_hooks به بخش .Sx Policy plugin API مراجعه کنید. .It Fa event_alloc .Bd -literal -compact struct sudo_plugin_event * (*event_alloc)(void); .Ed .Pp تابع .Fn event_alloc برای تخصیص یک .Vt struct sudo_plugin_event استفاده می‌شود که امکان دسترسی به حلقه رویداد اصلی .Nm sudo را فراهم می‌کند. برخلاف سایر فیلدها، اشاره‌گر .Fa event_alloc توسط فرانت‌اند .Nm sudo پر می‌شود، نه توسط افزونه. .Pp برای کسب اطلاعات بیشتر درباره رویدادها، به بخش .Sx Event API در زیر مراجعه کنید. .Pp تابع .Fn event_alloc تنها از نسخه API 1.17 به بعد در دسترس است. اگر فرانت‌اند .Nm sudo از نسخه API 1.17 یا بالاتر پشتیبانی نکند، .Fn event_alloc تنظیم نخواهد شد. .El .Ss "رابط افزونههای تأیید (Approval plugin API)" .Bd -literal struct approval_plugin { #define SUDO_APPROVAL_PLUGIN 4 unsigned int type; /* always SUDO_APPROVAL_PLUGIN */ unsigned int version; /* always SUDO_API_VERSION */ int (*open)(unsigned int version, sudo_conv_t conversation, sudo_printf_t sudo_plugin_printf, char * const settings[], char * const user_info[], int submit_optind, char * const submit_argv[], char * const submit_envp[], char * const plugin_options[], const char **errstr); void (*close)(void); int (*check)(char * const command_info[], char * const run_argv[], char * const run_envp[], const char **errstr); int (*show_version)(int verbose); }; .Ed .Pp یک افزونه تأیید می‌تواند برای اعمال محدودیت‌های اضافی پس از پذیرفته شدن دستور توسط افزونه خط‌مشی به کار رود. برخلاف سایر انواع افزونه‌ها، این افزونه تا زمان تکمیل دستور باز نمی‌ماند. افزونه پیش از فراخوانی .Fn check یا .Fn show_version باز می‌شود و اندکی پس از آن بسته می‌شود (توابع افزونه حسابرسی باید پیش از بسته شدن افزونه فراخوانی شوند). می‌توان چندین افزونه تأیید را در .Xr sudo.conf 5 مشخص کرد. .Pp ساختار .Vt struct approval_plugin دارای فیلدهای زیر است: .Bl -tag -width 4n .It Fa type فیلد .Fa type باید همیشه روی .Dv SUDO_APPROVAL_PLUGIN تنظیم شود. .It Fa version فیلد .Fa version باید روی .Dv SUDO_API_VERSION تنظیم شود. .Pp این به .Nm sudo امکان می‌دهد نسخه API که افزونه بر اساس آن ساخته شده است را تشخیص دهد. .It Fa open .Bd -literal -compact int (*open)(unsigned int version, sudo_conv_t conversation, sudo_printf_t sudo_plugin_printf, char * const settings[], char * const user_info[], int submit_optind, char * const submit_argv[], char * const submit_envp[], char * const plugin_options[], const char **errstr); .Ed .Pp تابع .Fn open تأیید بلافاصله پیش از فراخوانی توابع .Fn check یا .Fn show_version افزونه اجرا می‌شود. این تابع تنها در صورتی فراخوانی می‌شود که نسخه درخواست شده باشد یا اینکه تابع .Fn check_policy افزونه خط‌مشی با موفقیت بازگشته باشد. این تابع در صورت موفقیت مقدار 1، در صورت شکست 0، در صورت بروز خطای عمومی مقدار \-1 یا در صورت خطای نحوه استفاده مقدار \-2 را بازمی‌گرداند. در حالت آخر، .Nm sudo پیش از خروج یک پیام نحوه استفاده را چاپ خواهد کرد. اگر خطایی رخ دهد، افزونه می‌تواند به صورت اختیاری تابع .Fn conversation یا .Fn plugin_printf را با .Dv SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری را به کاربر نمایش دهد. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa version نسخه ارسال‌شده توسط .Nm sudo به افزونه امکان می‌دهد شماره نسخه اصلی (major) و فرعی (minor) رابط API افزونه را که توسط .Nm sudo پشتیبانی می‌شود، تشخیص دهد. .It Fa conversation اشاره‌گری به تابع .Fn conversation که می‌تواند توسط افزونه برای تعامل با کاربر استفاده شود (برای جزئیات به .Sx Conversation API مراجعه کنید). در صورت موفقیت 0 و در صورت شکست \-1 را بازمی‌گرداند. .It Fa plugin_printf اشاره‌گری به یک تابع به سبک .Fn printf که می‌تواند برای نمایش پیام‌های اطلاعاتی یا خطا استفاده شود (برای جزئیات به .Sx Conversation API مراجعه کنید). در صورت موفقیت تعداد نویسه‌های چاپ‌شده و در صورت شکست \-1 را بازمی‌گرداند. .It Fa settings برداری از تنظیمات ارائه‌شده توسط کاربر برای .Nm sudo به شکل رشته‌های .Dq name=value . این بردار با یک اشاره‌گر .Dv NULL خاتمه می‌یابد. این تنظیمات با گزینه‌هایی مطابقت دارند که کاربر هنگام اجرای .Nm sudo مشخص کرده است. به این ترتیب، آن‌ها تنها زمانی وجود خواهند داشت که گزینه متناظر در خط فرمان مشخص شده باشد. .Pp هنگام تجزیه .Fa settings ، افزونه باید رشته را بر اساس .Sy اولین علامت مساوی .Pq Ql = جدا کند، زیرا خود فیلد .Em name هرگز شامل علامت مساوی نخواهد بود اما .Em value ممکن است باشد. .Pp برای فهرستی از تمام تنظیمات ممکن به بخش .Sx Policy plugin API مراجعه کنید. .It Fa user_info برداری از اطلاعات مربوط به کاربری که دستور را اجرا می‌کند به شکل رشته‌های .Dq name=value . این بردار با یک اشاره‌گر .Dv NULL خاتمه می‌یابد. .Pp هنگام تجزیه .Fa user_info ، افزونه باید رشته را بر اساس .Sy اولین علامت مساوی .Pq Ql = جدا کند، زیرا خود فیلد .Em name هرگز شامل علامت مساوی نخواهد بود اما .Em value ممکن است باشد. .Pp برای فهرستی از تمام رشته‌های ممکن به بخش .Sx Policy plugin API مراجعه کنید. .It Fa submit_optind اندیس در .Fa submit_argv که به اولین مدخلی مربوط می‌شود که یک گزینه خط فرمان نیست. اگر .Fa submit_argv فقط شامل گزینه‌ها باشد، که ممکن است در مورد گزینه‌های .Fl l یا .Fl v صادق باشد، .Fa submit_argv Ns [ Fa submit_optind ] به اشاره‌گر NULL ارزیابی می‌شود. .It Fa submit_argv بردار آرگومانی که .Nm sudo با آن فراخوانی شده است، شامل تمامی گزینه‌های خط فرمان. آرگومان .Fa submit_optind می‌تواند برای تعیین پایان گزینه‌های خط فرمان استفاده شود. .It Fa submit_envp محیط کاربری فراخواننده به صورت یک بردار خاتمه‌یافته با .Dv NULL از رشته‌های .Dq name=value . .Pp هنگام تجزیه .Fa submit_envp ، افزونه باید رشته را بر اساس .Sy اولین علامت مساوی .Pq Ql = جدا کند، زیرا خود فیلد .Em name هرگز شامل علامت مساوی نخواهد بود اما .Em value ممکن است باشد. .It Fa plugin_options هر رشته (غیر کامنت) بلافاصله پس از مسیر افزونه به عنوان آرگومان‌های افزونه در نظر گرفته می‌شود. این آرگومان‌ها در مرزهای فاصله خالی (whitespace) جدا شده و در قالب یک آرایه از رشته‌های خاتمه‌یافته با .Dv NULL به افزونه ارسال می‌شوند. اگر هیچ آرگومانی مشخص نشده باشد، .Fa plugin_options اشاره‌گر .Dv NULL خواهد بود. .It Fa errstr اگر تابع .Fn open مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی را در توصیف شکست یا خطا در .Fa errstr ذخیره کند. سپس بخش جلویی (front-end) .Nm sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمان فراخوانی تابع .Fn close افزونه معتبر باقی بماند. .El .It Fa close .Bd -literal -compact void (*close)(void); .Ed .Pp تابع .Fn close پس از فراخوانی توابع .Fn check یا .Fn show_version افزونه تأیید، فراخوانی می‌شود. این تابع هیچ آرگومانی دریافت نمی‌کند. تابع .Fn close معمولاً برای پاک‌سازی‌های خاص افزونه، مانند آزادسازی اشیاء حافظه تخصیص‌یافته توسط افزونه، استفاده می‌شود. اگر افزونه نیازی به پاک‌سازی نداشته باشد، .Fn close می‌تواند روی اشاره‌گر .Dv NULL تنظیم شود. .It Fa check .Bd -literal -compact int (*check)(char * const command_info[], char * const run_argv[], char * const run_envp[], const char **errstr); .Ed .Pp تابع .Fn check تأیید پس از تابع .Fn check_policy افزونه خط‌مشی و پیش از هر افزونه ثبت وقایع I/O اجرا می‌شود. اگر چندین افزونه تأیید بارگذاری شده باشند، همه آن‌ها باید موفقیت‌آمیز باشند تا اجرای دستور مجاز شود. این تابع در صورت موفقیت مقدار 1، در صورت شکست 0، در صورت بروز خطای عمومی مقدار \-1 یا در صورت خطای نحوه استفاده مقدار \-2 را بازمی‌گرداند. در حالت آخر، .Nm sudo پیش از خروج یک پیام نحوه استفاده را چاپ خواهد کرد. اگر خطایی رخ دهد، افزونه می‌تواند به صورت اختیاری تابع .Fn conversation یا .Fn plugin_printf را با .Dv SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری را به کاربر ارائه دهد. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa command_info برداری از اطلاعات توصیف‌کننده دستور در حال اجرا به شکل رشته‌های .Dq name=value . این بردار با یک اشاره‌گر .Dv NULL خاتمه می‌یابد. .Pp هنگام تجزیه .Fa command_info ، افزونه باید رشته را بر اساس .Sy اولین علامت مساوی .Pq Ql = جدا کند، زیرا خود فیلد .Em name هرگز شامل علامت مساوی نخواهد بود اما .Em value ممکن است باشد. .Pp برای فهرستی از تمام رشته‌های ممکن به بخش .Sx Policy plugin API مراجعه کنید. .It Fa run_argv یک بردار آرگومان خاتمه‌یافته با .Dv NULL که دستوری را توصیف می‌کند که اجرا خواهد شد، به همان شکلی که به فراخوانی سیستمی .Xr execve 2 ارسال می‌شود. .It Fa run_envp محیطی که دستور با آن اجرا خواهد شد به شکل یک بردار خاتمه‌یافته با .Dv NULL از رشته‌های .Dq name=value . .Pp هنگام تجزیه .Fa run_envp ، افزونه باید رشته را بر اساس .Sy اولین علامت مساوی .Pq Ql = جدا کند، زیرا خود فیلد .Em name هرگز شامل علامت مساوی نخواهد بود اما .Em value ممکن است باشد. .It Fa errstr اگر تابع .Fn open مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی را در توصیف شکست یا خطا در .Fa errstr ذخیره کند. سپس بخش جلویی .Nm sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در .Fa errstr باید تا زمان فراخوانی تابع .Fn close افزونه معتبر باقی بماند. .El .It Fa show_version .Bd -literal -compact int (*show_version)(int verbose); .Ed .Pp تابع .Fn show_version توسط .Nm sudo هنگامی که کاربر گزینه .Fl V را مشخص کند فراخوانی می‌شود. افزونه می‌تواند اطلاعات نسخه خود را از طریق تابع .Fn conversation یا .Fn plugin_printf با استفاده از .Dv SUDO_CONV_INFO_MSG به کاربر نمایش دهد. اگر کاربر اطلاعات تفصیلی نسخه را درخواست کند، فلگ verbose تنظیم خواهد شد. .Pp در صورت موفقیت مقدار 1، در صورت شکست 0، در صورت بروز خطای عمومی مقدار \-1 یا در صورت خطای نحوه استفاده مقدار \-2 را بازمی‌گرداند، اگرچه مقدار بازگشتی در حال حاضر نادیده گرفته می‌شود. .El .Ss "کنترلکنندههای سیگنال (Signal handlers)" بخش جلویی (front-end) .Nm sudo کنترل‌کننده‌های سیگنال پیش‌فرض را برای به دام انداختن سیگنال‌های متداول در حین اجرای توابع افزونه نصب می‌کند. سیگنال‌های زیر پیش از اجرای دستور به طور پیش‌فرض به دام انداخته می‌شوند: .Pp .Bl -bullet -compact -width 1n .It .Dv SIGALRM .It .Dv SIGHUP .It .Dv SIGINT .It .Dv SIGPIPE .It .Dv SIGQUIT .It .Dv SIGTERM .It .Dv SIGTSTP .It .Dv SIGUSR1 .It .Dv SIGUSR2 .El .Pp اگر پیش از اجرای دستور یک سیگنال کشنده (fatal signal) دریافت شود، .Nm sudo تابع .Fn close افزونه را با وضعیت خروج 128 به اضافه مقدار سیگنال دریافت‌شده فراخوانی می‌کند. این امر برای افزونه‌هایی که چنین اطلاعاتی را در تابع .Fn close خود ثبت می‌کنند، امکان ثبت یکدست وقایع دستوراتی که با سیگنال خاتمه یافته‌اند را فراهم می‌سازد. یک استثنا در این مورد .Dv SIGPIPE است که تا زمان اجرای دستور نادیده گرفته می‌شود. .Pp یک افزونه می‌تواند به طور موقت کنترل‌کننده‌های سیگنال خود را نصب کند اما باید پیش از بازگشت تابع افزونه، کنترل‌کننده اصلی را بازیابی نماید. .Ss "رابط توابع هوک (Hook function API)" با شروع از نسخه 1.2 رابط API افزونه، امکان نصب هوک‌ها (قلاب‌ها) برای توابع خاصی که توسط بخش جلویی .Nm sudo فراخوانی می‌شوند وجود دارد. .Pp در حال حاضر، تنها هوک‌های پشتیبانی‌شده مربوط به مدیریت متغیرهای محیطی هستند. هوک‌ها می‌توانند برای رهگیری تلاش‌ها به منظور دریافت، تنظیم یا حذف متغیرهای محیطی استفاده شوند تا این تغییرات در نسخه محیطی که برای اجرای یک دستور به کار می‌رود منعکس شوند. نسخه‌های آتی API از قلاب کردن عملکردهای داخلی بخش جلویی .Nm sudo نیز پشتیبانی خواهند کرد. .Pp .Em "ساختار هوک (Hook structure)" .Pp هوک‌ها در .Nm sudo توسط ساختار زیر توصیف می‌شوند: .Bd -literal typedef int (*sudo_hook_fn_t)(); struct sudo_hook { unsigned int hook_version; unsigned int hook_type; sudo_hook_fn_t hook_fn; void *closure; }; .Ed .Pp یک .Vt struct sudo_hook دارای فیلدهای زیر است: .Bl -tag -width 4n .It Fa hook_version فیلد .Fa hook_version باید روی .Dv SUDO_HOOK_VERSION تنظیم شود. .It Fa hook_type فیلد .Fa hook_type می‌تواند یکی از انواع هوک پشتیبانی‌شده زیر باشد: .Bl -tag -width 4n .It Dv SUDO_HOOK_SETENV تابع .Xr setenv 3 کتابخانه C. هر هوک ثبت‌شده پیش از پیاده‌سازی کتابخانه C اجرا خواهد شد. فیلد .Fa hook_fn باید تابعی باشد که با تعاریف typedef زیر مطابقت داشته باشد: .Bd -literal typedef int (*sudo_hook_fn_setenv_t)(const char *name, const char *value, int overwrite, void *closure); .Ed .Pp اگر هوک ثبت‌شده با typedef مطابقت نداشته باشد، نتایج نامشخص خواهد بود. .It Dv SUDO_HOOK_UNSETENV تابع .Xr unsetenv 3 کتابخانه C. هر هوک ثبت‌شده پیش از پیاده‌سازی کتابخانه C اجرا خواهد شد. فیلد .Fa hook_fn باید تابعی باشد که با تعاریف typedef زیر مطابقت داشته باشد: .Bd -literal typedef int (*sudo_hook_fn_unsetenv_t)(const char *name, void *closure); .Ed .It Dv SUDO_HOOK_GETENV تابع .Xr getenv 3 کتابخانه C. هر هوک ثبت‌شده پیش از پیاده‌سازی کتابخانه C اجرا خواهد شد. فیلد .Fa hook_fn باید تابعی باشد که با تعاریف typedef زیر مطابقت داشته باشد: .Bd -literal typedef int (*sudo_hook_fn_getenv_t)(const char *name, char **value, void *closure); .Ed .Pp اگر هوک ثبت‌شده با typedef مطابقت نداشته باشد، نتایج نامشخص خواهد بود. .It Dv SUDO_HOOK_PUTENV تابع .Xr putenv 3 کتابخانه C. هر هوک ثبت‌شده پیش از پیاده‌سازی کتابخانه C اجرا خواهد شد. فیلد .Fa hook_fn باید تابعی باشد که با تعاریف typedef زیر مطابقت داشته باشد: .Bd -literal typedef int (*sudo_hook_fn_putenv_t)(char *string, void *closure); .Ed .Pp اگر هوک ثبت‌شده با typedef مطابقت نداشته باشد، نتایج نامشخص خواهد بود. .El .It Fa hook_fn .Bd -literal -compact sudo_hook_fn_t hook_fn; .Ed .Pp فیلد .Fa hook_fn باید روی پیاده‌سازی هوک افزونه تنظیم شود. آرگومان‌های واقعی تابع بسته به .Fa hook_type متفاوت خواهند بود (به .Fa hook_type در بالا مراجعه کنید). در تمام موارد، فیلد .Fa closure از .Vt struct sudo_hook به عنوان آخرین پارامتر تابع ارسال می‌شود. این می‌تواند برای ارسال داده‌های دلخواه به پیاده‌سازی هوک افزونه استفاده شود. .Pp مقدار بازگشتی تابع می‌تواند یکی از موارد زیر باشد: .Bl -tag -width 4n .It Dv SUDO_HOOK_RET_ERROR تابع هوک با خطا مواجه شد. .It Dv SUDO_HOOK_RET_NEXT هوک بدون خطا تکمیل شد، به هوک بعدی بروید (شامل پیاده‌سازی سیستم در صورت امکان). به عنوان مثال، یک هوک .Xr getenv 3 اگر متغیر مشخص‌شده در نسخه اختصاصی محیط یافت نشود، ممکن است مقدار .Dv SUDO_HOOK_RET_NEXT را بازگرداند. .It Dv SUDO_HOOK_RET_STOP هوک بدون خطا تکمیل شد، پردازش هوک‌ها برای این فراخوانی متوقف شود. این می‌تواند برای جایگزینی پیاده‌سازی سیستم استفاده شود. برای مثال، یک هوک .Fa setenv که روی یک نسخه اختصاصی از محیط عمل می‌کند اما .Va environ را بدون تغییر باقی می‌گذارد. .El .El .Pp هنگام قلاب کردن (hooking) توابع کتابخانه C باید دقت شود، زیرا ایجاد یک حلقه بی‌نهایت بسیار آسان است. به عنوان مثال، یک هوک .Xr getenv 3 که تابع .Xr snprintf 3 را فراخوانی می‌کند، اگر پیاده‌سازی .Xr snprintf 3 برای بررسی محلی‌سازی (locale) تابع .Xr getenv 3 را فراخوانی کند، ممکن است یک حلقه ایجاد کند. برای جلوگیری از این امر، ممکن است بخواهید از یک متغیر ایستا (static) در تابع هوک برای محافظت در برابر فراخوانی‌های تو در تو استفاده کنید. برای مثال: .Bd -literal -offset indent static int in_progress = 0; /* avoid recursion */ if (in_progress) return SUDO_HOOK_RET_NEXT; in_progress = 1; \&... in_progress = 0; return SUDO_HOOK_RET_STOP; .Ed .Pp .Em "ماکروهای نسخه رابط هوک (Hook API Version Macros)" .Bd -literal /* Hook API version major/minor */ #define SUDO_HOOK_VERSION_MAJOR 1 #define SUDO_HOOK_VERSION_MINOR 0 #define SUDO_HOOK_VERSION SUDO_API_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\e SUDO_HOOK_VERSION_MINOR) .Ed .Pp برای توابع دریافت‌کننده و تنظیم‌کننده (getters and setters) به بخش .Sx Policy plugin API مراجعه کنید. .Ss "رابط رویداد (Event API)" هنگامی که .Nm sudo دستوری را اجرا می‌کند، از یک حلقه رویداد (event loop) برای رسیدگی به سیگنال‌ها و I/O استفاده می‌نماید. رویدادها ممکن است بر اساس زمان، آماده شدن یک توصیف‌گر فایل یا سوکت، یا به دلیل دریافت یک سیگنال فعال شوند. از نسخه ۱.۱۵ رابط برنامه‌نویسی (API) به بعد، این امکان برای یک افزونه فراهم شده است که با فراخوانی تابع .Fn event_alloc در این حلقه رویداد مشارکت کند. .Pp .Em ساختار رویداد (Event structure) .Pp رویدادها توسط ساختار زیر توصیف می‌شوند: .Pp .Bd -literal -compact typedef void (*sudo_plugin_ev_callback_t)(int fd, int what, void *closure); struct sudo_plugin_event { int (*set)(struct sudo_plugin_event *pev, int fd, int events, sudo_plugin_ev_callback_t callback, void *closure); int (*add)(struct sudo_plugin_event *pev, struct timespec *timeout); int (*del)(struct sudo_plugin_event *pev); int (*pending)(struct sudo_plugin_event *pev, int events, struct timespec *ts); int (*fd)(struct sudo_plugin_event *pev); void (*setbase)(struct sudo_plugin_event *pev, void *base); void (*loopbreak)(struct sudo_plugin_event *pev); void (*free)(struct sudo_plugin_event *pev); }; .Ed .Pp یک .Vt struct sudo_plugin_event شامل اشاره‌گرهای تابع زیر است: .Bl -tag -width 4n .It Fa set .Bd -literal -compact int (*set)(struct sudo_plugin_event *pev, int fd, int events, sudo_plugin_ev_callback_t callback, void *closure); .Ed .Pp تابع .Fn set آرگومان‌های زیر را دریافت می‌کند: .Bl -tag -width 4n .It Vt struct sudo_plugin_event * Ns Fa pev اشاره‌گری به خود .Vt struct sudo_plugin_event . .It Fa fd توصیف‌گر فایل یا سوکت برای رویدادهای مبتنی بر I/O یا شماره سیگنال برای رویدادهای سیگنال. برای رویدادهای مبتنی بر زمان، .Fa fd باید \-1 باشد. .It Fa events مقادیر زیر مشخص می‌کنند که چه چیزی بازخوانی (callback) رویداد را فعال می‌کند: .Bl -tag -width 4n .It Dv SUDO_PLUGIN_EV_TIMEOUT کالبک پس از انقضای مهلت زمانی (timeout) مشخص‌شده اجرا می‌شود .It Dv SUDO_PLUGIN_EV_READ کالبک هنگامی که توصیف‌گر فایل آماده خواندن باشد اجرا می‌شود .It Dv SUDO_PLUGIN_EV_WRITE کالبک هنگامی که توصیف‌گر فایل آماده نوشتن باشد اجرا می‌شود .It Dv SUDO_PLUGIN_EV_PERSIST رویداد ماندگار است و تا زمانی که صریحاً حذف نشود فعال باقی می‌ماند .It Dv SUDO_PLUGIN_EV_SIGNAL کالبک هنگام دریافت سیگنال مشخص‌شده اجرا می‌شود .El .Pp فلگ .Dv SUDO_PLUGIN_EV_PERSIST می‌تواند با هر یک از انواع رویدادها با عملگر OR ترکیب شود. همچنین می‌توان .Dv SUDO_PLUGIN_EV_READ و .Dv SUDO_PLUGIN_EV_WRITE را با هم OR کرد تا کالبک هنگامی که یک توصیف‌گر چه برای خواندن و چه برای نوشتن آماده باشد اجرا شود. سایر مقادیر رویداد نسبت به یکدیگر مانعة‌الجمع هستند. .It Vt sudo_plugin_ev_callback_t Fa callback .Bd -literal -compact typedef void (*sudo_plugin_ev_callback_t)(int fd, int what, void *closure); .Ed .Pp تابعی که هنگام فعال شدن یک رویداد باید فراخوانی شود. تابع .Fn callback با آرگومان‌های زیر اجرا می‌شود: .Bl -tag -width 4n .It Fa fd توصیف‌گر فایل یا سوکت برای رویدادهای مبتنی بر I/O یا شماره سیگنال برای رویدادهای سیگنال. .It Fa what نوع رویدادی که موجب فعال شدن آن کالبک شده است. برای رویدادهایی که دارای چندین نوع رویداد هستند (برای مثال .Dv SUDO_PLUGIN_EV_READ و .Dv SUDO_PLUGIN_EV_WRITE ) یا دارای مهلت زمانی مرتبط هستند، .Fa what می‌تواند برای تعیین علت اجرای کالبک استفاده شود. .It Fa closure اشاره‌گر عمومی که در تابع .Fn set مشخص شده است. .El .It Fa closure اشاره‌گر عمومی که به تابع کالبک ارسال خواهد شد. .El .Pp تابع .Fn set در صورت موفقیت مقدار 1 و در صورت بروز خطا مقدار \-1 را بازمی‌گرداند. .It Fa add .Bd -literal -compact int (*add)(struct sudo_plugin_event *pev, struct timespec *timeout); .Ed .Pp تابع .Fn add رویداد .Fa pev را به حلقه رویداد .Nm sudo اضافه می‌کند. رویداد باید پیش‌تر از طریق تابع .Fn set مقداردهی اولیه شده باشد. اگر آرگومان .Fa timeout مقدار NULL نباشد، باید یک مهلت زمانی (نسبی) را مشخص کند که اگر معیار اصلی رویداد برآورده نشده باشد، رویداد پس از آن فعال شود. این اغلب برای پیاده‌سازی مهلت زمانی I/O استفاده می‌شود، جایی که اگر توصیف‌گر در یک بازه زمانی مشخص آماده نشود، رویداد شلیک می‌شود. اگر رویداد از قبل در حلقه رویداد موجود باشد، .Fa timeout آن برای مطابقت با مقدار جدید (در صورت وجود) به‌روزرسانی خواهد شد. .Pp تابع .Fn add در صورت موفقیت مقدار 1 و در صورت بروز خطا مقدار \-1 را بازمی‌گرداند. .It Fa del .Bd -literal -compact int (*del)(struct sudo_plugin_event *pev); .Ed .Pp تابع .Fn del رویداد .Fa pev را از حلقه رویداد .Nm sudo حذف می‌کند. رویدادهای حذف‌شده می‌توانند دوباره از طریق تابع .Fn add اضافه شوند. .Pp تابع .Fn del در صورت موفقیت مقدار 1 و در صورت بروز خطا مقدار \-1 را بازمی‌گرداند. .It Fa pending .Bd -literal -compact int (*pending)(struct sudo_plugin_event *pev, int events, struct timespec *ts); .Ed .Pp تابع .Fn pending می‌تواند برای بررسی اینکه آیا یک یا چند رویداد در انتظار (pending) هستند یا خیر به کار رود. آرگومان .Fa events مشخص می‌کند که چه رویدادهایی بررسی شوند. برای مشاهده فهرستی از انواع رویدادهای معتبر، تابع .Fn set را ببینید. اگر .Dv SUDO_PLUGIN_EV_TIMEOUT در .Fa events مشخص شده باشد، رویداد دارای مهلت زمانی مرتبط باشد و اشاره‌گر .Fa ts غیر NULL باشد، با زمان باقی‌مانده پر خواهد شد. .It Fa fd .Bd -literal -compact int (*fd)(struct sudo_plugin_event *pev); .Ed .Pp تابع .Fn fd توصیف‌گر یا شماره سیگنال مرتبط با رویداد .Fa pev را بازمی‌گرداند. .It Fa setbase .Bd -literal -compact void (*setbase)(struct sudo_plugin_event *pev, void *base); .Ed .Pp تابع .Fn setbase پایه رویداد زیرین .Fa base را برای .Fa pev روی مقدار مشخص‌شده تنظیم می‌کند. این تابع می‌تواند برای انتقال رویدادی که از طریق .Fn event_alloc ایجاد شده است به یک حلقه رویداد جدید تخصیص‌یافته توسط زیرسیستم رویداد sudo استفاده شود. اگر .Fa base برابر .Dv NULL باشد، پایه رویداد .Fa pev به مقدار پیش‌فرض بازنشانی می‌شود، که متناظر با حلقه رویداد اصلی .Nm sudo است. استفاده از این تابع نیازمند پیوند دادن (link) افزونه با کتابخانه sudo_util است. بعید است که در خارج از افزونه .Nm sudoers استفاده شود. .It Fa loopbreak .Bd -literal -compact void (*loopbreak)(struct sudo_plugin_event *pev); .Ed .Pp تابع .Fn loopbreak باعث می‌شود حلقه رویداد .Nm sudo بلافاصله خارج شود و دستور در حال اجرا پایان یابد. .It Fa free .Bd -literal -compact void (*free)(struct sudo_plugin_event *pev); .Ed .Pp تابع .Fn free رویداد .Fa pev را از حلقه رویداد حذف کرده و حافظه مرتبط با آن را آزاد می‌کند. .El .Ss "اجرای دستور از راه دور (Remote command execution)" فرانت‌اند .Nm sudo از اجرای دستورات از راه دور پشتیبانی نمی‌کند. با این حال، از نسخه ۱.۸.۸ .Nm sudo به بعد، گزینه .Fl h می‌تواند برای مشخص کردن یک میزبان راه دور که به افزونه خط‌مشی ارسال می‌شود استفاده شود. یک افزونه همچنین ممکن است یک .Em runas_user را در قالب .Dq user@hostname بپذیرد که با نسخه‌های قدیمی‌تر .Nm sudo نیز کار خواهد کرد. پیش‌بینی می‌شود که دستورات راه دور با اجرای یک برنامه کمکی ( .Dq helper ) پشتیبانی شوند. افزونه خط‌مشی باید محیط اجرا را به گونه‌ای آماده کند که فرانت‌اند .Nm sudo برنامه کمکی را اجرا کند، و آن برنامه نیز به نوبه خود به میزبان راه دور متصل شده و دستور را اجرا نماید. .Pp به عنوان مثال، افزونه خط‌مشی می‌تواند از .Nm ssh برای اجرای دستور از راه دور بهره ببرد. برنامه کمکی مسئول اجرای .Nm ssh با گزینه‌های مناسب برای استفاده از کلید خصوصی یا گواهی معتبر جهت پذیرش توسط میزبان راه دور، و اجرای برنامه‌ای در میزبان راه دور خواهد بود که محیط اجرا را متناسب با آن آماده کند. .Pp قابلیت راه دور .Nm sudoedit باید توسط افزونه خط‌مشی مدیریت شود، نه خود .Nm sudo ، چرا که فرانت‌اند اطلاعی از در حال اجرا بودن یک دستور راه دور ندارد. این موضوع ممکن است در بازنگری‌های آینده رابط برنامه‌نویسی افزونه برطرف شود. .Ss "رابط مکالمه (Conversation API)" اگر افزونه نیاز به تعامل با کاربر داشته باشد، می‌تواند این کار را از طریق تابع .Fn conversation انجام دهد. یک افزونه نباید تلاش کند مستقیماً از ورودی استاندارد یا ترمینال کاربر بخواند (وجود هیچ‌کدام تضمین نشده است). فراخواننده در صورتی که نیاز به چاپ خط جدید باشد، باید یک کاراکتر خط جدید انتهایی را در .Fa msg بگنجاند. .Pp یک تابع به سبک .Fn printf نیز در دسترس است که می‌تواند برای نمایش پیام‌های اطلاعاتی یا خطا به کاربر استفاده شود، که معمولاً برای پیام‌های ساده‌ای که به هیچ ورودی کاربری نیاز ندارند مناسب‌تر است. .Pp .Em ساختارهای تابع مکالمه (Conversation function structures) .Pp تابع مکالمه به عنوان آرگومان، اشاره‌گرهایی به ساختارهای زیر را می‌گیرد: .Bd -literal struct sudo_conv_message { #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */ #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */ #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */ #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */ #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */ #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */ #define SUDO_CONV_PREFER_TTY 0x2000 /* flag: use tty if possible */ int msg_type; int timeout; const char *msg; }; #define SUDO_CONV_REPL_MAX 1023 struct sudo_conv_reply { char *reply; }; typedef int (*sudo_conv_callback_fn_t)(int signo, void *closure); struct sudo_conv_callback { unsigned int version; void *closure; sudo_conv_callback_fn_t on_suspend; sudo_conv_callback_fn_t on_resume; }; .Ed .Pp اشاره‌گرها به توابع .Fn conversation و به سبک .Fn printf هنگام مقداردهی اولیه افزونه، به تابع .Fn open افزونه ارسال می‌شوند. تعاریف نوع زیر می‌توانند در اعلان تابع .Fn open استفاده شوند: .Bd -literal typedef int (*sudo_conv_t)(int num_msgs, const struct sudo_conv_message msgs[], struct sudo_conv_reply replies[], struct sudo_conv_callback *callback); typedef int (*sudo_printf_t)(int msg_type, const char * restrict fmt, ...); .Ed .Pp برای استفاده از تابع .Fn conversation ، افزونه باید آرایه‌ای از .Vt struct sudo_conv_message و .Vt struct sudo_conv_reply را ارسال کند. باید برای هر پیام در مکالمه یک .Vt struct sudo_conv_message و یک .Vt struct sudo_conv_reply وجود داشته باشد، به این معنی که هر دو آرایه باید دارای تعداد عناصر یکسانی باشند. هر .Vt struct sudo_conv_reply باید عضو .Fa reply خود را با .Dv NULL مقداردهی اولیه کرده باشد. اشاره‌گر .Vt struct sudo_conv_callback ، اگر .Dv NULL نباشد، باید شامل اشاره‌گرهای تابعی باشد که هنگام تعلیق (suspend) یا ازسرگیری (resume) فرآیند .Nm sudo در حین دریافت ورودی مکالمه فراخوانی شوند. توابع .Fa on_suspend و .Fa on_resume با سیگنالی که باعث تعلیق .Nm sudo شده است و اشاره‌گر .Fa closure از .Vt struct sudo_conv_callback فراخوانی می‌شوند. این توابع باید در صورت موفقیت مقدار 0 و در صورت بروز خطا مقدار \-1 را بازگردانند. در صورت بروز خطا، مکالمه خاتمه می‌یابد و تابع مکالمه مقدار \-1 را بازمی‌گرداند. کاربرد مورد نظر این است که به افزونه اجازه داده شود منابعی مانند قفل‌ها را که نباید هنگام تعلیق به طور نامحدود نگه داشته شوند آزاد کند و سپس با ازسرگیری فرآیند، دوباره آنها را در اختیار بگیرد. این توابع در واقع از داخل یک گرداننده سیگنال (signal handler) اجرا نمی‌شوند. .Pp مقدار .Fa msg_type باید روی یکی از مقادیر زیر تنظیم شود: .Bl -tag -width 4n .It Dv SUDO_CONV_PROMPT_ECHO_OFF درخواست ورودی از کاربر با غیرفعال بودن پژواک (echo) ورودی؛ این گزینه معمولاً برای گذرواژه‌ها استفاده می‌شود. پاسخ در آرایه .Fa replies ذخیره خواهد شد و هرگز .Dv NULL نخواهد بود. .It Dv SUDO_CONV_PROMPT_ECHO_ON درخواست ورودی از کاربر با فعال بودن پژواک (echo) ورودی. پاسخ در آرایه .Fa replies ذخیره خواهد شد و هرگز .Dv NULL نخواهد بود. .It Dv SUDO_CONV_ERROR_MSG نمایش یک پیام خطا. پیام در خروجی خطای استاندارد (standard error) نوشته می‌شود مگر اینکه فلگ .Dv SUDO_CONV_PREFER_TTY تنظیم شده باشد، که در این صورت در صورت امکان در ترمینال کاربر نوشته می‌شود. .It Dv SUDO_CONV_INFO_MSG نمایش یک پیام. پیام در خروجی استاندارد (standard output) نوشته می‌شود مگر اینکه فلگ .Dv SUDO_CONV_PREFER_TTY تنظیم شده باشد، که در این صورت در صورت امکان در ترمینال کاربر نوشته می‌شود. .It Dv SUDO_CONV_PROMPT_MASK درخواست ورودی از کاربر با نمایش نویسه ستاره به ازای هر نویسه خوانده‌شده. پاسخ در آرایه .Fa replies ذخیره خواهد شد و هرگز .Dv NULL نخواهد بود. این می‌تواند برای ارائه بازخورد بصری به کاربر در حین خواندن اطلاعات حساسی که نباید نمایش داده شوند استفاده شود. .El .Pp علاوه بر مقادیر فوق، بیت‌های فلگ زیر نیز می‌توانند تنظیم شوند: .Bl -tag -width 4n .It Dv SUDO_CONV_PROMPT_ECHO_OK اجازه خواندن ورودی در حالتی که غیرفعال کردن echo ممکن نیست، هنگامی که نوع پیام .Dv SUDO_CONV_PROMPT_ECHO_OFF یا .Dv SUDO_CONV_PROMPT_MASK باشد. به طور پیش‌فرض، اگر نتوان echo را برای این نوع پیام‌ها غیرفعال کرد، .Nm sudo از خواندن ورودی امتناع می‌ورزد. .It Dv SUDO_CONV_PREFER_TTY هنگام نمایش پیام از طریق .Dv SUDO_CONV_ERROR_MSG یا .Dv SUDO_CONV_INFO_MSG ، تلاش می‌کند پیام را در ترمینال کاربر بنویسد. اگر ترمینال در دسترس نباشد، بسته به اینکه از .Dv SUDO_CONV_ERROR_MSG یا .Dv SUDO_CONV_INFO_MSG استفاده شده باشد، خروجی خطای استاندارد یا خروجی استاندارد استفاده خواهد شد. ترمینال کاربر همیشه در صورت امکان برای ورودی استفاده می‌شود؛ این فلگ تنها برای خروجی کاربرد دارد. .El .Pp پارامتر .Fa timeout به ثانیه مشخص می‌کند که اعلان تا چه مدت منتظر ورودی بماند. مقدار صفر به معنای مهلت زمانی نامحدود است. .Pp افزونه مسئول آزادسازی بافر پاسخ موجود در هر .Vt struct sudo_conv_reply است، در صورتی که مقدار آن .Dv NULL نباشد. ثابت .Dv SUDO_CONV_REPL_MAX نشان‌دهنده حداکثر طول بافر پاسخ است (بدون احتساب نویسه NUL انتهایی). از دیدگاه کاربردی، این طولانی‌ترین گذرواژه‌ای است که .Nm sudo پشتیبانی خواهد کرد. .Pp تابع به سبک .Fn printf از همان سازوکار زیرین تابع .Fn conversation استفاده می‌کند اما فقط از .Dv SUDO_CONV_INFO_MSG و .Dv SUDO_CONV_ERROR_MSG برای پارامتر .Fa msg_type پشتیبانی می‌نماید. اگر نیازی به پاسخ کاربر نباشد، این تابع می‌تواند راحت‌تر از تابع .Fn conversation باشد و از دنباله‌های فرار استاندارد .Fn printf پشتیبانی می‌کند. .Pp برای مشاهده یک مثال از کاربرد تابع .Fn conversation ، افزونه نمونه را ببینید. .Ss "ترتیب فراخوانی افزونهها (Plugin invocation order)" از نسخه ۱.۹.۰ .Nm sudo به بعد، توابع .Fn open و .Fn close افزونه به ترتیب زیر فراخوانی می‌شوند: .Bl -enum .It audit open .It policy open .It approval open .It approval close .It I/O log open .It اجرای دستور (command runs) .It خاتمه دستور (command exits) .It I/O log close .It policy close .It audit close .It خروج sudo .El .Pp پیش از نسخه ۱.۹.۰ .Nm sudo ، تابع .Fn close لاگ I/O .Em پس از تابع .Fn close خط‌مشی فراخوانی می‌شد. .Ss "رابط افزونههای گروه sudoers (Sudoers group plugin API)" افزونه .Nm sudoers از رابط افزونه اختصاصی خود برای فعال‌سازی جستجوی گروه‌های غیر یونیکسی پشتیبانی می‌کند. این قابلیت می‌تواند برای پرس‌وجو از یک منبع گروه به غیر از پایگاه‌داده استاندارد گروه‌های یونیکس به کار رود. دو افزونه گروه نمونه همراه با .Nm sudo عرضه شده‌اند، .Em group_file و .Em system_group ، که جزئیات آنها در .Xr sudoers 5 آمده است. افزونه‌های گروه شخص ثالث شامل یک افزونه QAS AD هستند که توسط Quest Software عرضه شده است. .Pp یک افزونه گروه باید یک .Vt struct sudoers_group_plugin را در حوزه سراسری (global scope) اعلان کرده و مقداردهی کند. این ساختار حاوی اشاره‌گرهایی به توابعی است که مقداردهی اولیه افزونه، پاک‌سازی و جستجوی گروه را پیاده‌سازی می‌کنند. .Bd -literal struct sudoers_group_plugin { unsigned int version; int (*init)(int version, sudo_printf_t sudo_plugin_printf, char *const argv[]); void (*cleanup)(void); int (*query)(const char *user, const char *group, const struct passwd *pwd); }; .Ed .Pp یک .Vt struct sudoers_group_plugin دارای فیلدهای زیر است: .Bl -tag -width 4n .It Fa version فیلد .Fa version باید روی GROUP_API_VERSION تنظیم شود. .Pp این به .Nm sudoers امکان می‌دهد تا نسخه API که افزونه گروه بر اساس آن ساخته شده است را تشخیص دهد. .It Fa init .Bd -literal -compact int (*init)(int version, sudo_printf_t sudo_plugin_printf, char *const argv[]); .Ed .Pp تابع .Fn init پس از تجزیه شدن .Em sudoers اما پیش از هرگونه بررسی خط‌مشی فراخوانی می‌شود. در صورت موفقیت مقدار 1، در صورت عدم موفقیت (یا اگر افزونه پیکربندی نشده باشد) مقدار 0 و در صورت بروز خطا مقدار \-1 را بازمی‌گرداند. اگر خطایی رخ دهد، افزونه می‌تواند تابع .Fn plugin_printf را با .Dv SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری را به کاربر نمایش دهد. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa version نسخه ارسال‌شده توسط .Nm sudoers به افزونه امکان می‌دهد تا شماره نسخه اصلی و فرعی رابط افزونه گروه که توسط .Nm sudoers پشتیبانی می‌شود را مشخص کند. .It Fa plugin_printf اشاره‌گری به یک تابع به سبک .Fn printf که می‌تواند برای نمایش پیام‌های اطلاعاتی یا خطا به کاربر استفاده شود. در صورت موفقیت، تعداد نویسه‌های چاپ‌شده و در صورت شکست، مقدار \-1 را بازمی‌گرداند. .It Fa argv یک آرایه خاتمه‌یافته با .Dv NULL از آرگومان‌های تولیدشده از گزینه .Em group_plugin در .Em sudoers است. اگر هیچ آرگومانی داده نشده باشد، .Fa argv برابر .Dv NULL خواهد بود. .El .It Fa cleanup .Bd -literal -compact void (*cleanup)(); .Ed .Pp تابع .Fn cleanup زمانی فراخوانی می‌شود که .Nm sudoers بررسی‌های گروه خود را به پایان رسانده باشد. افزونه باید هرگونه حافظه‌ای را که تخصیص داده است آزاد کند و توصیف‌گرهای باز فایل را ببندد. .It Fa query .Bd -literal -compact int (*query)(const char *user, const char *group, const struct passwd *pwd); .Ed .Pp تابع .Fn query برای پرسش از افزونه گروه در این باره که آیا .Fa user عضوی از .Fa group است یا خیر استفاده می‌شود. .Pp آرگومان‌های تابع به شرح زیر هستند: .Bl -tag -width 4n .It Fa user نام کاربری که در پایگاه‌داده خارجی گروه جستجو می‌شود. .It Fa group نام گروهی که مورد پرس‌وجو قرار می‌گیرد. .It Fa pwd مدخل پایگاه‌داده گذرواژه برای .Fa user (در صورت وجود). اگر .Fa user در پایگاه‌داده گذرواژه موجود نباشد، .Fa pwd برابر .Dv NULL خواهد بود. .El .El .Pp .Em ماکروهای نسخه رابط برنامه‌نویسی گروه (Group API Version Macros) .Bd -literal /* Sudoers group plugin version major/minor */ #define GROUP_API_VERSION_MAJOR 1 #define GROUP_API_VERSION_MINOR 0 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \e GROUP_API_VERSION_MINOR) .Ed برای توابع دریافت‌کننده و تنظیم‌کننده (getters and setters) بخش .Sx Policy plugin API . .Sh "تغییرات رابط افزونه (PLUGIN API CHANGELOG)" بازبینی‌های زیر در رابط برنامه‌نویسی افزونه‌های (API) سدو اعمال شده است. .Bl -tag -width 4n .It Version 1.0 نسخه اولیه API. .It Version 1.1 (sudo 1.8.0) تابع .Fn open در افزونه‌های ثبت وقایع ورودی/خروجی (I/O logging) به گونه‌ای اصلاح شد که فهرست .Fa command_info را به عنوان یک آرگومان دریافت کند. .It Version 1.2 (sudo 1.8.5) به توابع .Fn open در افزونه‌های خط‌مشی (Policy) و ثبت ورودی/خروجی (I/O logging) اکنون در صورت مشخص شدن پارامترهای افزونه در .Xr sudo.conf 5 ، فهرستی از آن‌ها ارسال می‌شود. .Pp یک رابط هوک (hooks API) ساده معرفی شده است که به افزونه‌ها اجازه می‌دهد به توابع مدیریت محیط سیستم متصل شوند. .Pp به تابع .Fn init_session در افزونه خط‌مشی، اکنون اشاره‌گری به محیط کاربری ارسال می‌شود که در صورت نیاز قابل به‌روزرسانی است. از این قابلیت می‌توان برای ادغام متغیرهای محیطی ذخیره‌شده در دسته PAM پیش از اجرای دستور استفاده کرد. .It Version 1.3 (sudo 1.8.7) پشتیبانی از ورودی .Em exec_background به فهرست .Fa command_info اضافه شد. .Pp ورودی‌های .Em max_groups و .Em plugin_dir به فهرست .Fa settings اضافه شدند. .Pp توابع .Fn version و .Fn close اکنون اختیاری هستند. پیش از این، عدم وجود تابع .Fn version یا .Fn close منجر به از کار افتادن برنامه (کرش) می‌شد. اگر هیچ تابع .Fn close در افزونه خط‌مشی تعریف نشده باشد، یک تابع .Fn close پیش‌فرض توسط فرانت‌اند .Nm sudo ارائه می‌شود که در صورت عدم امکان اجرای دستور، یک هشدار نمایش می‌دهد. .Pp فرانت‌اند .Nm sudo اکنون گرداننده‌های سیگنال (signal handlers) پیش‌فرضی را برای به‌دام‌انداختن سیگنال‌های متداول هنگام اجرای توابع افزونه نصب می‌کند. .It Version 1.4 (sudo 1.8.8) ورودی .Em remote_host به فهرست .Fa settings اضافه شد. .It Version 1.5 (sudo 1.8.9) ورودی .Em preserve_fds به فهرست .Fa command_info اضافه شد. .It Version 1.6 (sudo 1.8.11) رفتار سیستم هنگام بازگرداندن خطا توسط افزونه ثبت ورودی/خروجی .Pq \-1 تغییر کرده است. پیش از این، فرانت‌اند .Nm sudo هنگامی که توابع .Fn log_ttyin ، .Fn log_ttyout ، .Fn log_stdin ، .Fn log_stdout یا .Fn log_stderr خطایی بازمی‌گرداندند، هیچ اقدامی انجام نمی‌داد. .Pp رفتار سیستم هنگامی که یک افزونه ثبت ورودی/خروجی مقدار 0 را برمی‌گرداند تغییر کرده است. پیش از این، خروجی دستور حتی در صورتی که تابع ثبت خروجی مقدار 0 را بازمی‌گرداند نیز روی ترمینال نمایش داده می‌شد. .It Version 1.7 (sudo 1.8.12) ورودی .Em plugin_path به فهرست .Fa settings اضافه شد. .Pp ورودی .Em debug_flags اکنون با نام مسیر فایل اشکال‌زدایی آغاز می‌شود و در صورتی که چندین خط Debug ویژه افزونه در فایل .Xr sudo.conf 5 وجود داشته باشد، ممکن است چندین بار تکرار شود. .It Version 1.8 (sudo 1.8.15) ورودی‌های .Em sudoedit_checkdir و .Em sudoedit_follow به فهرست .Fa command_info اضافه شدند. مقدار پیش‌فرض .Em sudoedit_checkdir در sudo 1.8.16 به true تغییر یافت. .Pp تابع .Fn conversation در sudo اکنون اشاره‌گری به یک .Vt struct sudo_conv_callback را به عنوان چهارمین آرگومان خود دریافت می‌کند. تعریف .Vt sudo_conv_t برای تطابق به‌روزرسانی شده است. افزونه باید مشخص کند که از نسخه 1.8 یا بالاتر API افزونه پشتیبانی می‌کند تا اشاره‌گر تابع گفتگویی را دریافت نماید که از این آرگومان پشتیبانی می‌کند. .It Version 1.9 (sudo 1.8.16) ورودی .Em execfd به فهرست .Fa command_info اضافه شد. .It Version 1.10 (sudo 1.8.19) ورودی .Em umask به فهرست .Fa user_info اضافه شد. ورودی‌های .Em iolog_group ، .Em iolog_mode و .Em iolog_user به فهرست .Fa command_info اضافه شدند. .It Version 1.11 (sudo 1.8.20) ورودی .Em timeout به فهرست .Fa settings اضافه شد. .It Version 1.12 (sudo 1.8.21) تابع .Fn change_winsize به .Vt struct io_plugin اضافه شد. .It Version 1.13 (sudo 1.8.26) تابع .Fn log_suspend به .Vt struct io_plugin اضافه شد. .It Version 1.14 (sudo 1.8.29) ورودی .Em umask_override به فهرست .Fa command_info اضافه شد. .It Version 1.15 (sudo 1.9.0) ورودی .Em cwd_optional به فهرست .Fa command_info اضافه شد. .Pp تابع .Fn event_alloc به .Vt struct policy_plugin و .Vt struct io_plugin اضافه شد. .Pp آرگومان .Fa errstr به توابع افزونه‌های خط‌مشی و ورودی/خروجی افزوده شد که تابع افزونه می‌تواند از آن برای بازگرداندن رشته خطا استفاده کند. این رشته ممکن است توسط افزونه حسابرسی (audit plugin) برای گزارش شرایط شکست یا خطای تعیین‌شده توسط سایر افزونه‌ها به کار رود. .Pp تابع .Fn close اکنون صرف‌نظر از اینکه دستوری واقعاً اجرا شده است یا خیر، فراخوانی می‌شود. این امر امکان پاک‌سازی منابع را برای افزونه‌ها حتی در صورت عدم اجرای دستور فراهم می‌آورد. .Pp مقدار .Dv SUDO_CONV_REPL_MAX از ۲۵۵ به ۱۰۲۳ بایت افزایش یافت. .Pp پشتیبانی از افزونه‌های حسابرسی (audit) و تایید (approval) اضافه شد. .It Version 1.16 (sudo 1.9.3) مقادیر اولیه محدودیت منابع به فهرست .Fa user_info اضافه شدند. .Pp ورودی‌های .Em cmnd_chroot و .Em cmnd_cwd به فهرست .Fa settings اضافه شدند. .It Version 1.17 (sudo 1.9.4) تابع .Fn event_alloc به .Vt struct audit_plugin و .Vt struct approval_plugin اضافه شد. .It Version 1.18 (sudo 1.9.9) افزونه خط‌مشی اکنون می‌تواند مقادیر محدودیت منابع را در فهرست .Fa command_info تنظیم کند. ورودی‌های .Em intercept و .Em log_subcmds به فهرست .Fa command_info اضافه شدند. .It Version 1.19 (sudo 1.9.11) ورودی‌های .Em intercept_ptrace و .Em intercept_setid به فهرست .Fa settings اضافه شدند. ورودی‌های .Em apparmor_profile و .Em use_ptrace به فهرست .Fa command_info اضافه شدند. .It Version 1.20 (sudo 1.9.12) ورودی .Em update_ticket به فهرست .Fa settings اضافه شد. ورودی .Em intercept_verify به فهرست .Fa command_info اضافه شد. .It Version 1.21 (sudo 1.9.13) ورودی .Em sudoedit_nfiles به فهرست .Fa command_info اضافه شد. .It Version 1.22 (sudo 1.9.16) ورودی .Em ttydev به فهرست .Fa user_info اضافه شد. .El .Sh "همچنین ببینید (SEE ALSO)" .Xr sudo.conf 5 , .Xr sudoers 5 , .Xr sudo 8 .Sh "نویسندگان (AUTHORS)" افراد بسیاری در طول سال‌ها روی .Nm sudo کار کرده‌اند؛ این نسخه عمدتاً شامل کدهای نوشته‌شده توسط فرد زیر است: .Bd -ragged -offset indent .An Todd C. Miller .Ed .Pp برای فهرست کامل افرادی که در .Nm sudo مشارکت داشته‌اند، پرونده CONTRIBUTORS.md را در توزیع .Nm sudo (https://www.sudo.ws/about/contributors) مشاهده فرمایید. .Sh "اشکالات (BUGS)" اگر معتقدید اشکالی در .Nm یافته‌اید، می‌توانید یک گزارش اشکال در پایگاه‌داده اشکالات سدو در https://bugzilla.sudo.ws ثبت کنید یا یک issue در https://github.com/sudo-project/sudo/issues باز نمایید. چنانچه ترجیح می‌دهید از ایمیل استفاده کنید، پیام‌ها می‌توانند به فهرست پستی sudo-workers در https://www.sudo.ws/mailman/listinfo/sudo-workers (عمومی) یا به (خصوصی) ارسال شوند. .Pp لطفاً آسیب‌پذیری‌های امنیتی را از طریق issueهای عمومی گیت‌هاب، باگزیلا یا فهرست‌های پستی گزارش نکنید. در عوض، آن‌ها را از طریق ایمیل به گزارش دهید. در صورت تمایل می‌توانید پیام خود را با کلید PGP موجود در https://www.sudo.ws/dist/PGPKEYS رمزگذاری کنید. .Sh "پشتیبانی (SUPPORT)" پشتیبانی رایگان و محدود از طریق فهرست پستی sudo-users در دسترس است، برای عضویت یا جستجو در آرشیو نشانی https://www.sudo.ws/mailman/listinfo/sudo-users را ببینید. .Sh "سلب مسئولیت (DISCLAIMER)" .Nm sudo به‌صورت .Dq AS IS ارائه می‌شود و هرگونه ضمانت صریح یا ضمنی، از جمله، اما نه محدود به، ضمانت‌های ضمنی قابلیت فروش و تناسب برای یک هدف خاص سلب می‌شود. برای جزئیات کامل، پرونده LICENSE.md ارائه‌شده همراه با .Nm sudo یا نشانی https://www.sudo.ws/about/license را ملاحظه فرمایید.