SUDO_PLUGIN(5) File Formats Manual SUDO_PLUGIN(5)

sudo_plugin — رابط افزونههای sudo

از نسخه ۱.۸ به بعد، sudo از یک رابط برنامه‌نویسی (API) افزونه برای سیاست‌گذاری (policy) و ثبت نشست‌ها (session logging) پشتیبانی می‌کند. افزونه‌ها می‌توانند به‌صورت اشیاء اشتراکی پویا (dynamic shared objects ‏- حالت پیش‌فرض در سیستم‌هایی که از آن‌ها پشتیبانی می‌کنند) کامپایل شوند، یا به‌صورت ایستا (statically) درون خود باینری sudo کامپایل گردند. به‌طور پیش‌فرض، افزونه sudoers قابلیت‌های بازرسی (audit)، سیاست‌گذاری امنیتی و ثبت ورودی/خروجی (I/O) را فراهم می‌کند. از طریق API افزونه، sudo می‌تواند برای استفاده از افزونه‌های جایگزینِ ارائه‌شده توسط اشخاص ثالث پیکربندی شود. افزونه‌های مورد استفاده در فایل sudo.conf(5) مشخص می‌شوند.

این API با شماره‌های نسخه اصلی (major) و فرعی (minor) نسخه‌گذاری می‌شود. با اعمال تغییرات افزایشی، شماره نسخه فرعی افزایش می‌یابد. با اعمال تغییرات ناسازگار، شماره نسخه اصلی افزایش می‌یابد. یک افزونه باید نسخه‌ای که به آن ارسال شده است را بررسی کند و مطمئن شود که نسخه اصلی مطابقت دارد.

رابط API افزونه توسط فایل سرآیند <sudo_plugin.h> تعریف شده است.

یک افزونه سیاست‌گذاری باید یک struct policy_plugin را در دامنه سراسری (global scope) اعلان کرده و مقداردهی کند. این ساختار شامل اشاره‌گرهایی به توابعی است که بررسی‌های سیاست‌گذاری sudo را پیاده‌سازی می‌کنند. نام نماد (symbol) باید در sudo.conf(5) همراه با مسیری به افزونه مشخص شود تا sudo بتواند آن را بارگذاری کند.

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);
};

یک struct policy_plugin دارای فیلدهای زیر است:

type
فیلد type همیشه باید روی SUDO_POLICY_PLUGIN تنظیم شود.
version
فیلد version باید روی SUDO_API_VERSION تنظیم شود.

این به sudo اجازه می‌دهد تا نسخه API که افزونه بر اساس آن ساخته شده است را تعیین کند.

open
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);

در صورت موفقیت مقدار ۱، در صورت شکست ۰، در صورت بروز خطای عمومی -۱، و در صورت خطای نحوه استفاده (usage error) مقدار -۲ را برمی‌گرداند. در حالت آخر، sudo پیش از خروج پیام نحوه استفاده را چاپ خواهد کرد. اگر خطایی رخ دهد، افزونه می‌تواند به صورت اختیاری تابع () یا () را با SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری را به کاربر نمایش دهد.

آرگومان‌های تابع به شرح زیر هستند:

version
نسخه‌ای که توسط sudo ارسال می‌شود، به افزونه امکان می‌دهد شماره نسخه اصلی و فرعی API افزونه که توسط sudo پشتیبانی می‌شود را تعیین کند.
conversation
اشاره‌گری به تابع () که می‌تواند توسط افزونه برای تعامل با کاربر استفاده شود (برای جزئیات به Conversation API مراجعه کنید). در صورت موفقیت ۰ و در صورت شکست -۱ برمی‌گرداند.
sudo_plugin_printf
اشاره‌گری به یک تابع به سبک printf() که می‌تواند برای نمایش پیام‌های اطلاعاتی یا خطا استفاده شود (برای جزئیات به Conversation API مراجعه کنید). در صورت موفقیت تعداد نویسه‌های چاپ‌شده و در صورت شکست -۱ برمی‌گرداند.
settings
یک بردار از تنظیمات ارائه‌شده توسط کاربر برای sudo به صورت رشته‌های “name=value” است. این بردار با یک اشاره‌گر NULL خاتمه می‌یابد. این تنظیمات مربوط به گزینه‌هایی است که کاربر هنگام اجرای sudo مشخص کرده است. بنابراین، آن‌ها تنها زمانی وجود خواهند داشت که گزینه متناظر در خط فرمان مشخص شده باشد.

هنگام تجزیه settings ، افزونه باید آن را بر اساس اولین علامت مساوی (‘=’) تقسیم کند، زیرا فیلد name هرگز شامل مساوی نخواهد بود، اما مقدار value ممکن است شامل آن باشد.

مقادیر زیر ممکن است توسط sudo تنظیم شوند:

bsdauth_type=string
نوع احراز هویت، در صورت مشخص شدن با گزینه -a -، جهت استفاده در سیستم‌هایی که از احراز هویت BSD پشتیبانی می‌کنند.
closefrom=number
در صورت مشخص شدن، کاربر از طریق گزینه -C درخواست کرده است که sudo تمام توصیف‌کننده‌های فایل (file descriptors) با مقدار number یا بالاتر را ببندد. افزونه می‌تواند به صورت اختیاری این مقدار یا مقدار دیگری را در لیست command_info بازگرداند.
cmnd_chroot=string
دایرکتوری ریشه (به chroot(2) مراجعه کنید) برای اجرای دستور در آن، همان‌طور که توسط کاربر از طریق گزینه -R مشخص شده است. افزونه ممکن است توانایی کاربر برای تعیین یک دایرکتوری ریشه جدید را نادیده گرفته یا محدود کند. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است.
cmnd_cwd=string
دایرکتوری کاری برای اجرای دستور در آن، همان‌طور که توسط کاربر از طریق گزینه -D مشخص شده است. افزونه ممکن است توانایی کاربر برای تعیین یک دایرکتوری کاری جدید را نادیده گرفته یا محدود کند. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است.
debug_flags=string
نام مسیر فایل اشکال‌زدایی به همراه یک فاصله و یک لیست جداشده با کاما از فلگ‌های اشکال‌زدایی که متناظر با مدخل Debug افزونه در sudo.conf(5) است (در صورت وجود). فلگ‌ها دقیقاً همان‌طور که در sudo.conf(5) آمده‌اند به افزونه ارسال می‌شوند. نحو مورد استفاده توسط sudo و افزونه sudoers به صورت @ است، اما یک افزونه تا زمانی که از کاما (‘,’) استفاده نکند، در انتخاب قالبی متفاوت آزاد است. پیش از sudo نسخه 1.8.12، راهی برای تعیین debug_flags مخصوص افزونه وجود نداشت، بنابراین مقدار آن همیشه همان مقداری بود که توسط بخش فرانت‌اند sudo استفاده می‌شد و شامل نام مسیر نبود، بلکه تنها خود فلگ‌ها را دربرداشت. از نسخه ۱.۷ رابط افزونه، sudo تنها در صورتی debug_flags را ارسال می‌کند که sudo.conf(5) شامل یک مدخل Debug مخصوص آن افزونه باشد.
ignore_ticket=bool
اگر کاربر گزینه -k را همراه با یک دستور مشخص کرده باشد، روی true تنظیم می‌شود و نشان می‌دهد که کاربر مایل است از هرگونه اعتبارنامه‌های احراز هویت ذخیره‌شده (cached) چشم‌پوشی کند. implied_shell به true. این به sudo بدون هیچ آرگومانی امکان می‌دهد تا به روشی مشابه با su(1) مورد استفاده قرار گیرد. اگر افزونه از این شیوه استفاده پشتیبانی نکند، می‌تواند مقدار -۲ را از تابع () برگرداند، که باعث می‌شود sudo پیام نحوه استفاده را چاپ کرده و خارج شود.
implied_shell=bool
اگر کاربر برنامه‌ای را در خط فرمان مشخص نکند، sudo مسیر پوسته کاربر را به افزونه ارسال کرده و implied_shell را تنظیم می‌کند.
intercept_ptrace=bool
مشخص می‌کند که آیا سیستم از حالت رهگیری (intercept mode) با استفاده از ptrace(2) پشتیبانی می‌کند یا خیر. این مورد در حال حاضر تنها برای سیستم‌های لینوکسی صادق است که از فیلتر کردن seccomp(2) و عمل “trap” پشتیبانی می‌کنند. سایر سیستم‌ها برای پیاده‌سازی رهگیری از یک شیء اشتراکی پویا استفاده خواهند کرد. تنها از نسخه ۱.۱۹ رابط API به بعد در دسترس است.
intercept_setid=bool
مشخص می‌کند که آیا سیستم از اجرای باینری‌های set-user-ID و set-group-ID در حالت رهگیری پشتیبانی می‌کند یا خیر. این مورد در حال حاضر تنها برای سیستم‌های لینوکسی صادق است که از فیلتر کردن seccomp(2) و عمل “trap” پشتیبانی می‌کنند. در سیستم‌هایی که برای پیاده‌سازی رهگیری از یک شیء اشتراکی پویا استفاده می‌کنند، پیونددهنده پویا (ld.so یا معادل آن) پیش‌بارگذاری اشیاء اشتراکی را هنگام اجرای باینری‌های set-user-ID یا set-group-ID غیرفعال می‌کند. این امر حالت رهگیری را برای آن برنامه و هر برنامه دیگری که توسط آن اجرا می‌شود غیرفعال خواهد کرد. افزونه سیاست‌گذاری می‌تواند برای جلوگیری از این وضعیت، از اجرای یک باینری set-user-ID یا set-group-ID در حالت رهگیری خودداری کند. تنها از نسخه ۱.۱۹ رابط API به بعد در دسترس است.
login_class=string
کلاس ورود BSD جهت استفاده هنگام تنظیم محدودیت‌های منابع و مقدار nice، در صورت مشخص شدن با گزینه -c.
login_shell=bool
اگر کاربر گزینه -i را مشخص کرده باشد روی true تنظیم می‌شود و نشان می‌دهد که کاربر مایل است یک پوسته ورود (login shell) را اجرا کند.
max_groups=int
حداکثر تعداد گروه‌هایی که یک کاربر می‌تواند عضو آن‌ها باشد. این مقدار تنها در صورتی وجود خواهد داشت که تنظیم متناظر در sudo.conf(5) موجود باشد.
network_addrs=list
یک لیست جداشده با فاصله از آدرس‌های شبکه IP و ماسک‌های شبکه به فرم “addr/netmask ،” به عنوان مثال، “192.168.1.2/255.255.255.0”. جفت‌های آدرس و ماسک شبکه بسته به پشتیبانی سیستم‌عامل می‌توانند IPv4 یا IPv6 باشند. اگر آدرس شامل دونقطه (‘:’) باشد، یک آدرس IPv6 است، در غیر این صورت IPv4 است.
noninteractive=bool
اگر کاربر گزینه -n را مشخص کرده باشد روی true تنظیم می‌شود و نشان می‌دهد که sudo باید در حالت غیرتعاملی عمل کند. اگر تعامل با کاربر مورد نیاز باشد، افزونه ممکن است فرمانی را که در حالت غیرتعاملی اجرا شده است رد کند.
plugin_dir=string
پوشه پیش‌فرض افزونه‌ها که توسط بخش فرانت‌اند sudo استفاده می‌شود. این دایرکتوری پیش‌فرضی است که در زمان کامپایل تنظیم شده و ممکن است با دایرکتوری که افزونه در حال اجرا از آن بارگذاری شده است، مطابقت نداشته باشد. این مقدار ممکن است توسط افزونه برای یافتن فایل‌های پشتیبان استفاده شود.
plugin_path=string
نام مسیر افزونه‌ای که توسط فرانت‌اند sudo بارگذاری شده است. این نام مسیر به صورت کامل (fully-qualified) خواهد بود، مگر اینکه افزونه به صورت ایستا درون sudo کامپایل شده باشد.
preserve_environment=bool
اگر کاربر گزینه -E را مشخص کرده باشد روی true تنظیم می‌شود و نشان می‌دهد که کاربر مایل به حفظ محیط متغیرها است.
preserve_groups=bool
اگر کاربر گزینه -P را مشخص کرده باشد روی true تنظیم می‌شود و نشان می‌دهد که کاربر مایل است بردار گروه‌ها را به جای تنظیم بر اساس کاربر هدف (runas user)، حفظ کند.
progname=string
نام دستوری که sudo تحت عنوان آن اجرا شده است، معمولاً “sudo” یا “sudoedit”.
prompt=string
اعلانی که هنگام درخواست گذرواژه باید استفاده شود، در صورت مشخص شدن از طریق گزینه -p.
remote_host=string
نام میزبان راه دور برای اجرای دستور روی آن، در صورت مشخص شدن از طریق گزینه -h. پشتیبانی از اجرای دستور روی میزبان راه دور به گونه‌ای طراحی شده که از طریق یک برنامه کمکی که به جای دستور تعیین‌شده توسط کاربر اجرا می‌شود، پیاده‌سازی گردد. فرانت‌اند sudo تنها قادر به اجرای دستورات روی میزبان محلی است. تنها از نسخه ۱.۴ رابط API به بعد در دسترس است.
run_shell=bool
اگر کاربر گزینه -s را مشخص کرده باشد روی true تنظیم می‌شود و نشان می‌دهد که کاربر مایل به اجرای یک پوسته است.
runas_group=string
نام گروه یا شناسه گروه (group-ID) برای اجرای دستور با آن، در صورت مشخص شدن از طریق گزینه -g.
runas_user=string
نام کاربر یا شناسه کاربر (user-ID) برای اجرای دستور با آن، در صورت مشخص شدن از طریق گزینه -u.
selinux_role=string
نقش SELinux مورد استفاده هنگام اجرای دستور، در صورت مشخص شدن با گزینه -r.
selinux_type=string
نوع SELinux مورد استفاده هنگام اجرای دستور، در صورت مشخص شدن با گزینه -t.
set_home=bool
اگر کاربر گزینه -H را مشخص کرده باشد روی true تنظیم می‌شود. در صورت true بودن، متغیر محیطی HOME روی پوشه خانگی کاربر هدف تنظیم می‌شود.
sudoedit=bool
هنگامی که گزینه -e مشخص شده باشد یا دستور به صورت sudoedit فراخوانی گردد، روی true تنظیم می‌شود. افزونه باید یک ویرایشگر را در argv در تابع check_policy() جایگزین کند، یا در صورتی که افزونه از sudoedit پشتیبانی نکند مقدار -۲ را همراه با خطای نحوه استفاده بازگرداند. برای اطلاعات بیشتر، بخش check_policy() را ببینید.
timeout=string
مهلت زمانی (timeout) دستور که توسط کاربر از طریق گزینه -T مشخص شده است. همه افزونه‌ها از مهلت زمانی دستور پشتیبانی نمی‌کنند و توانایی کاربر در تعیین مهلت زمانی ممکن است توسط سیاست‌گذاری محدود شده باشد. قالب رشته مهلت زمانی وابسته به هر افزونه است.
update_ticket=bool
اگر کاربر گزینه -N را مشخص کرده باشد روی false تنظیم می‌شود و نشان می‌دهد که کاربر می‌خواهد از به‌روزرسانی هرگونه اعتبارنامه احراز هویت ذخیره‌شده خودداری کند. تنها از نسخه ۱.۲۰ رابط API به بعد در دسترس است.

ممکن است تنظیمات بیشتری در آینده اضافه شوند، بنابراین افزونه باید تنظیماتی را که نمی‌شناسد، بدون خطا نادیده بگیرد.

user_info
برداری از اطلاعات مربوط به کاربری که دستور را اجرا می‌کند در قالب رشته‌های “name=value” است. این بردار با یک اشاره‌گر NULL خاتمه می‌یابد.

هنگام تجزیه user_info ، افزونه باید آن را بر اساس اولین علامت مساوی (‘=’) تقسیم کند، زیرا فیلد name هرگز شامل مساوی نخواهد بود، اما مقدار value ممکن است شامل آن باشد.

مقادیر زیر ممکن است توسط sudo تنظیم شوند:

cols=int
تعداد ستون‌هایی که ترمینال کاربر پشتیبانی می‌کند. اگر هیچ دستگاه ترمینالی در دسترس نباشد، مقدار پیش‌فرض ۸۰ استفاده می‌شود.
cwd=string
دایرکتوری کاری فعلی کاربر.
egid=gid_t
شناسه گروه موثر (effective group-ID) کاربری که sudo را فراخوانی کرده است.
euid=uid_t
شناسه کاربر موثر (effective user-ID) کاربری که sudo را فراخوانی کرده است.
gid=gid_t
شناسه گروه واقعی (real group-ID) کاربری که sudo را فراخوانی کرده است.
groups=list
لیست گروه‌های تکمیلی کاربر در قالب رشته‌ای از شناسه‌های گروه جداشده با کاما.
host=string
نام میزبان (hostname) ماشین محلی که توسط فراخوانی سیستمی gethostname(2) بازگردانده شده است.
lines=int
تعداد خطوطی که ترمینال کاربر پشتیبانی می‌کند. اگر هیچ دستگاه ترمینالی در دسترس نباشد، مقدار پیش‌فرض ۲۴ استفاده می‌شود.
pgid=int
شناسه گروه فرآیندی که فرآیند در حال اجرای sudo عضو آن است. تنها از نسخه ۱.۲ رابط API به بعد در دسترس است.
pid=int
شناسه فرآیند (PID) مربوط به فرآیند در حال اجرای sudo. تنها از نسخه ۱.۲ رابط API به بعد در دسترس است.
ppid=int
شناسه فرآیند والد (PPID) فرآیند در حال اجرای sudo. تنها از نسخه ۱.۲ رابط API به بعد در دسترس است.
rlimit_as=soft,hard
حداکثر اندازه‌ای که فضای آدرس‌دهی فرآیند می‌تواند رشد کند (به بایت)، در صورت پشتیبانی سیستم‌عامل. حدود نرم (soft) و سخت (hard) با کاما از هم جدا شده‌اند. مقدار “infinity” نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است.
rlimit_core=soft,hard
بزرگ‌ترین اندازه فایل core dump که می‌تواند ایجاد شود (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار “infinity” نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است.
rlimit_cpu=soft,hard
حداکثر زمان پردازنده (CPU time) که فرآیند می‌تواند استفاده کند (به ثانیه). حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار “infinity” نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است.
rlimit_data=soft,hard
حداکثر اندازه بخش داده (data segment) برای فرآیند (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار “infinity” نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است.
rlimit_fsize=soft,hard
بزرگ‌ترین اندازه فایلی که فرآیند می‌تواند ایجاد کند (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار “infinity” نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است.
rlimit_locks=soft,hard
حداکثر تعداد قفل‌هایی که فرآیند می‌تواند ایجاد کند، در صورت پشتیبانی سیستم‌عامل. حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار “infinity” نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است.
rlimit_memlock=soft,hard
حداکثر اندازه‌ای که فرآیند می‌تواند در حافظه قفل کند (به بایت)، در صورت پشتیبانی سیستم‌عامل. حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار “infinity” نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است.
rlimit_nofile=soft,hard
حداکثر تعداد فایل‌هایی که فرآیند می‌تواند همزمان باز نگه دارد. حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار “infinity” نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است.
rlimit_nproc=soft,hard
حداکثر تعداد فرآیندهایی که کاربر می‌تواند به طور همزمان اجرا کند. حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار “infinity” نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است.
rlimit_rss=soft,hard
حداکثر اندازه‌ای که مقدار فضای مقیم (resident set size) فرآیند می‌تواند رشد کند (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار “infinity” نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است.
rlimit_stack=soft,hard
حداکثر اندازه‌ای که پشته (stack) فرآیند می‌تواند رشد کند (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا شده‌اند. مقدار “infinity” نشان می‌دهد که هیچ محدودیتی وجود ندارد. تنها از نسخه ۱.۱۶ رابط API به بعد در دسترس است.
sid=int
شناسه نشست (session ID) مربوط به فرآیند در حال اجرای sudo یا ۰ اگر sudo بخشی از یک نشست کنترل کار (job control) سازگار با POSIX نباشد. تنها از نسخه ۱.۲ رابط API به بعد در دسترس است.
tcpgid=int
شناسه گروه فرآیند پیش‌زمینه مرتبط با دستگاه ترمینال متصل به فرآیند sudo یا ۰ اگر هیچ ترمینالی موجود نباشد. تنها از نسخه ۱.۲ رابط API به بعد در دسترس است.
tty=string
مسیر به دستگاه ترمینال کاربر، در صورت وجود. این مدخل تنها در صورتی موجود است که کاربر دستگاه ترمینال مرتبط با نشست داشته باشد.
ttydev=dev_t
شماره دستگاه ترمینال کاربر، در صورت وجود، قالب‌بندی‌شده به عنوان یک مقدار long long. این مدخل تنها در صورتی وجود دارد که کاربر دستگاه ترمینال مرتبط با این نشست داشته باشد. تنها از نسخه ۱.۲۲ رابط API به بعد در دسترس است.
uid=uid_t
شناسه کاربر واقعی (real user-ID) کاربری که sudo را فراخوانی می‌کند.
umask=octal
ماسک ایجاد فایل کاربر فراخوان. تنها از نسخه ۱.۱۰ رابط API به بعد در دسترس است.
user=string
نام کاربری که sudo را فراخوانی می‌کند.
user_env
محیط متغیرهای کاربر در قالب یک بردار خاتمه‌یافته با NULL از رشته‌های “name=value” است.

هنگام تجزیه user_env ، افزونه باید آن را بر اساس اولین علامت مساوی (‘=’) تقسیم کند، زیرا فیلد name هرگز شامل مساوی نخواهد بود، اما مقدار value ممکن است شامل آن باشد.

plugin_options
هر رشته‌ای (غیر از کامنت‌ها) که بلافاصله پس از مسیر افزونه قرار گیرد، به عنوان آرگومان به افزونه ارسال می‌شود. این آرگومان‌ها با فاصله جدا می‌شوند و در قالب یک آرایه از رشته‌ها که با NULL خاتمه یافته است به افزونه ارسال می‌گردند. اگر هیچ آرگومانی مشخص نشده باشد، plugin_options یک اشاره‌گر NULL خواهد بود.

پارامتر plugin_options تنها از نسخه ۱.۲ رابط API به بعد در دسترس است. یک افزونه باید پیش از استفاده از plugin_options ، نسخه API مشخص‌شده توسط فرانت‌اند sudo را بررسی کند. کوتاهی در این کار ممکن است منجر به کرش و فروپاشی برنامه شود.

errstr
اگر تابع () مقداری غیر از ۱ برگرداند، افزونه ممکن است پیامی را برای توصیف شکست یا خطا در errstr ذخیره کند. سپس فرانت‌اند sudo این مقدار را به تمام افزونه‌های بازرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمانی که تابع close() افزونه فراخوانی شود معتبر بماند.

پارامتر errstr تنها از نسخه ۱.۱۵ رابط API به بعد در دسترس است. یک افزونه باید پیش از استفاده از errstr ، نسخه API مشخص‌شده توسط فرانت‌اند sudo را بررسی کند. کوتاهی در این کار ممکن است منجر به کرش و فروپاشی برنامه شود.

close
void (*close)(int exit_status, int error);

تابع () هنگامی فراخوانی می‌شود که کار sudo به پایان رسیده باشد، اندکی پیش از خروج آن. از نسخه ۱.۱۵ رابط API به بعد، close() صرف‌نظر از اینکه دستوری واقعاً اجرا شده باشد یا خیر فراخوانی می‌شود. این امر به افزونه‌ها امکان می‌دهد تا حتی در صورت اجرا نشدن یک دستور نیز عملیات پاکسازی را انجام دهند. تنها بر اساس آرگومان‌های ارائه‌شده به تابع close() نمی‌توان تشخیص داد که آیا دستوری اجرا شده است یا خیر. برای تعیین اینکه آیا یک دستور واقعاً اجرا شده است یا نه، افزونه باید پیگیری کند که آیا تابع check_policy() با موفقیت بازگشته است یا خیر.

آرگومان‌های تابع به شرح زیر هستند:

exit_status
وضعیت خروج دستور، همان‌طور که توسط فراخوانی سیستمی wait(2) برگردانده شده است، یا صفر در صورتی که هیچ دستوری اجرا نشده باشد. اگر مقدار error غیر صفر باشد، مقدار exit_status تعریف‌نشده است.
error
اگر دستور نتواند اجرا شود، این فیلد روی مقدار errno تنظیم می‌شود که توسط فراخوانی سیستمی execve(2) ایجاد شده است. افزونه مسئول نمایش اطلاعات خطا از طریق تابع () یا () است. اگر دستور با موفقیت اجرا شده باشد، مقدار error صفر است.

اگر هیچ تابع () تعریف نشده باشد، هیچ افزونه ثبت ورودی/خروجی (I/O logging) بارگذاری نشده باشد، و هیچ‌یک از گزینه‌های timeout یا use_pty در لیست command_info تنظیم نشده باشند، فرانت‌اند sudo ممکن است به جای اجرای دستور به عنوان یک فرآیند فرزند، آن را مستقیماً اجرا کند.

show_version
int (*show_version)(int verbose);

تابع () توسط sudo هنگامی فراخوانی می‌شود که کاربر گزینه -V را مشخص کرده باشد. افزونه می‌تواند اطلاعات نسخه خود را از طریق تابع conversation() یا sudo_plugin_printf() با استفاده از SUDO_CONV_INFO_MSG به کاربر نمایش دهد. اگر کاربر اطلاعات دقیق نسخه را درخواست کند، فلگ verbose غیر صفر خواهد بود.

در صورت موفقیت ۱، در صورت شکست ۰، در صورت خطای عمومی -۱، و در صورت خطای نحوه استفاده -۲ برمی‌گرداند، اگرچه مقدار بازگشتی در حال حاضر نادیده گرفته می‌شود.

check_policy
int (*check_policy)(int argc, char * const argv[], char *env_add[],
    char **command_info[], char **argv_out[], char **user_env_out[],
    const char **errstr);

تابع () توسط sudo فراخوانی می‌شود تا مشخص گردد آیا کاربر مجاز به اجرای دستورات مشخص‌شده هست یا خیر.

اگر گزینه sudoedit در آرایه settings که به تابع () ارسال شده است فعال شده باشد، کاربر حالت sudoedit را درخواست کرده است. sudoedit مکانیزمی برای ویرایش یک یا چند فایل است که در آن ویرایشگر به جای دسترسی‌های ارتقاءیافته، با اعتبارنامه‌های خود کاربر اجرا می‌شود. sudo این کار را با ایجاد نسخه‌های موقت قابل نوشتن توسط کاربر از فایل‌های مورد نظر و سپس رونویسی نسخه‌های اصلی با این نسخه‌های موقت پس از اتمام ویرایش انجام می‌دهد. اگر افزونه از sudoedit پشتیبانی کند، باید را در لیست command_info تنظیم نماید. افزونه مسئول انتخاب ویرایشگر مورد استفاده است، که می‌تواند از یک متغیر در محیط کاربر مانند EDITOR انتخاب شده و باید در argv_out ذخیره شود (متغیرهای محیطی ممکن است شامل گزینه‌های خط فرمان باشند). فایل‌هایی که باید ویرایش شوند باید از argv به argv_out کپی شوند و با یک عنصر ‘--’ از ویرایشگر و آرگومان‌های آن جدا گردند. این ‘--’ پیش از اجرای ویرایشگر توسط sudo حذف خواهد شد. افزونه همچنین می‌تواند sudoedit_nfiles را روی تعداد فایل‌های مورد ویرایش در لیست command_info تنظیم کند؛ این مقدار تنها از نسخه ۱.۲۱ رابط API به بعد توسط فرانت‌اند sudo استفاده خواهد شد.

تابع () در صورتی که دستور مجاز باشد مقدار ۱، در صورت عدم مجاز بودن ۰، در صورت خطای عمومی -۱، و در صورت خطای نحوه استفاده یا در صورتی که sudoedit مشخص شده باشد ولی توسط افزونه پشتیبانی نشود، مقدار -۲ را بازمی‌گرداند. در حالت آخر، sudo پیش از خروج، پیام نحوه استفاده را چاپ خواهد کرد. اگر خطایی رخ دهد، افزونه می‌تواند به صورت اختیاری تابع conversation() یا sudo_plugin_printf() را با SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری را به کاربر نمایش دهد.

آرگومان‌های تابع به شرح زیر هستند:

argc
تعداد عناصر موجود در argv ، بدون احتساب اشاره‌گر پایانی NULL.
argv
بردار آرگومان که دستوری را که کاربر مایل به اجرای آن است توصیف می‌کند، به همان شکلی که به فراخوانی سیستمی execve(2) ارسال می‌شود. این بردار با یک اشاره‌گر NULL خاتمه می‌یابد.
env_add
متغیرهای محیطی اضافی که توسط کاربر در خط فرمان مشخص شده‌اند، در قالب یک بردار خاتمه‌یافته با NULL از رشته‌های “name=value”. افزونه در صورتی که یک یا چند متغیر مجاز به تنظیم نباشند می‌تواند دستور را رد کند، یا ممکن است چنین متغیرهایی را بدون اعلام خطا نادیده بگیرد.

هنگام تجزیه env_add ، افزونه باید بر اساس اولین علامت مساوی (‘=’) تقسیم کند، زیرا فیلد name هرگز شامل مساوی نخواهد بود، اما مقدار value ممکن است شامل آن باشد.

command_info
اطلاعات مربوط به دستوری که اجرا می‌شود در قالب رشته‌های “name=value”. این مقادیر توسط sudo برای تنظیم محیط اجرا هنگام اجرای یک دستور استفاده می‌شوند. این افزونه مسئول ایجاد و پر کردن بردار است، که باید با یک اشاره‌گر NULL خاتمه یابد. مقادیر زیر توسط sudo شناسایی می‌شوند:
apparmor_profile=string
پروفایل AppArmor برای انتقال به آن هنگام اجرای دستور. تنها از نسخه 1.19 به بعد API در دسترس است.
chroot=string
دایرکتوری ریشه برای استفاده هنگام اجرای دستور.
closefrom=number
در صورت مشخص شدن، sudo تمام توصیف‌کننده‌های فایل با مقداری برابر با number یا بالاتر را خواهد بست.
command=string
مسیر کامل دستوری که باید اجرا شود.
cwd=string
دایرکتوری کاری فعلی برای تغییر به آن هنگام اجرای دستور. اگر sudo نتواند به دایرکتوری کاری جدید تغییر مسیر دهد، دستور اجرا نخواهد شد مگر اینکه cwd_optional نیز تنظیم شده باشد (به زیر نگاه کنید).
cwd_optional=bool
در صورت تنظیم، sudo ناتوانی در تغییر به دایرکتوری کاری جدید را به عنوان خطای غیرمهلک در نظر می‌گیرد. این تنظیم هیچ تاثیری ندارد مگر اینکه نیز تنظیم شده باشد.
exec_background=bool
به‌طور پیش‌فرض، sudo تا زمانی که خودش در پیش‌زمینه در حال اجرا است، دستور را به عنوان فرایند پیش‌زمینه اجرا می‌کند. هنگامی که exec_background فعال باشد و دستور در یک شبه‌ترمینال اجرا شود (به دلیل ثبت لاگ I/O یا تنظیم use_pty )، دستور به عنوان یک فرایند پس‌زمینه اجرا خواهد شد. تلاش‌ها برای خواندن از ترمینال کنترلی (یا تغییر تنظیمات ترمینال) منجر به تعلیق دستور با سیگنال SIGTTIN (یا در مورد تنظیمات ترمینال، SIGTTOU ) خواهد شد. اگر این اتفاق زمانی بیفتد که sudo یک فرایند پیش‌زمینه است، ترمینال کنترلی به دستور واگذار شده و بدون نیاز به دخالت کاربر، در پیش‌زمینه از سر گرفته می‌شود. مزیت اجرای اولیه دستور در پس‌زمینه این است که sudo نیازی به خواندن از ترمینال ندارد مگر اینکه دستور صریحاً آن را درخواست کند. در غیر این صورت، هر ورودی ترمینال باید به دستور تحویل داده شود، چه به آن نیاز داشته باشد و چه نداشته باشد (هسته سیستم‌عامل ترمینال‌ها را بافر می‌کند، بنابراین نمی‌توان تشخیص داد که آیا دستور واقعاً ورودی را می‌خواهد یا خیر). این با رفتار تاریخی sudo یا وضعیتی که دستور در شبه‌ترمینال اجرا نمی‌شود تفاوت دارد.

برای اینکه این سازوکار بدون مشکل کار کند، سیستم‌عامل باید از راه‌اندازی مجدد خودکار فراخوان‌های سیستمی پشتیبانی کند. متاسفانه همه سیستم‌عامل‌ها به‌طور پیش‌فرض این کار را انجام نمی‌دهند، و حتی سیستم‌هایی که انجام می‌دهند نیز ممکن است اشکالاتی داشته باشند. برای مثال، macOS در راه‌اندازی مجدد فراخوان‌های سیستمی () و () ناموفق است (این یک باگ در macOS است). علاوه بر این، از آنجا که این رفتار به متوقف شدن دستور با سیگنال‌های SIGTTIN یا SIGTTOU وابسته است، برنامه‌هایی که این سیگنال‌ها را دریافت کرده و خود را با سیگنال دیگری (معمولاً SIGTOP) معلق می‌کنند، به‌طور خودکار به پیش‌زمینه منتقل نخواهند شد. برخی از نسخه‌های دستور su(1) در لینوکس به این شکل رفتار می‌کنند. به همین دلیل، یک افزونه نباید exec_background را تنظیم کند مگر اینکه صریحاً توسط مدیر سیستم فعال شده باشد و باید راهی برای فعال یا غیرفعال کردن آن بر مبنای هر دستور وجود داشته باشد.

این تنظیم هیچ تاثیری ندارد مگر اینکه ثبت لاگ I/O فعال باشد یا use_pty فعال شده باشد.

execfd=number
در صورت مشخص شدن، sudo از فراخوان سیستمی fexecve(2) به جای execve(2) برای اجرای دستور استفاده خواهد کرد. مقدار مشخص‌شده number باید به یک توصیف‌کننده فایل باز ارجاع داشته باشد.
intercept=bool
در صورت تنظیم، sudo تلاش‌ها برای اجرای یک دستور بعدی را رهگیری کرده و با استفاده از تابع () افزونه خط‌مشی، یک بررسی خط‌مشی انجام می‌دهد تا مشخص کند که آیا اجرای دستور مجاز است یا خیر. از این سازوکار می‌توان برای جلوگیری از گریز به پوسته در پلتفرم‌های پشتیبانی‌شده استفاده کرد، اما دارای محدودیت‌های متعددی است. برای جزئیات بیشتر به بخش Preventing shell escapes در sudoers(5) مراجعه کنید. تنها از نسخه 1.18 به بعد API در دسترس است.
intercept_verify=bool
در صورت تنظیم، sudo تلاش خواهد کرد تا بررسی کند که دستوری که در حالت رهگیری اجرا می‌شود، نام مسیر، آرگومان‌های خط فرمان و محیط مورد انتظار را دارد یا خیر. این تنظیم هیچ تاثیری ندارد مگر اینکه use_ptrace نیز فعال باشد. تنها از نسخه 1.20 به بعد API در دسترس است.
iolog_compress=bool
اگر افزونه‌های ثبت لاگ I/O (در صورت وجود) باید داده‌های لاگ را فشرده کنند، روی true تنظیم شود. این یک راهنمایی (hint) برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد.
iolog_group=string
گروهی که مالک فایل‌ها و دایرکتوری‌های لاگ I/O تازه ایجادشده خواهد بود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد.
iolog_mode=octal
حالت دسترسی فایل برای استفاده هنگام ایجاد فایل‌ها و دایرکتوری‌های لاگ I/O. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد.
iolog_user=string
کاربری که مالک فایل‌ها و دایرکتوری‌های لاگ I/O تازه ایجادشده خواهد بود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد.
iolog_path=string
مسیر کامل فایل یا دایرکتوری‌ای که لاگ I/O در آن ذخیره می‌شود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد. اگر هیچ افزونه ثبت لاگ I/O بارگذاری نشده باشد، این تنظیم هیچ تاثیری ندارد.
iolog_stdin=bool
اگر افزونه‌های ثبت لاگ I/O (در صورت وجود) باید ورودی استاندارد را در صورتی که به یک دستگاه ترمینال متصل نیست ثبت کنند، روی true تنظیم شود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد.
iolog_stdout=bool
اگر افزونه‌های ثبت لاگ I/O (در صورت وجود) باید خروجی استاندارد را در صورتی که به یک دستگاه ترمینال متصل نیست ثبت کنند، روی true تنظیم شود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد.
iolog_stderr=bool
اگر افزونه‌های ثبت لاگ I/O (در صورت وجود) باید خطای استاندارد را در صورتی که به یک دستگاه ترمینال متصل نیست ثبت کنند، روی true تنظیم شود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد.
iolog_ttyin=bool
اگر افزونه‌های ثبت لاگ I/O (در صورت وجود) باید تمام ورودی‌های ترمینال را ثبت کنند، روی true تنظیم شود. این فقط شامل ورودی تایپ‌شده توسط کاربر است و شامل ورودی از طریق لوله (pipe) یا تغییرمسیریافته از یک فایل نمی‌شود. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد.
iolog_ttyout=bool
اگر افزونه‌های ثبت لاگ I/O (در صورت وجود) باید تمام خروجی‌های ترمینال را ثبت کنند، روی true تنظیم شود. این فقط شامل خروجی نمایش‌یافته بر روی صفحه است، نه خروجی ارسال‌شده به لوله یا فایل. این یک راهنمایی برای افزونه ثبت لاگ I/O است که ممکن است آن را نادیده بگیرد.
login_class=string
کلاس ورود BSD برای استفاده هنگام تنظیم محدودیت‌های منابع و مقدار nice (اختیاری). این گزینه فقط روی سیستم‌هایی تنظیم می‌شود که از کلاس‌های ورود پشتیبانی می‌کنند.
nice=int
مقدار nice (اولویت) برای استفاده هنگام اجرای دستور. مقدار nice، در صورت مشخص شدن، اولویت مرتبط با را در سیستم‌های BSD نادیده می‌گیرد.
log_subcmds=bool
در صورت تنظیم، sudo تابع accept() افزونه ممیزی را فراخوانی می‌کند تا هنگام اجرای یک دستور بعدی توسط دستور اصلی، در صورت پشتیبانی سیستم، آن را ثبت کند. اگر intercept نیز مشخص شده باشد، log_subcmds نادیده گرفته خواهد شد. برای اطلاعات بیشتر به بخش Preventing shell escapes در sudoers(5) مراجعه کنید. تنها از نسخه 1.18 به بعد API در دسترس است.
noexec=bool
در صورت تنظیم، از اجرای سایر برنامه‌ها توسط دستور جلوگیری می‌کند.
preserve_fds=list
فهرستی از توصیف‌کننده‌های فایل که با کاما از یکدیگر جدا شده‌اند و باید صرف‌نظر از مقدار تنظیم حفظ شوند. تنها از نسخه 1.5 به بعد API در دسترس است.
preserve_groups=bool
در صورت تنظیم، sudo بردار گروه‌های کاربر را به جای مقداردهی اولیه بر اساس runas_user حفظ خواهد کرد.
rlimit_as=soft,hard
حداکثر اندازه‌ای که فضای آدرس فرایند می‌تواند تا آن گسترش یابد (به بایت)، در صورت پشتیبانی سیستم‌عامل. حدود نرم (soft) و سخت (hard) با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار “infinity” نشان‌دهنده عدم وجود محدودیت است. مقدار “user” باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار “default” باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است.
rlimit_core=soft,hard
بزرگ‌ترین اندازه فایل تخلیه حافظه (core dump) که ممکن است ایجاد شود (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار “infinity” نشان‌دهنده عدم وجود محدودیت است. مقدار “user” باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار “default” باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است.
rlimit_cpu=soft,hard
حداکثر مدت زمان پردازنده که فرایند می‌تواند استفاده کند (به ثانیه). حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار “infinity” نشان‌دهنده عدم وجود محدودیت است. مقدار “user” باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار “default” باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است.
rlimit_data=soft,hard
حداکثر اندازه بخش داده برای فرایند (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار “infinity” نشان‌دهنده عدم وجود محدودیت است. مقدار “user” باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار “default” باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است.
rlimit_fsize=soft,hard
بزرگ‌ترین اندازه فایلی که فرایند می‌تواند ایجاد کند (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار “infinity” نشان‌دهنده عدم وجود محدودیت است. مقدار “user” باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار “default” باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است.
rlimit_locks=soft,hard
حداکثر تعداد قفل‌هایی که فرایند می‌تواند برقرار کند، در صورت پشتیبانی سیستم‌عامل. حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار “infinity” نشان‌دهنده عدم وجود محدودیت است. مقدار “user” باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار “default” باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است.
rlimit_memlock=soft,hard
حداکثر اندازه‌ای که فرایند می‌تواند در حافظه قفل کند (به بایت)، در صورت پشتیبانی سیستم‌عامل. حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار “infinity” نشان‌دهنده عدم وجود محدودیت است. مقدار “user” باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار “default” باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است.
rlimit_nofile=soft,hard
حداکثر تعداد فایل‌هایی که فرایند می‌تواند باز داشته باشد. حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار “infinity” نشان‌دهنده عدم وجود محدودیت است. مقدار “user” باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار “default” باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است.
rlimit_nproc=soft,hard
حداکثر تعداد فرایندهایی که کاربر می‌تواند به‌طور همزمان اجرا کند. حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار “infinity” نشان‌دهنده عدم وجود محدودیت است. مقدار “user” باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار “default” باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است.
rlimit_rss=soft,hard
حداکثر اندازه‌ای که اندازه مجموعه مقیم (resident set size) فرایند می‌تواند تا آن گسترش یابد (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار “infinity” نشان‌دهنده عدم وجود محدودیت است. مقدار “user” باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار “default” باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است.
rlimit_stack=soft,hard
حداکثر اندازه‌ای که پشته فرایند می‌تواند تا آن گسترش یابد (به بایت). حدود نرم و سخت با کاما از یکدیگر جدا می‌شوند. اگر تنها یک مقدار مشخص شود، هر دو حد سخت و نرم روی آن تنظیم می‌شوند. مقدار “infinity” نشان‌دهنده عدم وجود محدودیت است. مقدار “user” باعث حفظ محدودیت منبع کاربر فراخواننده می‌شود. مقدار “default” باعث استفاده از محدودیت منبع پیش‌فرض کاربر هدف در سیستم‌هایی می‌شود که امکان پیکربندی محدودیت‌های منبع به ازای هر کاربر را فراهم می‌کنند. تنها از نسخه 1.18 به بعد API در دسترس است.
runas_egid=gid
شناسه گروه مؤثر (effective group-ID) برای اجرای دستور با آن. در صورت عدم تعیین، مقدار runas_gid استفاده می‌شود.
runas_euid=uid
شناسه کاربر مؤثر (effective user-ID) برای اجرای دستور با آن. در صورت عدم تعیین، مقدار runas_uid استفاده می‌شود.
runas_gid=gid
شناسه گروه (group-ID) برای اجرای دستور با آن.
runas_group=string
نام گروهی که دستور با آن اجرا خواهد شد، در صورتی که با گروه پیش‌فرض runas_user متفاوت باشد. این مقدار صرفاً برای مقاصد ممیزی ارائه شده است؛ پیشخوان sudo هنگام اجرای دستور از و runas_gid استفاده می‌کند.
runas_groups=list
بردار گروه‌های کمکی (supplementary group vector) برای استفاده در دستور به شکل فهرستی از شناسه‌های گروه جداشده با کاما. اگر تنظیم شده باشد، این گزینه نادیده گرفته می‌شود.
runas_uid=uid
شناسه کاربر (user-ID) برای اجرای دستور با آن.
runas_user=string
نام کاربری که دستور با آن اجرا خواهد شد، که باید با runas_euid (یا در صورت عدم تنظیم runas_euid ، با runas_uid ) مطابقت داشته باشد. این مقدار صرفاً برای مقاصد ممیزی ارائه شده است؛ پیشخوان sudo هنگام اجرای دستور از runas_euid و runas_uid استفاده می‌کند.
selinux_role=string
نقش SELinux برای استفاده هنگام اجرای دستور.
selinux_type=string
نوع SELinux برای استفاده هنگام اجرای دستور.
set_utmp=bool
ایجاد یک ورودی utmp (یا utmpx) هنگام تخصیص یک شبه‌ترمینال. به‌طور پیش‌فرض، ورودی جدید یک کپی از ورودی utmp موجود کاربر (در صورت وجود) خواهد بود، همراه با به‌روزرسانی فیلدهای tty، time، type و pid.
sudoedit=bool
روی true تنظیم می‌شود هنگامی که در حالت sudoedit باشد. این افزونه ممکن است حالت sudoedit را فعال کند حتی اگر sudo به‌عنوان sudoedit فراخوانی نشده باشد. این به افزونه اجازه می‌دهد تا جایگزینی دستور را انجام داده و در صورت تلاش کاربر برای اجرای یک ویرایشگر، حالت sudoedit را به‌طور شفاف فعال سازد.
sudoedit_checkdir=bool
برای غیرفعال کردن بررسی‌های قابلیت نوشتن در دایرکتوری در sudoedit روی false تنظیم کنید. به‌طور پیش‌فرض، sudoedit نسخه 1.8.16 و بالاتر، تمام بخش‌های دایرکتوری در مسیر مورد ویرایش را از نظر قابلیت نوشتن توسط کاربر فراخواننده بررسی می‌کند. پیوندهای نمادین در دایرکتوری‌های قابل نوشتن دنبال نخواهند شد و sudoedit از ویرایش فایلی که در یک دایرکتوری قابل نوشتن قرار دارد خودداری می‌کند. این محدودیت‌ها زمانی که sudoedit توسط root اجرا شود اعمال نمی‌گردند. گزینه sudoedit_checkdir می‌تواند روی false تنظیم شود تا این بررسی غیرفعال گردد. تنها از نسخه 1.8 به بعد API در دسترس است.
sudoedit_follow=bool
روی true تنظیم شود تا به sudoedit اجازه ویرایش فایل‌هایی که پیوند نمادین هستند داده شود. به‌طور پیش‌فرض، sudoedit نسخه 1.8.15 و بالاتر از باز کردن یک پیوند نمادین خودداری می‌کند. گزینه sudoedit_follow می‌تواند برای بازگرداندن رفتار قدیمی‌تر و مجاز ساختن sudoedit به باز کردن پیوندهای نمادین استفاده شود. تنها از نسخه 1.8 به بعد API در دسترس است.
sudoedit_nfiles=number
تعداد فایل‌هایی که باید توسط کاربر ویرایش شوند. در صورت وجود، این مقدار توسط پیشخوان sudo استفاده خواهد شد تا مشخص شود کدام عناصر بردار argv_out فایل‌های مورد ویرایش هستند. عنصر ‘--’ باید بلافاصله پیش از اولین فایل مورد ویرایش قرار گیرد. اگر sudoedit_nfiles مشخص نشده باشد، پیشخوان sudo از موقعیت عنصر ‘--’ برای تعیین محل شروع فهرست فایل‌ها استفاده خواهد کرد. تنها از نسخه 1.21 به بعد API در دسترس است.
timeout=int
مهلت زمانی دستور. اگر غیرصفر باشد، پس از انقضای مهلت زمانی دستور خاتمه داده خواهد شد (کشته می‌شود).
umask=octal
ماسک ایجاد فایل برای استفاده هنگام اجرای دستور. این مقدار ممکن است در برخی سیستم‌ها توسط PAM یا login.conf نادیده گرفته شود، مگر اینکه گزینه umask_override نیز تنظیم شده باشد.
umask_override=bool
مقدار مشخص‌شده توسط گزینه umask را مجبور می‌کند تا هر umask تعیین‌شده توسط PAM یا login.conf را نادیده بگیرد.
use_ptrace=bool
در صورت تنظیم، sudo از ptrace(2) برای پیاده‌سازی حالت رهگیری در صورت پشتیبانی سیستم استفاده خواهد کرد. این تنظیم هیچ تاثیری ندارد مگر اینکه intercept نیز تنظیم شده باشد. تنها از نسخه 1.19 به بعد API در دسترس است.
use_pty=bool
صرف‌نظر از اینکه لاگ‌گیری I/O در حال استفاده باشد یا خیر، یک شبه‌ترمینال برای اجرای دستور در آن تخصیص می‌دهد. به‌طور پیش‌فرض، sudo تنها زمانی دستور را در یک شبه‌ترمینال اجرا می‌کند که یک افزونه ثبت لاگ I/O بارگذاری شده باشد.
utmp_user=string
نام کاربری برای استفاده هنگام ساخت یک ورودی utmp (یا utmpx) جدید در زمانی که فعال است. این گزینه می‌تواند برای تنظیم فیلد کاربر در ورودی utmp روی کاربری که دستور با آن اجرا می‌شود به جای کاربر فراخواننده استفاده گردد. در صورت عدم تنظیم، sudo ورودی جدید را بر اساس ورودی موجود کاربر فراخواننده پایه‌گذاری خواهد کرد.

مقادیر پشتیبانی‌نشده نادیده گرفته خواهند شد.

argv_out
بردار آرگومان‌های خاتمه‌یافته با NULL برای ارسال به فراخوان سیستمی execve(2) هنگام اجرای دستور. افزونه مسئول تخصیص حافظه و پر کردن این بردار است.
user_env_out
بردار محیطی خاتمه‌یافته با NULL برای استفاده هنگام اجرای دستور. افزونه مسئول تخصیص حافظه و پر کردن این بردار است.
errstr
اگر تابع () مقداری به جز 1 بازگرداند، افزونه می‌تواند پیامی حاوی شرح شکست یا خطا را در errstr ذخیره کند. سپس پیشخوان sudo این مقدار را به تمام افزونه‌های ممیزی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمانی که تابع close() افزونه فراخوانی شود معتبر باقی بماند.

پارامتر errstr تنها از نسخه 1.15 به بعد API در دسترس است. یک افزونه باید نسخه API مشخص‌شده توسط پیشخوان sudo را قبل از استفاده از errstr بررسی کند. عدم انجام این کار ممکن است منجر به کرش شود.

list
int (*list)(int argc, char * const argv[], int verbose,
    const char *user, const char **errstr);

فهرست کردن اختیارات موجود برای کاربر فراخواننده. در صورت موفقیت 1، در صورت شکست 0، و در صورت بروز خطا -1 بازمی‌گرداند. در صورت بروز خطا، افزونه می‌تواند به صورت اختیاری تابع () یا () را با SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری به کاربر ارائه دهد.

اختیارات باید از طریق تابع () یا () با استفاده از SUDO_CONV_INFO_MSG ارائه شوند.

آرگومان‌های تابع به شرح زیر هستند:

argc
تعداد عناصر موجود در argv ، بدون احتساب اشاره‌گر پایانی NULL.
argv
اگر غیر از NULL باشد، یک بردار آرگومان است که دستوری را که کاربر مایل است در برابر خط‌مشی بررسی کند توصیف می‌نماید، به همان صورتی که به فراخوان سیستمی execve(2) ارسال می‌شد. اگر دستور توسط خط‌مشی مجاز باشد، مسیر کامل دستور باید همراه با هرگونه آرگومان خط فرمان نمایش داده شود.
verbose
فلگی که مشخص می‌کند فهرست‌بندی در حالت پرگو (verbose) انجام شود یا خیر.
user
نام یک کاربر دیگر برای فهرست کردن اختیارات او در صورتی که خط‌مشی اجازه دهد. اگر NULL باشد، افزونه باید اختیارات کاربر فراخواننده را فهرست کند.
errstr
اگر تابع () مقداری به جز 1 بازگرداند، افزونه می‌تواند پیامی حاوی شرح شکست یا خطا را در errstr ذخیره کند. سپس پیشخوان sudo این مقدار را به تمام افزونه‌های ممیزی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمانی که تابع close() افزونه فراخوانی شود معتبر باقی بماند.

پارامتر errstr تنها از نسخه 1.15 به بعد API در دسترس است. یک افزونه باید نسخه API مشخص‌شده توسط پیشخوان sudo را قبل از استفاده از errstr بررسی کند. عدم انجام این کار ممکن است منجر به کرش شود.

validate
int (*validate)(const char **errstr);

تابع () زمانی فراخوانی می‌شود که sudo با گزینه -v اجرا شده باشد. برای افزونه‌های خط‌مشی مانند sudoers که گواهی‌های احراز هویت را کش می‌کنند، این تابع گواهی‌ها را اعتبارسنجی کرده و در کش قرار می‌دهد.

اگر افزونه از کش کردن گواهی‌های احراز هویت پشتیبانی نمی‌کند، تابع () باید NULL باشد.

در صورت موفقیت 1، در صورت شکست 0، و در صورت بروز خطا -1 بازمی‌گرداند. در صورت بروز خطا، افزونه می‌تواند به صورت اختیاری تابع () یا () را با SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری به کاربر ارائه دهد.

آرگومان‌های تابع به شرح زیر هستند:

errstr
اگر تابع () مقداری به جز 1 بازگرداند، افزونه می‌تواند پیامی حاوی شرح شکست یا خطا را در errstr ذخیره کند. سپس پیشخوان sudo این مقدار را به تمام افزونه‌های ممیزی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمانی که تابع close() افزونه فراخوانی شود معتبر باقی بماند.

پارامتر errstr تنها از نسخه 1.15 به بعد API در دسترس است. یک افزونه باید نسخه API مشخص‌شده توسط پیشخوان sudo را قبل از استفاده از errstr بررسی کند. عدم انجام این کار ممکن است منجر به کرش شود.

invalidate
void (*invalidate)(int rmcred);

تابع () زمانی فراخوانی می‌شود که sudo با گزینه -k یا -K اجرا شده باشد. برای افزونه‌های خط‌مشی مانند sudoers که گواهی‌های احراز هویت را کش می‌کنند، این تابع گواهی‌ها را باطل می‌سازد. اگر فلگ rmcred غیرصفر باشد، افزونه ممکن است گواهی‌ها را به جای باطل‌سازیِ ساده حذف کند.

اگر افزونه از کش کردن گواهی‌های احراز هویت پشتیبانی نمی‌کند، تابع () باید NULL باشد.

init_session
int (*init_session)(struct passwd *pwd, char **user_env[],
    const char **errstr);

تابع () قبل از اینکه sudo محیط اجرا را برای دستور آماده کند فراخوانی می‌شود. این تابع در فرایند والد sudo قبل از هرگونه تغییر شناسه کاربر یا شناسه گروه اجرا می‌شود. از این تابع می‌توان برای راه‌اندازی نشست‌هایی استفاده کرد که توسط command_info پشتیبانی نمی‌شوند، مانند باز کردن یک نشست PAM. از تابع close() می‌توان برای بستن نشستی که توسط init_session() باز شده است استفاده کرد.

در صورت موفقیت 1، در صورت شکست 0، و در صورت بروز خطا -1 بازمی‌گرداند. در صورت بروز خطا، افزونه می‌تواند به صورت اختیاری تابع () یا () را با SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری به کاربر ارائه دهد.

آرگومان‌های تابع به شرح زیر هستند:

pwd
اگر شناسه کاربری که دستور با آن اجرا می‌شود در پایگاه داده گذرواژه‌ها پیدا شده باشد، pwd آن کاربر را توصیف خواهد کرد، در غیر این صورت NULL خواهد بود.
user_env_out
بردار محیطی خاتمه‌یافته با NULL برای استفاده هنگام اجرای دستور. این همان رشته‌ای است که از طریق پارامتر user_env_out افزونه خط‌مشی به پیشخوان بازگردانده می‌شود. اگر تابع () نیاز به اصلاح محیط کاربر داشته باشد، باید اشاره‌گر ذخیره‌شده در user_env_out را به‌روز کند. کاربرد مورد انتظار، ادغام محتویات محیط PAM (در صورت وجود) با محتویات user_env_out است. پارامتر user_env_out تنها از نسخه 1.2 به بعد API در دسترس است. یک افزونه باید نسخه API مشخص‌شده توسط پیشخوان sudo را قبل از استفاده از user_env_out بررسی کند. عدم انجام این کار ممکن است منجر به کرش شود.
errstr
اگر تابع init_session() مقداری به جز 1 بازگرداند، افزونه می‌تواند پیامی حاوی شرح شکست یا خطا را در errstr ذخیره کند. سپس پیشخوان sudo این مقدار را به تمام افزونه‌های ممیزی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمانی که تابع close() افزونه فراخوانی شود معتبر باقی بماند.

پارامتر errstr تنها از نسخه 1.15 به بعد API در دسترس است. یک افزونه باید نسخه API مشخص‌شده توسط پیشخوان sudo را قبل از استفاده از errstr بررسی کند. عدم انجام این کار ممکن است منجر به کرش شود.

register_hooks
void (*register_hooks)(int version,
   int (*register_hook)(struct sudo_hook *hook));

تابع () توسط پیشخوان sudo برای ثبت هرگونه قلابی که افزونه نیاز دارد فراخوانی می‌شود. اگر افزونه از قلاب‌ها پشتیبانی نمی‌کند، register_hooks باید روی اشاره‌گر NULL تنظیم شود.

آرگومان version نسخه API قلاب‌های پشتیبانی‌شده توسط پیشخوان sudo را توصیف می‌کند.

تابع () باید برای ثبت هر قلاب پشتیبانی‌شده‌ای که افزونه به آن نیاز دارد استفاده شود. این تابع در صورت موفقیت 0، در صورتی که نوع قلاب پشتیبانی نشود 1، و در صورتی که نسخه اصلی در struct sudo_hook با نسخه اصلی API قلاب‌های پیشخوان مطابقت نداشته باشد -1 بازمی‌گرداند.

برای اطلاعات بیشتر درباره قلاب‌ها به بخش Hook function API در زیر مراجعه کنید.

تابع () تنها از نسخه 1.2 به بعد API در دسترس است. اگر پیشخوان sudo از نسخه 1.2 یا بالاتر API پشتیبانی نکند، register_hooks() فراخوانی نخواهد شد.

deregister_hooks
void (*deregister_hooks)(int version,
   int (*deregister_hook)(struct sudo_hook *hook));

تابع () توسط پیشخوان sudo برای لغو ثبت هر قلابی که توسط افزونه ثبت شده است فراخوانی می‌شود. اگر افزونه از قلاب‌ها پشتیبانی نمی‌کند، deregister_hooks باید روی اشاره‌گر NULL تنظیم شود.

آرگومان version نسخه API قلاب‌های پشتیبانی‌شده توسط پیشخوان sudo را توصیف می‌کند.

تابع () باید برای لغو ثبت هر قلابی که توسط تابع register_hook() به کار گرفته شده بود استفاده شود. اگر افزونه تلاش کند قلابی را لغو ثبت کند که پیشخوان از آن پشتیبانی نمی‌کند، deregister_hook() یک خطا بازمی‌گرداند.

برای اطلاعات بیشتر درباره قلاب‌ها به بخش Hook function API در زیر مراجعه کنید.

تابع () تنها از نسخه 1.2 به بعد API در دسترس است. اگر پیشخوان sudo از نسخه 1.2 یا بالاتر API پشتیبانی نکند، deregister_hooks() فراخوانی نخواهد شد.

event_alloc
struct sudo_plugin_event * (*event_alloc)(void);

تابع () برای تخصیص یک struct sudo_plugin_event استفاده می‌شود که دسترسی به حلقه رویدادهای اصلی sudo را فراهم می‌کند. برخلاف سایر فیلدها، اشاره‌گر event_alloc توسط پیشخوان sudo پر می‌شود، نه توسط افزونه.

برای اطلاعات بیشتر درباره رویدادها به بخش Event API در زیر مراجعه کنید.

تابع () تنها از نسخه 1.15 به بعد API در دسترس است. اگر پیشخوان sudo از نسخه 1.15 یا بالاتر API پشتیبانی نکند، event_alloc تنظیم نخواهد شد.

ماکروهای نسخه افزونه خط‌مشی (Policy Plugin Version Macros)

/* 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,\
                                            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 { \
    *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
} while(0)
#define SUDO_API_VERSION_SET_MINOR(vp, n) do { \
    *(vp) = (*(vp) & 0xffff0000) | (n); \
} while(0)

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);
};

هنگامی که یک افزونه ورودی/خروجی بارگذاری می‌شود، sudo دستور را در یک شبه‌ترمینال اجرا می‌کند. این امر ثبت ورودی و خروجی نشست کاربر را امکان‌پذیر می‌سازد. اگر هر یک از ورودی استاندارد، خروجی استاندارد یا خطای استاندارد به یک tty مربوط نباشد، sudo یک لوله (pipe) باز می‌کند تا ورودی/خروجی را پیش از ارسال، برای ثبت دریافت کند.

تابع () ورودی خام کاربر را از دستگاه ترمینال دریافت می‌کند (این شامل ورودی حتی در زمان غیرفعال بودن انعکاس (echo ،) مانند زمانی که یک گذرواژه خوانده می‌شود، نیز خواهد بود). تابع log_ttyout() خروجی را از شبه‌ترمینال دریافت می‌کند که برای بازپخش نشست کاربر در آینده مناسب است. توابع log_stdin(،) log_stdout() و log_stderr() تنها در صورتی فراخوانی می‌شوند که به ترتیب، ورودی استاندارد، خروجی استاندارد یا خطای استاندارد به چیزی غیر از یک tty مربوط باشند.

در صورتی که قرار نباشد هیچ ثبتی انجام شود، هر یک از توابع ثبت وقایع می‌توانند روی اشاره‌گر NULL تنظیم شوند. اگر تابع open مقدار 0 بازگرداند، هیچ ورودی/خروجی‌ای به افزونه ارسال نخواهد شد.

اگر یک تابع ثبت وقایع خطایی (-1) بازگرداند، دستور در حال اجرا پایان خواهد یافت و تمام توابع ثبت وقایع افزونه غیرفعال خواهند شد. سایر افزونه‌های ثبت وقایع ورودی/خروجی همچنان هرگونه ورودی یا خروجی باقی‌مانده‌ای را که هنوز پردازش نشده است دریافت خواهند کرد.

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

یک struct audit_plugin دارای فیلدهای زیر است:

type
فیلد type همیشه باید روی SUDO_IO_PLUGIN تنظیم شود.
version
فیلد version باید روی SUDO_API_VERSION تنظیم شود.

این به sudo امکان می‌دهد تا نسخه API که افزونه بر اساس آن ساخته شده است را تعیین کند.

open
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[]);

تابع () پیش از فراخوانی توابع log_ttyin(،) log_ttyout(،) log_stdin(،) log_stdout(،) log_stderr(،) log_suspend(،) change_winsize() یا show_version() اجرا می‌شود. این تابع تنها در صورتی فراخوانی می‌شود که نسخه درخواست شده باشد یا تابع check_policy() افزونه خط‌مشی با موفقیت بازگشته باشد. در صورت موفقیت مقدار 1، در صورت شکست 0، در صورت بروز خطای عمومی -1 و در صورت خطای نحوه استفاده -2 را برمی‌گرداند. در حالت اخیر، sudo پیش از خروج پیامی درباره نحوه استفاده چاپ خواهد کرد. اگر خطایی رخ دهد، افزونه می‌تواند به صورت اختیاری تابع conversation() یا sudo_plugin_printf() را با SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری به کاربر ارائه دهد.

آرگومان‌های تابع به شرح زیر هستند:

version
نسخه ارائه‌شده توسط sudo به افزونه امکان می‌دهد شماره نسخه اصلی و فرعی API افزونه پشتیبانی‌شده توسط sudo را تعیین کند.
conversation
اشاره‌گری به تابع () که ممکن است توسط تابع (show_version) جهت نمایش اطلاعات نسخه استفاده شود (به show_version() در زیر مراجعه کنید). تابع conversation() همچنین ممکن است برای نمایش پیام خطای اضافی به کاربر استفاده شود. تابع conversation() در صورت موفقیت مقدار 0 و در صورت شکست -1 بازمی‌گرداند.
sudo_plugin_printf
اشاره‌گری به یک تابع به سبک printf()-style که ممکن است توسط تابع show_version() جهت نمایش اطلاعات نسخه استفاده شود (به show_version در زیر مراجعه کنید). تابع sudo_plugin_printf() همچنین می‌تواند برای نمایش پیام خطای اضافی به کاربر استفاده شود. تابع sudo_plugin_printf() در صورت موفقیت تعداد نویسه‌های چاپ‌شده و در صورت شکست -1 بازمی‌گرداند.
settings
برداری از تنظیمات ارائه‌شده توسط کاربر برای sudo به شکل رشته‌های “name=value”. این بردار با اشاره‌گر NULL پایان می‌یابد. این تنظیمات مربوط به گزینه‌هایی هستند که کاربر هنگام اجرای sudo مشخص کرده است. بنابراین، آن‌ها تنها زمانی وجود خواهند داشت که گزینه متناظر در خط فرمان مشخص شده باشد.

هنگام تجزیه settings ، افزونه باید بر اساس اولین علامت مساوی (‘=’) تفکیک را انجام دهد، چرا که فیلد name هرگز خودش شامل علامت مساوی نخواهد بود، اما value ممکن است باشد.

برای فهرستی از تمامی تنظیمات ممکن، بخش Policy plugin API را ببینید.

user_info
برداری از اطلاعات مربوط به کاربری که دستور را اجرا می‌کند به شکل رشته‌های “name=value”. این بردار با اشاره‌گر NULL پایان می‌یابد.

هنگام تجزیه user_info ، افزونه باید بر اساس اولین علامت مساوی (‘=’) تفکیک را انجام دهد، چرا که فیلد name هرگز خودش شامل مساوی نخواهد بود، اما value ممکن است باشد.

برای فهرستی از تمامی رشته‌های ممکن، بخش Policy plugin API را ببینید.

command_info
برداری از اطلاعات توصیف‌کننده دستور در حال اجرا به شکل رشته‌های “name=value”. این بردار با اشاره‌گر NULL پایان می‌یابد.

هنگام تجزیه command_info ، افزونه باید بر اساس اولین علامت مساوی (‘=’) تفکیک را انجام دهد، چرا که فیلد name هرگز خودش شامل مساوی نخواهد بود، اما value ممکن است باشد.

برای فهرستی از تمامی رشته‌های ممکن، بخش Policy plugin API را ببینید.

argc
تعداد عناصر موجود در argv ، بدون احتساب اشاره‌گر پایانی NULL. این مقدار می‌تواند صفر باشد، مانند زمانی که sudo با گزینه -V فراخوانی می‌شود.
argv
در صورت غیر NULL بودن (non-NULL) ، یک بردار آرگومان است که دستوری را که کاربر مایل به اجرای آن است توصیف می‌کند، به همان شکلی که به فراخوانی سیستمی execve(2) ارسال می‌گردد.
user_env
محیط کاربر به شکل یک بردار پایان‌یافته با NULL از رشته‌های “name=value”.

هنگام تجزیه user_env ، افزونه باید بر اساس اولین علامت مساوی (‘=’) تفکیک را انجام دهد، چرا که فیلد name هرگز خودش شامل مساوی نخواهد بود، اما value ممکن است باشد.

plugin_options
هر رشته‌ای (غیر از کامنت) بلافاصله پس از مسیر افزونه، به عنوان آرگومان‌های افزونه تلقی می‌شود. این آرگومان‌ها در مرزهای فاصله خالی تفکیک شده و در قالب یک آرایه از رشته‌ها که با NULL خاتمه می‌یابد به افزونه ارسال می‌شوند. اگر هیچ آرگومانی مشخص نشده باشد، plugin_options اشاره‌گر NULL خواهد بود.

پارامتر plugin_options تنها با شروع از نسخه 1.2 از API در دسترس است. یک افزونه باید پیش از استفاده از plugin_options ، نسخه API ارائه‌شده توسط بخش فرانت‌اند sudo را بررسی کند. عدم انجام این کار ممکن است منجر به از کار افتادن برنامه شود.

errstr
اگر تابع () مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در errstr ذخیره کند. سپس فرانت‌اند sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمان فراخوانی تابع close() افزونه معتبر بماند.

پارامتر errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه باید پیش از استفاده از errstr ، نسخه API مشخص‌شده توسط بخش فرانت‌اند sudo را بررسی کند. عدم انجام این کار ممکن است منجر به از کار افتادن برنامه شود.

close
void (*close)(int exit_status, int error);

تابع () زمانی که کار sudo پایان یابد، اندکی پیش از خروج فراخوانی می‌شود.

آرگومان‌های تابع به شرح زیر هستند:

exit_status
وضعیت خروج دستور، همان‌طور که توسط فراخوانی سیستمی wait(2) بازگردانده شده است، یا در صورتی که هیچ دستوری اجرا نشده باشد صفر است. اگر error غیر صفر باشد، مقدار exit_status تعریف‌نشده است.
error
اگر دستور نتواند اجرا شود، این مقدار روی مقدار errno تنظیم‌شده توسط فراخوانی سیستمی execve(2) تنظیم می‌شود. اگر دستور با موفقیت اجرا شده باشد، مقدار error صفر است.
show_version
int (*show_version)(int verbose);

تابع () زمانی توسط sudo فراخوانی می‌شود که کاربر گزینه -V را مشخص کرده باشد. افزونه می‌تواند اطلاعات نسخه خود را از طریق تابع conversation() یا sudo_plugin_printf() با استفاده از SUDO_CONV_INFO_MSG به کاربر نمایش دهد. اگر کاربر اطلاعات دقیق نسخه را درخواست کند، پرچم verbose غیر صفر خواهد بود.

در صورت موفقیت 1، در صورت شکست 0، در صورت بروز خطای عمومی -1، یا اگر خطای نحوه استفاده وجود داشته باشد -2 بازمی‌گرداند، هرچند مقدار بازگشتی در حال حاضر نادیده گرفته می‌شود.

log_ttyin
int (*log_ttyin)(const char *buf, unsigned int len,
    const char **errstr);

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

آرگومان‌های تابع به شرح زیر هستند:

buf
بافر حاوی ورودی کاربر.
len
طول buf به بایت.
errstr
اگر تابع () مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در errstr ذخیره کند. سپس بخش فرانت‌اند sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمان فراخوانی تابع close() افزونه معتبر بماند.

پارامتر errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه باید پیش از استفاده از errstr ، نسخه API ارائه‌شده توسط بخش فرانت‌اند sudo را بررسی کند. عدم انجام این کار ممکن است منجر به از کار افتادن برنامه شود.

log_ttyout
int (*log_ttyout)(const char *buf, unsigned int len,
    const char **errstr);

تابع () هر زمان که داده‌ای از دستور قابل خواندن باشد، اما پیش از نوشته شدن در ترمینال کاربر، فراخوانی می‌شود. این به افزونه اجازه می‌دهد تا در صورت تمایل داده را رد کند (مثلاً اگر خروجی شامل محتوای ممنوعه باشد). اگر داده باید به کاربر تحویل داده شود مقدار 1، اگر داده رد شود مقدار 0 (که دستور در حال اجرا را متوقف می‌کند)، یا در صورت بروز خطا مقدار -1 بازمی‌گرداند.

آرگومان‌های تابع به شرح زیر هستند:

buf
بافر حاوی خروجی دستور.
len
طول buf به بایت.
errstr
اگر تابع () مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در errstr ذخیره کند. سپس بخش فرانت‌اند sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمان فراخوانی تابع close() افزونه معتبر بماند.

پارامتر errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه باید پیش از استفاده از errstr ، نسخه API ارائه‌شده توسط فرانت‌اند sudo را بررسی کند. عدم انجام این کار ممکن است منجر به خرابی برنامه شود.

log_stdin
int (*log_stdin)(const char *buf, unsigned int len,
    const char **errstr);

تابع () تنها در صورتی استفاده می‌شود که ورودی استاندارد مربوط به یک دستگاه tty نباشد. این تابع هر زمان که داده‌ای از ورودی استاندارد قابل خواندن باشد، اما پیش از انتقال آن به دستور در حال اجرا فراخوانی می‌شود. این به افزونه امکان می‌دهد در صورت تمایل داده را رد کند (مثلاً اگر ورودی شامل محتوای ممنوعه باشد). اگر داده باید به دستور ارسال شود مقدار 1، اگر داده رد شود مقدار 0 (که دستور در حال اجرا را متوقف می‌کند)، یا در صورت بروز خطا مقدار -1 بازمی‌گرداند.

آرگومان‌های تابع به شرح زیر است:

buf
بافر حاوی ورودی کاربر.
len
طول buf به بایت.
errstr
اگر تابع () مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در errstr ذخیره کند. سپس بخش فرانت‌اند sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمان فراخوانی تابع close() افزونه معتبر بماند.

پارامتر errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه باید پیش از استفاده از errstr ، نسخه API ارائه‌شده توسط فرانت‌اند sudo را بررسی کند. عدم انجام این کار ممکن است منجر به خرابی برنامه شود.

log_stdout
int (*log_stdout)(const char *buf, unsigned int len,
    const char **errstr);

تابع () تنها در صورتی استفاده می‌شود که خروجی استاندارد به یک دستگاه tty مربوط نباشد. این تابع هر زمان که داده‌ای از دستور قابل خواندن باشد، اما پیش از نوشته شدن در خروجی استاندارد، فراخوانی می‌شود. این به افزونه امکان می‌دهد تا در صورت تمایل داده را رد کند (مثلاً اگر خروجی شامل محتوای ممنوعه باشد). اگر داده باید به کاربر تحویل شود مقدار 1، اگر داده رد شود مقدار 0 (که دستور در حال اجرا را خاتمه می‌دهد)، یا در صورت بروز خطا مقدار -1 بازمی‌گرداند.

آرگومان‌های تابع به شرح زیر است:

buf
بافر حاوی خروجی دستور.
len
طول buf به بایت.
errstr
اگر تابع () مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در errstr ذخیره کند. سپس بخش فرانت‌اند sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمان فراخوانی تابع close() افزونه معتبر بماند.

پارامتر errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه باید پیش از استفاده از errstr ، نسخه API ارائه‌شده توسط فرانت‌اند sudo را بررسی کند. عدم انجام این کار ممکن است منجر به خرابی برنامه شود.

log_stderr
int (*log_stderr)(const char *buf, unsigned int len,
    const char **errstr);

تابع () تنها در صورتی استفاده می‌شود که خطای استاندارد به یک دستگاه tty مربوط نباشد. این تابع هر زمان که داده‌ای از دستور قابل خواندن باشد، اما پیش از نوشته شدن در خطای استاندارد، فراخوانی می‌شود. این به افزونه امکان می‌دهد تا در صورت تمایل داده را رد کند (مثلاً اگر خروجی شامل محتوای ممنوعه باشد). اگر داده باید به کاربر تحویل شود مقدار 1، اگر داده رد شود مقدار 0 (که دستور در حال اجرا را متوقف می‌کند)، یا در صورت بروز خطا مقدار -1 بازمی‌گرداند.

آرگومان‌های تابع به شرح زیر است:

buf
بافر حاوی خروجی دستور.
len
طول buf به بایت.
errstr
اگر تابع () مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در errstr ذخیره کند. سپس بخش فرانت‌اند sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمان فراخوانی تابع close() افزونه معتبر بماند.

پارامتر errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه باید پیش از استفاده از errstr ، نسخه API ارائه‌شده توسط فرانت‌اند sudo را بررسی کند. عدم انجام این کار ممکن است منجر به خرابی برنامه شود.

register_hooks
برای شرح () به بخش Policy plugin API مراجعه کنید.
deregister_hooks
برای شرح deregister_hooks() به بخش Policy plugin API مراجعه کنید.
change_winsize
int (*change_winsize)(unsigned int lines, unsigned int cols,
    const char **errstr);

تابع () هر زمان که اندازه پنجره ترمینال از مقادیر اولیه مشخص‌شده در فهرست user_info تغییر کند، فراخوانی می‌شود. در صورت بروز خطا -1 بازمی‌گرداند که در این حالت تماس دیگری با change_winsize() برقرار نخواهد شد،

آرگومان‌های تابع به شرح زیر هستند:

lines
تعداد خطوط (سطرها) در ترمینال تغییراندازه‌یافته.
cols
تعداد ستون‌ها در ترمینال تغییراندازه‌یافته.
errstr
اگر تابع () مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در errstr ذخیره کند. سپس بخش فرانت‌اند sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمان فراخوانی تابع close() افزونه معتبر بماند.

پارامتر errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه باید پیش از استفاده از errstr ، نسخه API ارائه‌شده توسط فرانت‌اند sudo را بررسی کند. عدم انجام این کار ممکن است منجر به خرابی برنامه شود.

log_suspend
int (*log_suspend)(int signo, const char **errstr);

تابع () هر زمان که دستوری معلق شده یا ازسرگرفته شود فراخوانی می‌شود. ثبت این اطلاعات، صرف‌نظر کردن از بازه زمانی تعلیق بودن دستور در زمان بازپخش یک نشست را امکان‌پذیر می‌سازد. در صورت بروز خطا -1 بازمی‌گرداند که در این حالت تماس دیگری با log_suspend() برقرار نخواهد شد،

آرگومان‌های تابع به شرح زیر هستند:

signo
سیگنالی که باعث معلق شدن دستور شده است، یا SIGCONT در صورتی که اجرای دستور ازسرگرفته شده باشد.
errstr
اگر تابع () مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا در errstr ذخیره کند. سپس بخش فرانت‌اند sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمان فراخوانی تابع close() افزونه معتبر بماند.

پارامتر errstr تنها با شروع از نسخه 1.15 از API در دسترس است. یک افزونه باید پیش از استفاده از errstr ، نسخه API ارائه‌شده توسط فرانت‌اند sudo را بررسی کند. عدم انجام این کار ممکن است منجر به خرابی برنامه شود.

event_alloc
struct sudo_plugin_event * (*event_alloc)(void);

تابع () برای تخصیص دادن یک struct sudo_plugin_event استفاده می‌شود که دسترسی به حلقه رویداد اصلی sudo را فراهم می‌کند. برخلاف سایر فیلدها، اشاره‌گر event_alloc() توسط بخش فرانت‌اند sudo پر می‌شود، نه توسط افزونه.

برای اطلاعات بیشتر درباره رویدادها، بخش Event API در زیر را ببینید.

تابع () تنها با شروع از نسخه 1.15 از API در دسترس است. اگر فرانت‌اند sudo از نسخه 1.15 یا بالاتر API پشتیبانی نکند، event_alloc() تنظیم نخواهد شد.

ماکروهای نسخه افزونه ورودی/خروجی (I/O Plugin Version Macros)

مشابه موارد بخش Policy plugin API.

/* 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);
}

یک افزونه حسابرسی می‌تواند برای ثبت تلاش‌های موفق و ناموفق جهت اجرای sudo مستقل از خط‌مشی یا هر یک از افزونه‌های I/O استفاده شود. می‌توان چندین افزونه حسابرسی را در sudo.conf(5) مشخص کرد.

یک struct audit_plugin دارای فیلدهای زیر است:

type
فیلد type باید همیشه روی SUDO_AUDIT_PLUGIN تنظیم شود.
version
فیلد version باید روی SUDO_API_VERSION تنظیم شود.

این به sudo امکان می‌دهد تا نسخه API که افزونه بر اساس آن ساخته شده است را تعیین کند.

open
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);

تابع () حسابرسی، پیش از هر تابع API افزونه دیگر sudo اجرا می‌شود. این کار امکان حسابرسی خرابی‌ها در سایر افزونه‌ها را ممکن می‌سازد. این تابع در صورت موفقیت مقدار 1، در صورت شکست 0، در صورت بروز یک خطای عمومی -1، یا در صورت بروز خطای نحوه استفاده مقدار -2 را برمی‌گرداند. در حالت اخیر، sudo پیش از خروج پیامی درباره نحوه استفاده چاپ خواهد کرد. در صورت بروز خطا، افزونه می‌تواند به صورت اختیاری تابع conversation() یا plugin_printf() را با SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای اضافی را به کاربر نمایش دهد.

آرگومان‌های تابع به شرح زیر هستند:

version
نسخه ارسال‌شده توسط sudo به افزونه امکان می‌دهد تا شماره نسخه اصلی و فرعی API افزونه پشتیبانی‌شده توسط sudo را تعیین کند.
conversation
اشاره‌گری به تابع () که ممکن است توسط تابع show_version() برای نمایش اطلاعات نسخه استفاده شود (به show_version() در زیر مراجعه کنید). همچنین تابع conversation() می‌تواند برای نمایش پیام خطای اضافی به کاربر استفاده شود. تابع conversation() در صورت موفقیت مقدار 0 و در صورت شکست مقدار -1 را برمی‌گرداند.
plugin_printf
اشاره‌گری به تابعی به سبک printf() که ممکن است توسط تابع show_version() برای نمایش اطلاعات نسخه استفاده شود (به show_version() در زیر مراجعه کنید). همچنین تابع plugin_printf() می‌تواند برای نمایش پیام خطای اضافی به کاربر استفاده شود. تابع plugin_printf() در صورت موفقیت تعداد کاراکترهای چاپ‌شده و در صورت شکست مقدار -1 را برمی‌گرداند.
settings
برداری از تنظیمات ارائه‌شده توسط کاربر برای sudo در قالب رشته‌های “name=value”. این بردار با یک اشاره‌گر NULL خاتمه می‌یابد. این تنظیمات متناظر با گزینه‌هایی هستند که کاربر هنگام اجرای sudo مشخص کرده است. به این ترتیب، آن‌ها تنها زمانی وجود خواهند داشت که گزینه متناظر در خط فرمان مشخص شده باشد.

هنگام تجزیه کردن settings، افزونه باید آن را بر اساس اولین علامت مساوی (‘=’) تفکیک کند، زیرا خود فیلد name هرگز شامل مساوی نخواهد بود، اما value ممکن است شامل آن باشد.

برای فهرستی از تمام تنظیمات ممکن، به بخش Policy plugin API مراجعه کنید.

user_info
برداری از اطلاعات درباره کاربر اجراکننده دستور در قالب رشته‌های “name=value”. این بردار با یک اشاره‌گر NULL خاتمه می‌یابد.

هنگام تجزیه کردن user_info، افزونه باید آن را بر اساس اولین علامت مساوی (‘=’) تفکیک کند، زیرا خود فیلد name هرگز شامل مساوی نخواهد بود، اما value ممکن است شامل آن باشد.

برای فهرستی از تمام رشته‌های ممکن، به بخش Policy plugin API مراجعه کنید.

submit_optind
اندیس درون submit_argv که متناظر با اولین ورودی است که یک گزینه خط فرمان نیست. اگر submit_argv تنها شامل گزینه‌ها باشد، که ممکن است در مورد گزینه‌های -l یا -v رخ دهد، submit_argv[submit_optind] به اشاره‌گر NULL ارزیابی می‌شود.
submit_argv
بردار آرگومانی که sudo با آن فراخوانی شده بود، شامل تمام گزینه‌های خط فرمان. از آرگومان submit_optind می‌توان برای تعیین انتهای گزینه‌های خط فرمان استفاده کرد.
submit_envp
محیط کاربر فراخواننده در قالب برداری از رشته‌های “name=value” که با NULL خاتمه می‌یابد.

هنگام تجزیه کردن submit_envp، افزونه باید آن را بر اساس اولین علامت مساوی (‘=’) تفکیک کند، زیرا خود فیلد name هرگز شامل مساوی نخواهد بود، اما value ممکن است شامل آن باشد.

plugin_options
هر رشته (غیر از کامنت) که بلافاصله پس از مسیر افزونه قرار گیرد به عنوان آرگومان‌های افزونه در نظر گرفته می‌شود. این آرگومان‌ها بر اساس مرز فاصله‌های خالی تفکیک شده و در قالب آرایه‌ای از رشته‌ها با خاتمه‌دهنده NULL به افزونه ارسال می‌شوند. اگر هیچ آرگومانی مشخص نشده باشد، plugin_options برابر با اشاره‌گر NULL خواهد بود.
errstr
اگر تابع () مقداری غیر از 1 برگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا را در errstr ذخیره کند. سپس بخش فرانت‌اند sudo این مقدار را به تمام افزونه‌های حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمانی که تابع close() افزونه فراخوانی شود، معتبر باقی بماند.
close
void (*close)(int status_type, int status);

تابع () زمانی که کار sudo تمام می‌شود، اندکی پیش از خروج آن فراخوانی می‌گردد.

آرگومان‌های تابع به شرح زیر هستند:

status_type
نوع وضعیتی که ارسال می‌شود. یکی از مقادیر SUDO_PLUGIN_NO_STATUS ، SUDO_PLUGIN_WAIT_STATUS ، SUDO_PLUGIN_EXEC_ERROR یا SUDO_PLUGIN_SUDO_ERROR.
status
بسته به مقدار status_type ، این مقدار یا نادیده گرفته می‌شود، یا وضعیت خروج دستور برگشتی توسط فراخوانی سیستمی wait(2) ، یا مقدار errno تنظیم‌شده توسط فراخوانی سیستمی execve(2) ، یا مقدار errno ناشی از بروز خطا در فرانت‌اند sudo است.
accept
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);

تابع () زمانی فراخوانی می‌شود که یک دستور یا کنش توسط یک افزونه خط‌مشی یا تأیید پذیرفته شود. آرگومان‌های تابع به شرح زیر هستند:

plugin_name
نام افزونه‌ای که دستور را پذیرفته است یا “sudo” برای فرانت‌اند sudo.
plugin_type
نوع افزونه‌ای که دستور را پذیرفته است، که در حال حاضر یکی از مقادیر SUDO_POLICY_PLUGIN ، SUDO_POLICY_APPROVAL یا SUDO_FRONT_END است. تابع accept() چندین بار فراخوانی می‌شود – یک بار به ازای هر افزونه خط‌مشی یا تأیید که موفق شود و یک بار برای فرانت‌اند sudo. هنگامی که به نمایندگی از فرانت‌اند sudo فراخوانی شود، command_info ممکن است شامل اطلاعاتی از یک افزونه ثبت وقایع I/O نیز باشد.

معمولاً یک افزونه حسابرسی یا علاقه‌مند به وضعیت پذیرش از سوی فرانت‌اند sudo است یا از سوی افزونه‌های مختلف خط‌مشی و تأیید، اما نه هر دوی آن‌ها. این امکان وجود دارد که افزونه خط‌مشی دستوری را بپذیرد که بعداً توسط یک افزونه تأیید رد شود، که در این صورت هر دو تابع () و reject() افزونه حسابرسی فراخوانی خواهند شد.

command_info
برداری اختیاری از اطلاعات توصیف‌کننده دستور در حال اجرا در قالب رشته‌های “name=value”. این بردار با یک اشاره‌گر NULL خاتمه می‌یابد.

هنگام تجزیه کردن command_info، افزونه باید آن را بر اساس اولین علامت مساوی (‘=’) تفکیک کند، زیرا خود فیلد name هرگز شامل مساوی نخواهد بود، اما value ممکن است شامل آن باشد.

برای فهرستی از تمام رشته‌های ممکن، به بخش Policy plugin API مراجعه کنید.

run_argv
یک بردار آرگومان خاتمه‌یافته با NULL که دستوری را توصیف می‌کند که قرار است اجرا شود، در همان قالبی که به فراخوانی سیستمی execve(2) ارسال می‌گردد.
run_envp
محیطی که دستور با آن اجرا خواهد شد در قالب برداری از رشته‌های “name=value” که با NULL خاتمه می‌یابد.

هنگام تجزیه کردن run_envp، افزونه باید آن را بر اساس اولین علامت مساوی (‘=’) تفکیک کند، زیرا خود فیلد name هرگز شامل مساوی نخواهد بود، اما value ممکن است شامل آن باشد.

errstr
اگر تابع () مقداری غیر از 1 برگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا را در errstr ذخیره کند. سپس بخش فرانت‌اند sudo این مقدار را به تمام افزونه‌های حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمانی که تابع close() افزونه فراخوانی شود، معتبر باقی بماند.
reject
int (*reject)(const char *plugin_name, unsigned int plugin_type,
    const char *audit_msg, char * const command_info[],
    const char **errstr);

تابع () زمانی فراخوانی می‌شود که یک دستور یا کنش توسط یک افزونه رد شود. آرگومان‌های تابع به شرح زیر هستند:

plugin_name
نام افزونه‌ای که دستور را رد کرده است.
plugin_type
نوع افزونه‌ای که دستور را رد کرده است، که در حال حاضر یکی از مقادیر SUDO_POLICY_PLUGIN ، SUDO_APPROVAL_PLUGIN یا SUDO_IO_PLUGIN است.

برخلاف تابع ()، تابع reject() به نمایندگی از فرانت‌اند sudo فراخوانی نمی‌شود.

audit_msg
رشته‌ای اختیاری در توصیف دلیل رد شدن دستور توسط افزونه. اگر افزونه دلیلی ارائه نداده باشد، audit_msg برابر با اشاره‌گر NULL خواهد بود.
command_info
برداری اختیاری از اطلاعات توصیف‌کننده دستور در حال اجرا در قالب رشته‌های “name=value”. این بردار با یک اشاره‌گر NULL خاتمه می‌یابد.

هنگام تجزیه کردن command_info، افزونه باید آن را بر اساس اولین علامت مساوی (‘=’) تفکیک کند، زیرا خود فیلد name هرگز شامل مساوی نخواهد بود، اما value ممکن است شامل آن باشد.

برای فهرستی از تمام رشته‌های ممکن، به بخش Policy plugin API مراجعه کنید.

errstr
اگر تابع () مقداری غیر از 1 برگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا را در errstr ذخیره کند. سپس بخش فرانت‌اند sudo این مقدار را به تمام افزونه‌های حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمانی که تابع close() افزونه فراخوانی شود، معتبر باقی بماند.
error
int (*error)(const char *plugin_name, unsigned int plugin_type,
    const char *audit_msg, char * const command_info[],
    const char **errstr);

تابع () زمانی فراخوانی می‌شود که یک افزونه یا فرانت‌اند sudo خطایی را برگرداند. آرگومان‌های تابع به شرح زیر هستند:

plugin_name
نام افزونه‌ای که خطا را ایجاد کرده است یا “sudo” برای فرانت‌اند sudo.
plugin_type
نوع افزونه‌ای که خطا را ایجاد کرده است، یا SUDO_FRONT_END برای فرانت‌اند sudo.
audit_msg
رشته‌ای اختیاری در توصیف خطای افزونه. اگر افزونه توضیحی ارائه نداده باشد، audit_msg برابر با اشاره‌گر NULL خواهد بود.
command_info
برداری اختیاری از اطلاعات توصیف‌کننده دستور در حال اجرا در قالب رشته‌های “name=value”. این بردار با یک اشاره‌گر NULL خاتمه می‌یابد.

هنگام تجزیه کردن command_info، افزونه باید آن را بر اساس اولین علامت مساوی (‘=’) تفکیک کند، زیرا خود فیلد name هرگز شامل مساوی نخواهد بود، اما value ممکن است شامل آن باشد.

برای فهرستی از تمام رشته‌های ممکن، به بخش Policy plugin API مراجعه کنید.

errstr
اگر تابع () مقداری غیر از 1 برگرداند، افزونه می‌تواند پیامی در توصیف شکست یا خطا را در errstr ذخیره کند. سپس بخش فرانت‌اند sudo این مقدار را به تمام افزونه‌های حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمانی که تابع close() افزونه فراخوانی شود، معتبر باقی بماند.
show_version
int (*show_version)(int verbose);

تابع () توسط sudo زمانی فراخوانی می‌شود که کاربر گزینه -V را مشخص کند. افزونه می‌تواند اطلاعات نسخه خود را از طریق تابع conversation() یا plugin_printf() با استفاده از SUDO_CONV_INFO_MSG به کاربر نمایش دهد. اگر کاربر اطلاعات نسخه همراه با جزئیات را درخواست کند، فلگ verbose تنظیم خواهد شد.

در صورت موفقیت مقدار 1، در صورت شکست 0، در صورت بروز یک خطای عمومی -1، یا در صورت بروز خطای نحوه استفاده مقدار -2 را برمی‌گرداند، اگرچه مقدار بازگشتی در حال حاضر نادیده گرفته می‌شود.

register_hooks
برای توضیحات مربوط به () به بخش Policy plugin API مراجعه کنید.
deregister_hooks
برای توضیحات مربوط به deregister_hooks() به بخش Policy plugin API مراجعه کنید.
event_alloc
struct sudo_plugin_event * (*event_alloc)(void);

تابع () برای تخصیص یک struct sudo_plugin_event استفاده می‌شود که امکان دسترسی به حلقه رویداد اصلی sudo را فراهم می‌کند. برخلاف سایر فیلدها، اشاره‌گر event_alloc توسط فرانت‌اند sudo پر می‌شود، نه توسط افزونه.

برای کسب اطلاعات بیشتر درباره رویدادها، به بخش Event API در زیر مراجعه کنید.

تابع () تنها از نسخه API 1.17 به بعد در دسترس است. اگر فرانت‌اند sudo از نسخه API 1.17 یا بالاتر پشتیبانی نکند، event_alloc() تنظیم نخواهد شد.

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);
};

یک افزونه تأیید می‌تواند برای اعمال محدودیت‌های اضافی پس از پذیرفته شدن دستور توسط افزونه خط‌مشی به کار رود. برخلاف سایر انواع افزونه‌ها، این افزونه تا زمان تکمیل دستور باز نمی‌ماند. افزونه پیش از فراخوانی () یا show_version() باز می‌شود و اندکی پس از آن بسته می‌شود (توابع افزونه حسابرسی باید پیش از بسته شدن افزونه فراخوانی شوند). می‌توان چندین افزونه تأیید را در sudo.conf(5) مشخص کرد.

ساختار struct approval_plugin دارای فیلدهای زیر است:

type
فیلد type باید همیشه روی SUDO_APPROVAL_PLUGIN تنظیم شود.
version
فیلد version باید روی SUDO_API_VERSION تنظیم شود.

این به sudo امکان می‌دهد نسخه API که افزونه بر اساس آن ساخته شده است را تشخیص دهد.

open
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);

تابع () تأیید بلافاصله پیش از فراخوانی توابع check() یا show_version() افزونه اجرا می‌شود. این تابع تنها در صورتی فراخوانی می‌شود که نسخه درخواست شده باشد یا اینکه تابع check_policy() افزونه خط‌مشی با موفقیت بازگشته باشد. این تابع در صورت موفقیت مقدار 1، در صورت شکست 0، در صورت بروز خطای عمومی مقدار -1 یا در صورت خطای نحوه استفاده مقدار -2 را بازمی‌گرداند. در حالت آخر، sudo پیش از خروج یک پیام نحوه استفاده را چاپ خواهد کرد. اگر خطایی رخ دهد، افزونه می‌تواند به صورت اختیاری تابع conversation() یا plugin_printf() را با SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری را به کاربر نمایش دهد.

آرگومان‌های تابع به شرح زیر هستند:

version
نسخه ارسال‌شده توسط sudo به افزونه امکان می‌دهد شماره نسخه اصلی (major) و فرعی (minor) رابط API افزونه را که توسط sudo پشتیبانی می‌شود، تشخیص دهد.
conversation
اشاره‌گری به تابع () که می‌تواند توسط افزونه برای تعامل با کاربر استفاده شود (برای جزئیات به Conversation API مراجعه کنید). در صورت موفقیت 0 و در صورت شکست -1 را بازمی‌گرداند.
plugin_printf
اشاره‌گری به یک تابع به سبک printf() که می‌تواند برای نمایش پیام‌های اطلاعاتی یا خطا استفاده شود (برای جزئیات به Conversation API مراجعه کنید). در صورت موفقیت تعداد نویسه‌های چاپ‌شده و در صورت شکست -1 را بازمی‌گرداند.
settings
برداری از تنظیمات ارائه‌شده توسط کاربر برای sudo به شکل رشته‌های “name=value”. این بردار با یک اشاره‌گر NULL خاتمه می‌یابد. این تنظیمات با گزینه‌هایی مطابقت دارند که کاربر هنگام اجرای sudo مشخص کرده است. به این ترتیب، آن‌ها تنها زمانی وجود خواهند داشت که گزینه متناظر در خط فرمان مشخص شده باشد.

هنگام تجزیه settings ، افزونه باید رشته را بر اساس اولین علامت مساوی (‘=’) جدا کند، زیرا خود فیلد name هرگز شامل علامت مساوی نخواهد بود اما value ممکن است باشد.

برای فهرستی از تمام تنظیمات ممکن به بخش Policy plugin API مراجعه کنید.

user_info
برداری از اطلاعات مربوط به کاربری که دستور را اجرا می‌کند به شکل رشته‌های “name=value”. این بردار با یک اشاره‌گر NULL خاتمه می‌یابد.

هنگام تجزیه user_info ، افزونه باید رشته را بر اساس اولین علامت مساوی (‘=’) جدا کند، زیرا خود فیلد name هرگز شامل علامت مساوی نخواهد بود اما value ممکن است باشد.

برای فهرستی از تمام رشته‌های ممکن به بخش Policy plugin API مراجعه کنید.

submit_optind
اندیس در submit_argv که به اولین مدخلی مربوط می‌شود که یک گزینه خط فرمان نیست. اگر submit_argv فقط شامل گزینه‌ها باشد، که ممکن است در مورد گزینه‌های -l یا -v صادق باشد، submit_argv[submit_optind] به اشاره‌گر NULL ارزیابی می‌شود.
submit_argv
بردار آرگومانی که sudo با آن فراخوانی شده است، شامل تمامی گزینه‌های خط فرمان. آرگومان submit_optind می‌تواند برای تعیین پایان گزینه‌های خط فرمان استفاده شود.
submit_envp
محیط کاربری فراخواننده به صورت یک بردار خاتمه‌یافته با NULL از رشته‌های “name=value”.

هنگام تجزیه submit_envp ، افزونه باید رشته را بر اساس اولین علامت مساوی (‘=’) جدا کند، زیرا خود فیلد name هرگز شامل علامت مساوی نخواهد بود اما value ممکن است باشد.

plugin_options
هر رشته (غیر کامنت) بلافاصله پس از مسیر افزونه به عنوان آرگومان‌های افزونه در نظر گرفته می‌شود. این آرگومان‌ها در مرزهای فاصله خالی (whitespace) جدا شده و در قالب یک آرایه از رشته‌های خاتمه‌یافته با NULL به افزونه ارسال می‌شوند. اگر هیچ آرگومانی مشخص نشده باشد، plugin_options اشاره‌گر NULL خواهد بود.
errstr
اگر تابع () مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی را در توصیف شکست یا خطا در errstr ذخیره کند. سپس بخش جلویی (front-end) sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمان فراخوانی تابع close() افزونه معتبر باقی بماند.
close
void (*close)(void);

تابع () پس از فراخوانی توابع check() یا show_version() افزونه تأیید، فراخوانی می‌شود. این تابع هیچ آرگومانی دریافت نمی‌کند. تابع close() معمولاً برای پاک‌سازی‌های خاص افزونه، مانند آزادسازی اشیاء حافظه تخصیص‌یافته توسط افزونه، استفاده می‌شود. اگر افزونه نیازی به پاک‌سازی نداشته باشد، close() می‌تواند روی اشاره‌گر NULL تنظیم شود.

check
int (*check)(char * const command_info[], char * const run_argv[],
    char * const run_envp[], const char **errstr);

تابع () تأیید پس از تابع check_policy() افزونه خط‌مشی و پیش از هر افزونه ثبت وقایع I/O اجرا می‌شود. اگر چندین افزونه تأیید بارگذاری شده باشند، همه آن‌ها باید موفقیت‌آمیز باشند تا اجرای دستور مجاز شود. این تابع در صورت موفقیت مقدار 1، در صورت شکست 0، در صورت بروز خطای عمومی مقدار -1 یا در صورت خطای نحوه استفاده مقدار -2 را بازمی‌گرداند. در حالت آخر، sudo پیش از خروج یک پیام نحوه استفاده را چاپ خواهد کرد. اگر خطایی رخ دهد، افزونه می‌تواند به صورت اختیاری تابع conversation() یا plugin_printf() را با SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری را به کاربر ارائه دهد.

آرگومان‌های تابع به شرح زیر هستند:

command_info
برداری از اطلاعات توصیف‌کننده دستور در حال اجرا به شکل رشته‌های “name=value”. این بردار با یک اشاره‌گر NULL خاتمه می‌یابد.

هنگام تجزیه command_info ، افزونه باید رشته را بر اساس اولین علامت مساوی (‘=’) جدا کند، زیرا خود فیلد name هرگز شامل علامت مساوی نخواهد بود اما value ممکن است باشد.

برای فهرستی از تمام رشته‌های ممکن به بخش Policy plugin API مراجعه کنید.

run_argv
یک بردار آرگومان خاتمه‌یافته با NULL که دستوری را توصیف می‌کند که اجرا خواهد شد، به همان شکلی که به فراخوانی سیستمی execve(2) ارسال می‌شود.
run_envp
محیطی که دستور با آن اجرا خواهد شد به شکل یک بردار خاتمه‌یافته با NULL از رشته‌های “name=value”.

هنگام تجزیه run_envp ، افزونه باید رشته را بر اساس اولین علامت مساوی (‘=’) جدا کند، زیرا خود فیلد name هرگز شامل علامت مساوی نخواهد بود اما value ممکن است باشد.

errstr
اگر تابع () مقداری غیر از 1 بازگرداند، افزونه می‌تواند پیامی را در توصیف شکست یا خطا در errstr ذخیره کند. سپس بخش جلویی sudo این مقدار را به هر افزونه حسابرسی ثبت‌شده ارسال خواهد کرد. رشته ذخیره‌شده در errstr باید تا زمان فراخوانی تابع close() افزونه معتبر باقی بماند.
show_version
int (*show_version)(int verbose);

تابع () توسط sudo هنگامی که کاربر گزینه -V را مشخص کند فراخوانی می‌شود. افزونه می‌تواند اطلاعات نسخه خود را از طریق تابع conversation() یا plugin_printf() با استفاده از SUDO_CONV_INFO_MSG به کاربر نمایش دهد. اگر کاربر اطلاعات تفصیلی نسخه را درخواست کند، فلگ verbose تنظیم خواهد شد.

در صورت موفقیت مقدار 1، در صورت شکست 0، در صورت بروز خطای عمومی مقدار -1 یا در صورت خطای نحوه استفاده مقدار -2 را بازمی‌گرداند، اگرچه مقدار بازگشتی در حال حاضر نادیده گرفته می‌شود.

بخش جلویی (front-end) sudo کنترل‌کننده‌های سیگنال پیش‌فرض را برای به دام انداختن سیگنال‌های متداول در حین اجرای توابع افزونه نصب می‌کند. سیگنال‌های زیر پیش از اجرای دستور به طور پیش‌فرض به دام انداخته می‌شوند:

اگر پیش از اجرای دستور یک سیگنال کشنده (fatal signal) دریافت شود، sudo تابع () افزونه را با وضعیت خروج 128 به اضافه مقدار سیگنال دریافت‌شده فراخوانی می‌کند. این امر برای افزونه‌هایی که چنین اطلاعاتی را در تابع close() خود ثبت می‌کنند، امکان ثبت یکدست وقایع دستوراتی که با سیگنال خاتمه یافته‌اند را فراهم می‌سازد. یک استثنا در این مورد SIGPIPE است که تا زمان اجرای دستور نادیده گرفته می‌شود.

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

با شروع از نسخه 1.2 رابط API افزونه، امکان نصب هوک‌ها (قلاب‌ها) برای توابع خاصی که توسط بخش جلویی sudo فراخوانی می‌شوند وجود دارد.

در حال حاضر، تنها هوک‌های پشتیبانی‌شده مربوط به مدیریت متغیرهای محیطی هستند. هوک‌ها می‌توانند برای رهگیری تلاش‌ها به منظور دریافت، تنظیم یا حذف متغیرهای محیطی استفاده شوند تا این تغییرات در نسخه محیطی که برای اجرای یک دستور به کار می‌رود منعکس شوند. نسخه‌های آتی API از قلاب کردن عملکردهای داخلی بخش جلویی sudo نیز پشتیبانی خواهند کرد.

ساختار هوک (Hook structure)

هوک‌ها در sudo توسط ساختار زیر توصیف می‌شوند:

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;
};

یک struct sudo_hook دارای فیلدهای زیر است:

hook_version
فیلد hook_version باید روی SUDO_HOOK_VERSION تنظیم شود.
hook_type
فیلد hook_type می‌تواند یکی از انواع هوک پشتیبانی‌شده زیر باشد:
تابع setenv(3) کتابخانه C. هر هوک ثبت‌شده پیش از پیاده‌سازی کتابخانه C اجرا خواهد شد. فیلد hook_fn باید تابعی باشد که با تعاریف typedef زیر مطابقت داشته باشد: 
typedef int (*sudo_hook_fn_setenv_t)(const char *name,
   const char *value, int overwrite, void *closure);

اگر هوک ثبت‌شده با typedef مطابقت نداشته باشد، نتایج نامشخص خواهد بود.

تابع unsetenv(3) کتابخانه C. هر هوک ثبت‌شده پیش از پیاده‌سازی کتابخانه C اجرا خواهد شد. فیلد hook_fn باید تابعی باشد که با تعاریف typedef زیر مطابقت داشته باشد: 
typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
   void *closure);
تابع getenv(3) کتابخانه C. هر هوک ثبت‌شده پیش از پیاده‌سازی کتابخانه C اجرا خواهد شد. فیلد hook_fn باید تابعی باشد که با تعاریف typedef زیر مطابقت داشته باشد: 
typedef int (*sudo_hook_fn_getenv_t)(const char *name,
   char **value, void *closure);

اگر هوک ثبت‌شده با typedef مطابقت نداشته باشد، نتایج نامشخص خواهد بود.

تابع putenv(3) کتابخانه C. هر هوک ثبت‌شده پیش از پیاده‌سازی کتابخانه C اجرا خواهد شد. فیلد hook_fn باید تابعی باشد که با تعاریف typedef زیر مطابقت داشته باشد: 
typedef int (*sudo_hook_fn_putenv_t)(char *string,
   void *closure);

اگر هوک ثبت‌شده با typedef مطابقت نداشته باشد، نتایج نامشخص خواهد بود.

hook_fn
sudo_hook_fn_t hook_fn;

فیلد hook_fn باید روی پیاده‌سازی هوک افزونه تنظیم شود. آرگومان‌های واقعی تابع بسته به hook_type متفاوت خواهند بود (به hook_type در بالا مراجعه کنید). در تمام موارد، فیلد closure از struct sudo_hook به عنوان آخرین پارامتر تابع ارسال می‌شود. این می‌تواند برای ارسال داده‌های دلخواه به پیاده‌سازی هوک افزونه استفاده شود.

مقدار بازگشتی تابع می‌تواند یکی از موارد زیر باشد:

تابع هوک با خطا مواجه شد.
هوک بدون خطا تکمیل شد، به هوک بعدی بروید (شامل پیاده‌سازی سیستم در صورت امکان). به عنوان مثال، یک هوک getenv(3) اگر متغیر مشخص‌شده در نسخه اختصاصی محیط یافت نشود، ممکن است مقدار SUDO_HOOK_RET_NEXT را بازگرداند.
هوک بدون خطا تکمیل شد، پردازش هوک‌ها برای این فراخوانی متوقف شود. این می‌تواند برای جایگزینی پیاده‌سازی سیستم استفاده شود. برای مثال، یک هوک setenv که روی یک نسخه اختصاصی از محیط عمل می‌کند اما environ را بدون تغییر باقی می‌گذارد.

هنگام قلاب کردن (hooking) توابع کتابخانه C باید دقت شود، زیرا ایجاد یک حلقه بی‌نهایت بسیار آسان است. به عنوان مثال، یک هوک getenv(3) که تابع snprintf(3) را فراخوانی می‌کند، اگر پیاده‌سازی snprintf(3) برای بررسی محلی‌سازی (locale) تابع getenv(3) را فراخوانی کند، ممکن است یک حلقه ایجاد کند. برای جلوگیری از این امر، ممکن است بخواهید از یک متغیر ایستا (static) در تابع هوک برای محافظت در برابر فراخوانی‌های تو در تو استفاده کنید. برای مثال:

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;

ماکروهای نسخه رابط هوک (Hook API Version Macros)

/* 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,\
                                              SUDO_HOOK_VERSION_MINOR)

برای توابع دریافت‌کننده و تنظیم‌کننده (getters and setters) به بخش Policy plugin API مراجعه کنید.

هنگامی که sudo دستوری را اجرا می‌کند، از یک حلقه رویداد (event loop) برای رسیدگی به سیگنال‌ها و I/O استفاده می‌نماید. رویدادها ممکن است بر اساس زمان، آماده شدن یک توصیف‌گر فایل یا سوکت، یا به دلیل دریافت یک سیگنال فعال شوند. از نسخه ۱.۱۵ رابط برنامه‌نویسی (API) به بعد، این امکان برای یک افزونه فراهم شده است که با فراخوانی تابع () در این حلقه رویداد مشارکت کند.

ساختار رویداد (Event structure)

رویدادها توسط ساختار زیر توصیف می‌شوند:

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);
};

یک struct sudo_plugin_event شامل اشاره‌گرهای تابع زیر است:

set
int (*set)(struct sudo_plugin_event *pev, int fd, int events,
    sudo_plugin_ev_callback_t callback, void *closure);

تابع () آرگومان‌های زیر را دریافت می‌کند:

struct sudo_plugin_event *pev
اشاره‌گری به خود struct sudo_plugin_event.
fd
توصیف‌گر فایل یا سوکت برای رویدادهای مبتنی بر I/O یا شماره سیگنال برای رویدادهای سیگنال. برای رویدادهای مبتنی بر زمان، fd باید -1 باشد.
events
مقادیر زیر مشخص می‌کنند که چه چیزی بازخوانی (callback) رویداد را فعال می‌کند:
کالبک پس از انقضای مهلت زمانی (timeout) مشخص‌شده اجرا می‌شود
کالبک هنگامی که توصیف‌گر فایل آماده خواندن باشد اجرا می‌شود
کالبک هنگامی که توصیف‌گر فایل آماده نوشتن باشد اجرا می‌شود
رویداد ماندگار است و تا زمانی که صریحاً حذف نشود فعال باقی می‌ماند
کالبک هنگام دریافت سیگنال مشخص‌شده اجرا می‌شود

فلگ SUDO_PLUGIN_EV_PERSIST می‌تواند با هر یک از انواع رویدادها با عملگر OR ترکیب شود. همچنین می‌توان SUDO_PLUGIN_EV_READ و SUDO_PLUGIN_EV_WRITE را با هم OR کرد تا کالبک هنگامی که یک توصیف‌گر چه برای خواندن و چه برای نوشتن آماده باشد اجرا شود. سایر مقادیر رویداد نسبت به یکدیگر مانعة‌الجمع هستند.

sudo_plugin_ev_callback_t callback
typedef void (*sudo_plugin_ev_callback_t)(int fd, int what,
    void *closure);

تابعی که هنگام فعال شدن یک رویداد باید فراخوانی شود. تابع () با آرگومان‌های زیر اجرا می‌شود:

fd
توصیف‌گر فایل یا سوکت برای رویدادهای مبتنی بر I/O یا شماره سیگنال برای رویدادهای سیگنال.
what
نوع رویدادی که موجب فعال شدن آن کالبک شده است. برای رویدادهایی که دارای چندین نوع رویداد هستند (برای مثال SUDO_PLUGIN_EV_READ و SUDO_PLUGIN_EV_WRITE) یا دارای مهلت زمانی مرتبط هستند، what می‌تواند برای تعیین علت اجرای کالبک استفاده شود.
closure
اشاره‌گر عمومی که در تابع set() مشخص شده است.
closure
اشاره‌گر عمومی که به تابع کالبک ارسال خواهد شد.

تابع () در صورت موفقیت مقدار 1 و در صورت بروز خطا مقدار -1 را بازمی‌گرداند.

add
int (*add)(struct sudo_plugin_event *pev, struct timespec *timeout);

تابع () رویداد pev را به حلقه رویداد sudo اضافه می‌کند. رویداد باید پیش‌تر از طریق تابع set() مقداردهی اولیه شده باشد. اگر آرگومان timeout مقدار NULL نباشد، باید یک مهلت زمانی (نسبی) را مشخص کند که اگر معیار اصلی رویداد برآورده نشده باشد، رویداد پس از آن فعال شود. این اغلب برای پیاده‌سازی مهلت زمانی I/O استفاده می‌شود، جایی که اگر توصیف‌گر در یک بازه زمانی مشخص آماده نشود، رویداد شلیک می‌شود. اگر رویداد از قبل در حلقه رویداد موجود باشد، timeout آن برای مطابقت با مقدار جدید (در صورت وجود) به‌روزرسانی خواهد شد.

تابع () در صورت موفقیت مقدار 1 و در صورت بروز خطا مقدار -1 را بازمی‌گرداند.

del
int (*del)(struct sudo_plugin_event *pev);

تابع () رویداد pev را از حلقه رویداد sudo حذف می‌کند. رویدادهای حذف‌شده می‌توانند دوباره از طریق تابع add() اضافه شوند.

تابع () در صورت موفقیت مقدار 1 و در صورت بروز خطا مقدار -1 را بازمی‌گرداند.

pending
int (*pending)(struct sudo_plugin_event *pev, int events,
    struct timespec *ts);

تابع () می‌تواند برای بررسی اینکه آیا یک یا چند رویداد در انتظار (pending) هستند یا خیر به کار رود. آرگومان events مشخص می‌کند که چه رویدادهایی بررسی شوند. برای مشاهده فهرستی از انواع رویدادهای معتبر، تابع set() را ببینید. اگر SUDO_PLUGIN_EV_TIMEOUT در events مشخص شده باشد، رویداد دارای مهلت زمانی مرتبط باشد و اشاره‌گر ts غیر NULL باشد، با زمان باقی‌مانده پر خواهد شد.

fd
int (*fd)(struct sudo_plugin_event *pev);

تابع () توصیف‌گر یا شماره سیگنال مرتبط با رویداد pev را بازمی‌گرداند.

setbase
void (*setbase)(struct sudo_plugin_event *pev, void *base);

تابع () پایه رویداد زیرین base را برای pev روی مقدار مشخص‌شده تنظیم می‌کند. این تابع می‌تواند برای انتقال رویدادی که از طریق event_alloc() ایجاد شده است به یک حلقه رویداد جدید تخصیص‌یافته توسط زیرسیستم رویداد sudo استفاده شود. اگر base برابر NULL باشد، پایه رویداد pev به مقدار پیش‌فرض بازنشانی می‌شود، که متناظر با حلقه رویداد اصلی sudo است. استفاده از این تابع نیازمند پیوند دادن (link) افزونه با کتابخانه sudo_util است. بعید است که در خارج از افزونه sudoers استفاده شود.

loopbreak
void (*loopbreak)(struct sudo_plugin_event *pev);

تابع () باعث می‌شود حلقه رویداد sudo بلافاصله خارج شود و دستور در حال اجرا پایان یابد.

free
void (*free)(struct sudo_plugin_event *pev);

تابع () رویداد pev را از حلقه رویداد حذف کرده و حافظه مرتبط با آن را آزاد می‌کند.

فرانت‌اند sudo از اجرای دستورات از راه دور پشتیبانی نمی‌کند. با این حال، از نسخه ۱.۸.۸ sudo به بعد، گزینه -h می‌تواند برای مشخص کردن یک میزبان راه دور که به افزونه خط‌مشی ارسال می‌شود استفاده شود. یک افزونه همچنین ممکن است یک runas_user را در قالب “user@hostname” بپذیرد که با نسخه‌های قدیمی‌تر sudo نیز کار خواهد کرد. پیش‌بینی می‌شود که دستورات راه دور با اجرای یک برنامه کمکی ( “helper” ) پشتیبانی شوند. افزونه خط‌مشی باید محیط اجرا را به گونه‌ای آماده کند که فرانت‌اند sudo برنامه کمکی را اجرا کند، و آن برنامه نیز به نوبه خود به میزبان راه دور متصل شده و دستور را اجرا نماید.

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

قابلیت راه دور sudoedit باید توسط افزونه خط‌مشی مدیریت شود، نه خود sudo ، چرا که فرانت‌اند اطلاعی از در حال اجرا بودن یک دستور راه دور ندارد. این موضوع ممکن است در بازنگری‌های آینده رابط برنامه‌نویسی افزونه برطرف شود.

اگر افزونه نیاز به تعامل با کاربر داشته باشد، می‌تواند این کار را از طریق تابع () انجام دهد. یک افزونه نباید تلاش کند مستقیماً از ورودی استاندارد یا ترمینال کاربر بخواند (وجود هیچ‌کدام تضمین نشده است). فراخواننده در صورتی که نیاز به چاپ خط جدید باشد، باید یک کاراکتر خط جدید انتهایی را در msg بگنجاند.

یک تابع به سبک () نیز در دسترس است که می‌تواند برای نمایش پیام‌های اطلاعاتی یا خطا به کاربر استفاده شود، که معمولاً برای پیام‌های ساده‌ای که به هیچ ورودی کاربری نیاز ندارند مناسب‌تر است.

ساختارهای تابع مکالمه (Conversation function structures)

تابع مکالمه به عنوان آرگومان، اشاره‌گرهایی به ساختارهای زیر را می‌گیرد:

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;
};

اشاره‌گرها به توابع () و به سبک printf() هنگام مقداردهی اولیه افزونه، به تابع open() افزونه ارسال می‌شوند. تعاریف نوع زیر می‌توانند در اعلان تابع open() استفاده شوند:

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, ...);

برای استفاده از تابع () ، افزونه باید آرایه‌ای از struct sudo_conv_message و struct sudo_conv_reply را ارسال کند. باید برای هر پیام در مکالمه یک struct sudo_conv_message و یک struct sudo_conv_reply وجود داشته باشد، به این معنی که هر دو آرایه باید دارای تعداد عناصر یکسانی باشند. هر struct sudo_conv_reply باید عضو reply خود را با NULL مقداردهی اولیه کرده باشد. اشاره‌گر struct sudo_conv_callback ، اگر NULL نباشد، باید شامل اشاره‌گرهای تابعی باشد که هنگام تعلیق (suspend) یا ازسرگیری (resume) فرآیند sudo در حین دریافت ورودی مکالمه فراخوانی شوند. توابع on_suspend و on_resume با سیگنالی که باعث تعلیق sudo شده است و اشاره‌گر closure از struct sudo_conv_callback فراخوانی می‌شوند. این توابع باید در صورت موفقیت مقدار 0 و در صورت بروز خطا مقدار -1 را بازگردانند. در صورت بروز خطا، مکالمه خاتمه می‌یابد و تابع مکالمه مقدار -1 را بازمی‌گرداند. کاربرد مورد نظر این است که به افزونه اجازه داده شود منابعی مانند قفل‌ها را که نباید هنگام تعلیق به طور نامحدود نگه داشته شوند آزاد کند و سپس با ازسرگیری فرآیند، دوباره آنها را در اختیار بگیرد. این توابع در واقع از داخل یک گرداننده سیگنال (signal handler) اجرا نمی‌شوند.

مقدار msg_type باید روی یکی از مقادیر زیر تنظیم شود:

درخواست ورودی از کاربر با غیرفعال بودن پژواک (echo) ورودی؛ این گزینه معمولاً برای گذرواژه‌ها استفاده می‌شود. پاسخ در آرایه replies ذخیره خواهد شد و هرگز NULL نخواهد بود.
درخواست ورودی از کاربر با فعال بودن پژواک (echo) ورودی. پاسخ در آرایه replies ذخیره خواهد شد و هرگز NULL نخواهد بود.
نمایش یک پیام خطا. پیام در خروجی خطای استاندارد (standard error) نوشته می‌شود مگر اینکه فلگ SUDO_CONV_PREFER_TTY تنظیم شده باشد، که در این صورت در صورت امکان در ترمینال کاربر نوشته می‌شود.
نمایش یک پیام. پیام در خروجی استاندارد (standard output) نوشته می‌شود مگر اینکه فلگ SUDO_CONV_PREFER_TTY تنظیم شده باشد، که در این صورت در صورت امکان در ترمینال کاربر نوشته می‌شود.
درخواست ورودی از کاربر با نمایش نویسه ستاره به ازای هر نویسه خوانده‌شده. پاسخ در آرایه replies ذخیره خواهد شد و هرگز NULL نخواهد بود. این می‌تواند برای ارائه بازخورد بصری به کاربر در حین خواندن اطلاعات حساسی که نباید نمایش داده شوند استفاده شود.

علاوه بر مقادیر فوق، بیت‌های فلگ زیر نیز می‌توانند تنظیم شوند:

اجازه خواندن ورودی در حالتی که غیرفعال کردن echo ممکن نیست، هنگامی که نوع پیام SUDO_CONV_PROMPT_ECHO_OFF یا SUDO_CONV_PROMPT_MASK باشد. به طور پیش‌فرض، اگر نتوان echo را برای این نوع پیام‌ها غیرفعال کرد، sudo از خواندن ورودی امتناع می‌ورزد.
هنگام نمایش پیام از طریق SUDO_CONV_ERROR_MSG یا SUDO_CONV_INFO_MSG ، تلاش می‌کند پیام را در ترمینال کاربر بنویسد. اگر ترمینال در دسترس نباشد، بسته به اینکه از SUDO_CONV_ERROR_MSG یا SUDO_CONV_INFO_MSG استفاده شده باشد، خروجی خطای استاندارد یا خروجی استاندارد استفاده خواهد شد. ترمینال کاربر همیشه در صورت امکان برای ورودی استفاده می‌شود؛ این فلگ تنها برای خروجی کاربرد دارد.

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

افزونه مسئول آزادسازی بافر پاسخ موجود در هر struct sudo_conv_reply است، در صورتی که مقدار آن NULL نباشد. ثابت SUDO_CONV_REPL_MAX نشان‌دهنده حداکثر طول بافر پاسخ است (بدون احتساب نویسه NUL انتهایی). از دیدگاه کاربردی، این طولانی‌ترین گذرواژه‌ای است که sudo پشتیبانی خواهد کرد.

تابع به سبک () از همان سازوکار زیرین تابع conversation() استفاده می‌کند اما فقط از SUDO_CONV_INFO_MSG و SUDO_CONV_ERROR_MSG برای پارامتر msg_type پشتیبانی می‌نماید. اگر نیازی به پاسخ کاربر نباشد، این تابع می‌تواند راحت‌تر از تابع conversation() باشد و از دنباله‌های فرار استاندارد printf() پشتیبانی می‌کند.

برای مشاهده یک مثال از کاربرد تابع () ، افزونه نمونه را ببینید.

از نسخه ۱.۹.۰ sudo به بعد، توابع open() و close() افزونه به ترتیب زیر فراخوانی می‌شوند:

  1. audit open
  2. policy open
  3. approval open
  4. approval close
  5. I/O log open
  6. اجرای دستور (command runs)
  7. خاتمه دستور (command exits)
  8. I/O log close
  9. policy close
  10. audit close
  11. خروج sudo

پیش از نسخه ۱.۹.۰ sudo ، تابع () لاگ I/O پس از تابع close() خط‌مشی فراخوانی می‌شد.

افزونه sudoers از رابط افزونه اختصاصی خود برای فعال‌سازی جستجوی گروه‌های غیر یونیکسی پشتیبانی می‌کند. این قابلیت می‌تواند برای پرس‌وجو از یک منبع گروه به غیر از پایگاه‌داده استاندارد گروه‌های یونیکس به کار رود. دو افزونه گروه نمونه همراه با sudo عرضه شده‌اند، و ، که جزئیات آنها در sudoers(5) آمده است. افزونه‌های گروه شخص ثالث شامل یک افزونه QAS AD هستند که توسط Quest Software عرضه شده است.

یک افزونه گروه باید یک struct sudoers_group_plugin را در حوزه سراسری (global scope) اعلان کرده و مقداردهی کند. این ساختار حاوی اشاره‌گرهایی به توابعی است که مقداردهی اولیه افزونه، پاک‌سازی و جستجوی گروه را پیاده‌سازی می‌کنند.

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);
};

یک struct sudoers_group_plugin دارای فیلدهای زیر است:

version
فیلد version باید روی GROUP_API_VERSION تنظیم شود.

این به sudoers امکان می‌دهد تا نسخه API که افزونه گروه بر اساس آن ساخته شده است را تشخیص دهد.

init
int (*init)(int version, sudo_printf_t sudo_plugin_printf,
    char *const argv[]);

تابع () پس از تجزیه شدن sudoers اما پیش از هرگونه بررسی خط‌مشی فراخوانی می‌شود. در صورت موفقیت مقدار 1، در صورت عدم موفقیت (یا اگر افزونه پیکربندی نشده باشد) مقدار 0 و در صورت بروز خطا مقدار -1 را بازمی‌گرداند. اگر خطایی رخ دهد، افزونه می‌تواند تابع () را با SUDO_CONF_ERROR_MSG فراخوانی کند تا اطلاعات خطای بیشتری را به کاربر نمایش دهد.

آرگومان‌های تابع به شرح زیر هستند:

version
نسخه ارسال‌شده توسط sudoers به افزونه امکان می‌دهد تا شماره نسخه اصلی و فرعی رابط افزونه گروه که توسط sudoers پشتیبانی می‌شود را مشخص کند.
plugin_printf
اشاره‌گری به یک تابع به سبک () که می‌تواند برای نمایش پیام‌های اطلاعاتی یا خطا به کاربر استفاده شود. در صورت موفقیت، تعداد نویسه‌های چاپ‌شده و در صورت شکست، مقدار -1 را بازمی‌گرداند.
argv
یک آرایه خاتمه‌یافته با NULL از آرگومان‌های تولیدشده از گزینه در sudoers است. اگر هیچ آرگومانی داده نشده باشد، argv برابر NULL خواهد بود.
cleanup
void (*cleanup)();

تابع () زمانی فراخوانی می‌شود که sudoers بررسی‌های گروه خود را به پایان رسانده باشد. افزونه باید هرگونه حافظه‌ای را که تخصیص داده است آزاد کند و توصیف‌گرهای باز فایل را ببندد.

query
int (*query)(const char *user, const char *group,
    const struct passwd *pwd);

تابع () برای پرسش از افزونه گروه در این باره که آیا user عضوی از group است یا خیر استفاده می‌شود.

آرگومان‌های تابع به شرح زیر هستند:

user
نام کاربری که در پایگاه‌داده خارجی گروه جستجو می‌شود.
group
نام گروهی که مورد پرس‌وجو قرار می‌گیرد.
pwd
مدخل پایگاه‌داده گذرواژه برای user (در صورت وجود). اگر user در پایگاه‌داده گذرواژه موجود نباشد، pwd برابر NULL خواهد بود.

ماکروهای نسخه رابط برنامه‌نویسی گروه (Group API Version Macros)

/* 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) | \
                           GROUP_API_VERSION_MINOR)
برای توابع دریافت‌کننده و تنظیم‌کننده (getters and setters) بخش Policy plugin API.

بازبینی‌های زیر در رابط برنامه‌نویسی افزونه‌های (API) سدو اعمال شده است.

Version 1.0
نسخه اولیه API.
Version 1.1 (sudo 1.8.0)
تابع () در افزونه‌های ثبت وقایع ورودی/خروجی (I/O logging) به گونه‌ای اصلاح شد که فهرست command_info را به عنوان یک آرگومان دریافت کند.
Version 1.2 (sudo 1.8.5)
به توابع open() در افزونه‌های خط‌مشی (Policy) و ثبت ورودی/خروجی (I/O logging) اکنون در صورت مشخص شدن پارامترهای افزونه در sudo.conf(5) ، فهرستی از آن‌ها ارسال می‌شود.

یک رابط هوک (hooks API) ساده معرفی شده است که به افزونه‌ها اجازه می‌دهد به توابع مدیریت محیط سیستم متصل شوند.

به تابع () در افزونه خط‌مشی، اکنون اشاره‌گری به محیط کاربری ارسال می‌شود که در صورت نیاز قابل به‌روزرسانی است. از این قابلیت می‌توان برای ادغام متغیرهای محیطی ذخیره‌شده در دسته PAM پیش از اجرای دستور استفاده کرد.

Version 1.3 (sudo 1.8.7)
پشتیبانی از ورودی exec_background به فهرست command_info اضافه شد.

ورودی‌های و به فهرست settings اضافه شدند.

توابع () و close() اکنون اختیاری هستند. پیش از این، عدم وجود تابع version() یا close() منجر به از کار افتادن برنامه (کرش) می‌شد. اگر هیچ تابع close() در افزونه خط‌مشی تعریف نشده باشد، یک تابع close() پیش‌فرض توسط فرانت‌اند sudo ارائه می‌شود که در صورت عدم امکان اجرای دستور، یک هشدار نمایش می‌دهد.

فرانت‌اند sudo اکنون گرداننده‌های سیگنال (signal handlers) پیش‌فرضی را برای به‌دام‌انداختن سیگنال‌های متداول هنگام اجرای توابع افزونه نصب می‌کند.

Version 1.4 (sudo 1.8.8)
ورودی به فهرست settings اضافه شد.
Version 1.5 (sudo 1.8.9)
ورودی به فهرست command_info اضافه شد.
Version 1.6 (sudo 1.8.11)
رفتار سیستم هنگام بازگرداندن خطا توسط افزونه ثبت ورودی/خروجی (-1) تغییر کرده است. پیش از این، فرانت‌اند sudo هنگامی که توابع (،) log_ttyout(،) log_stdin(،) log_stdout() یا log_stderr() خطایی بازمی‌گرداندند، هیچ اقدامی انجام نمی‌داد.

رفتار سیستم هنگامی که یک افزونه ثبت ورودی/خروجی مقدار 0 را برمی‌گرداند تغییر کرده است. پیش از این، خروجی دستور حتی در صورتی که تابع ثبت خروجی مقدار 0 را بازمی‌گرداند نیز روی ترمینال نمایش داده می‌شد.

Version 1.7 (sudo 1.8.12)
ورودی به فهرست settings اضافه شد.

ورودی debug_flags اکنون با نام مسیر فایل اشکال‌زدایی آغاز می‌شود و در صورتی که چندین خط Debug ویژه افزونه در فایل sudo.conf(5) وجود داشته باشد، ممکن است چندین بار تکرار شود.

Version 1.8 (sudo 1.8.15)
ورودی‌های sudoedit_checkdir و sudoedit_follow به فهرست command_info اضافه شدند. مقدار پیش‌فرض sudoedit_checkdir در sudo 1.8.16 به true تغییر یافت.

تابع () در sudo اکنون اشاره‌گری به یک struct sudo_conv_callback را به عنوان چهارمین آرگومان خود دریافت می‌کند. تعریف sudo_conv_t برای تطابق به‌روزرسانی شده است. افزونه باید مشخص کند که از نسخه 1.8 یا بالاتر API افزونه پشتیبانی می‌کند تا اشاره‌گر تابع گفتگویی را دریافت نماید که از این آرگومان پشتیبانی می‌کند.

Version 1.9 (sudo 1.8.16)
ورودی به فهرست command_info اضافه شد.
Version 1.10 (sudo 1.8.19)
ورودی umask به فهرست user_info اضافه شد. ورودی‌های و به فهرست command_info اضافه شدند.
Version 1.11 (sudo 1.8.20)
ورودی timeout به فهرست settings اضافه شد.
Version 1.12 (sudo 1.8.21)
تابع change_winsize() به struct io_plugin اضافه شد.
Version 1.13 (sudo 1.8.26)
تابع log_suspend() به struct io_plugin اضافه شد.
Version 1.14 (sudo 1.8.29)
ورودی umask_override به فهرست command_info اضافه شد.
Version 1.15 (sudo 1.9.0)
ورودی cwd_optional به فهرست command_info اضافه شد.

تابع () به struct policy_plugin و struct io_plugin اضافه شد.

آرگومان errstr به توابع افزونه‌های خط‌مشی و ورودی/خروجی افزوده شد که تابع افزونه می‌تواند از آن برای بازگرداندن رشته خطا استفاده کند. این رشته ممکن است توسط افزونه حسابرسی (audit plugin) برای گزارش شرایط شکست یا خطای تعیین‌شده توسط سایر افزونه‌ها به کار رود.

تابع () اکنون صرف‌نظر از اینکه دستوری واقعاً اجرا شده است یا خیر، فراخوانی می‌شود. این امر امکان پاک‌سازی منابع را برای افزونه‌ها حتی در صورت عدم اجرای دستور فراهم می‌آورد.

مقدار SUDO_CONV_REPL_MAX از ۲۵۵ به ۱۰۲۳ بایت افزایش یافت.

پشتیبانی از افزونه‌های حسابرسی (audit) و تایید (approval) اضافه شد.

Version 1.16 (sudo 1.9.3)
مقادیر اولیه محدودیت منابع به فهرست user_info اضافه شدند.

ورودی‌های و به فهرست settings اضافه شدند.

Version 1.17 (sudo 1.9.4)
تابع () به struct audit_plugin و struct approval_plugin اضافه شد.
Version 1.18 (sudo 1.9.9)
افزونه خط‌مشی اکنون می‌تواند مقادیر محدودیت منابع را در فهرست command_info تنظیم کند. ورودی‌های intercept و log_subcmds به فهرست command_info اضافه شدند.
Version 1.19 (sudo 1.9.11)
ورودی‌های و به فهرست settings اضافه شدند. ورودی‌های و use_ptrace به فهرست command_info اضافه شدند.
Version 1.20 (sudo 1.9.12)
ورودی به فهرست settings اضافه شد. ورودی به فهرست command_info اضافه شد.
Version 1.21 (sudo 1.9.13)
ورودی sudoedit_nfiles به فهرست command_info اضافه شد.
Version 1.22 (sudo 1.9.16)
ورودی به فهرست user_info اضافه شد.

sudo.conf(5), sudoers(5), sudo(8)

افراد بسیاری در طول سال‌ها روی sudo کار کرده‌اند؛ این نسخه عمدتاً شامل کدهای نوشته‌شده توسط فرد زیر است:

Todd C. Miller

برای فهرست کامل افرادی که در sudo مشارکت داشته‌اند، پرونده CONTRIBUTORS.md را در توزیع sudo (https://www.sudo.ws/about/contributors) مشاهده فرمایید.

اگر معتقدید اشکالی در sudo_plugin یافته‌اید، می‌توانید یک گزارش اشکال در پایگاه‌داده اشکالات سدو در https://bugzilla.sudo.ws ثبت کنید یا یک issue در https://github.com/sudo-project/sudo/issues باز نمایید. چنانچه ترجیح می‌دهید از ایمیل استفاده کنید، پیام‌ها می‌توانند به فهرست پستی sudo-workers در https://www.sudo.ws/mailman/listinfo/sudo-workers (عمومی) یا به <sudo@sudo.ws> (خصوصی) ارسال شوند.

لطفاً آسیب‌پذیری‌های امنیتی را از طریق issueهای عمومی گیت‌هاب، باگزیلا یا فهرست‌های پستی گزارش نکنید. در عوض، آن‌ها را از طریق ایمیل به <Todd.Miller@sudo.ws> گزارش دهید. در صورت تمایل می‌توانید پیام خود را با کلید PGP موجود در https://www.sudo.ws/dist/PGPKEYS رمزگذاری کنید.

پشتیبانی رایگان و محدود از طریق فهرست پستی sudo-users در دسترس است، برای عضویت یا جستجو در آرشیو نشانی https://www.sudo.ws/mailman/listinfo/sudo-users را ببینید.

sudo به‌صورت “AS IS” ارائه می‌شود و هرگونه ضمانت صریح یا ضمنی، از جمله، اما نه محدود به، ضمانت‌های ضمنی قابلیت فروش و تناسب برای یک هدف خاص سلب می‌شود. برای جزئیات کامل، پرونده LICENSE.md ارائه‌شده همراه با sudo یا نشانی https://www.sudo.ws/about/license را ملاحظه فرمایید.

August 14, 2024 Sudo 1.9.17p2