.\" Man page generated from reStructuredText .\" by the Docutils 0.22.3 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "DBUS\-BROKER" "1" "سپتامبر ۲۰۲۲" "dbus-broker" "دستورهای کاربری" .SH "نام (NAME)" dbus-broker \- واسط و کارگزار گذرگاه پیام لینوکس D-Bus .SH "خلاصه دستور (SYNOPSIS)" .nf \fBdbus\-broker\fP [ \fIگزینه‌ها\fP ] \fBdbus\-broker\fP \fB\-\-version\fP \fBdbus\-broker\fP \fB\-\-help\fP .fi .sp .SH "توضیحات (DESCRIPTION)" .sp برنامه \fBdbus\-broker\fP یک پیاده‌سازی از مشخصات گذرگاه پیام .BR D\-Bus [1] است. هر نمونه از آن یک گذرگاه پیام یکتا و مستقل را فراهم می‌کند که کلاینت‌ها می‌توانند به آن متصل شده و از طریق آن پیام ردوبدل کنند. این واسط بر اساس مشخصات D\-Bus، وظیفه میانجی‌گری پیام‌ها، کنترل دسترسی، اشتراک‌ها و کنترل گذرگاه را بر عهده دارد. .sp برنامه \fBdbus\-broker\fP یک پیاده‌سازی \fIمحض\fP است؛ به این معنی که تنها میانجی‌گری پیام‌ها را انجام می‌دهد. این برنامه به یک فرایند کنترل‌کننده نیاز دارد که برپاسازی گذرگاه و تمامی ارتباطات خارجی را مدیریت کند. برنامه .BR dbus\-broker\-launch (1) نمونه‌ای از چنین کنترل‌کننده‌ای است که هدف آن سازگاری کامل با .BR dbus\-daemon (1)، پیاده‌سازی مرجع D\-Bus، می‌باشد. برای مشاهده جزئیات چگونگی راه‌اندازی یک گذرگاه پیام به .BR dbus\-broker\-launch (1) مراجعه کنید. .sp این صفحه راهنما رابط میان \fBdbus\-broker\fP و کنترل‌کننده آن (مانند .BR dbus\-broker\-launch (1)) را مستند می‌کند. .SH "گزینه‌ها (OPTIONS)" .sp گزینه‌های خط فرمان زیر پشتیبانی می‌شوند. در صورتی که گزینه‌ای ارسال شود که در این فهرست وجود ندارد، واسط از راه‌اندازی خودداری کرده و با یک خطا خارج می‌شود. .INDENT 0.0 .TP .BR \-h ", " \-\-help چاپ اطلاعات نحوه استفاده و خروج فوری. .TP .B \-\-version چاپ نسخه ساخت برنامه و خروج فوری. .TP .B \-\-audit فعال‌سازی ثبت وقایع در زیرسیستم حسابرسی (audit) لینوکس (در صورتی که پشتیبانی از audit در زمان کامپایل گنجانده نشده باشد، این گزینه بی‌استفاده خواهد بود؛ \fBپیش‌فرض\fP: خاموش). .TP .BI \-\-controller\fB= FD استفاده از توصیف‌گر فایل (file descriptor) به ارث‌رسیده با شماره داده‌شده به عنوان سوکت کنترل‌کننده (بخش \fBکنترل‌کننده (CONTROLLER)\fP را ببینید؛ استفاده از این گزینه الزامی است). .TP .BI \-\-log \ FD استفاده از توصیف‌گر فایل به ارث‌رسیده با شماره داده‌شده برای دسترسی به لاگ سیستم (بخش \fBثبت وقایع (LOGGING)\fP را ببینید؛ \fBپیش‌فرض\fP: بدون ثبت لاگ). .TP .BI \-\-machine\-id\fB= ID تنظیم شناسه ماشین (machine-id) که باید توسط واسط از طریق رابط org.freedesktop.DBus اعلام شود (استفاده از این گزینه الزامی است و معمولاً مقدار آن از /etc/machine\-id خوانده می‌شود). .TP .BI \-\-max\-bytes\fB= BYTES حداکثر تعداد بایت‌هایی که هر کاربر مجاز است در واسط تخصیص دهد (\fBپیش‌فرض\fP: ۱۶ مبی‌بایت / 16 MiB). .TP .BI \-\-max\-fds\fB= FDS حداکثر تعداد توصیف‌گرهای فایلی که هر کاربر مجاز است در واسط تخصیص دهد (\fBپیش‌فرض\fP: ۶۴). .TP .BI \-\-max\-matches\fB= MATCHES حداکثر تعداد قوانین تطبیق (match rules) که هر کاربر مجاز است در واسط تخصیص دهد (\fBپیش‌فرض\fP: ۱۶ هزار / 16k). .TP .BI \-\-max\-objects\fB= OBJECTS حداکثر تعداد کل نام‌ها، همتایان (peers)، پاسخ‌های در انتظار و غیره که هر کاربر مجاز است در واسط تخصیص دهد (\fBپیش‌فرض\fP: ۱۶ هزار / 16k). .UNINDENT .SH "کنترل‌کننده (CONTROLLER)" .sp هر نمونه از \fBdbus\-broker\fP یک سوکت .BR unix (7) را از فرایند والد خود به ارث می‌برد. این سوکت باید از طریق گزینه \fB\-\-controller\fP مشخص شود. واسط از این سوکت برای دریافت دستورهای کنترلی از فرایند والد خود (یا از هر کسی که طرف دیگر این سوکت را در اختیار دارد، که \fIکنترل‌کننده\fP نیز نامیده می‌شود) استفاده می‌کند. این سوکت از ارتباطات نقطه به نقطه (P2P) استاندارد D\-Bus بهره می‌برد. رابط‌های ارائه‌شده روی این سوکت در بخش \fBرابط برنامه‌نویسی (API)\fP شرح داده شده‌اند. .sp به‌طور پیش‌فرض، یک نمونه از واسط در حالت غیرفعال (idle) قرار دارد؛ یعنی پس از ساخت فرایند (fork) و اجرای واسط، کار خود را با یک فهرست خالی از سوکت‌های گذرگاه برای مدیریت آغاز می‌کند و هیچ راهی برای اتصال کلاینت‌ها به آن وجود ندارد. کنترل‌کننده باید با استفاده از رابط کنترل‌کننده، سوکت‌های شنونده ایجاد کند، سیاست‌های گذرگاه را مشخص نماید، نام‌های قابل فعال‌سازی بسازد و به رویدادهای گذرگاه واکنش نشان دهد. .sp فرایند \fBdbus\-broker\fP هرگز به هیچ منبع خارجی فراتر از آنچه از طریق خط فرمان یا رابط‌های کنترل‌کننده به آن منتقل شده است دسترسی پیدا نمی‌کند؛ یعنی هیچ دسترسی به سیستم‌فایل، هیچ فراخوانی .BR nss (5) و هیچ ارتباطی با فرایندهای خارجی توسط واسط انجام نمی‌گیرد. برعکس، واسط هرگز به منبعی جز سوکت‌هایی که توسط کنترل‌کننده به آن اختصاص یافته دسترسی ندارد. این موضوع توسط پیاده‌سازی نرم‌افزار تضمین شده است. در عین حال، این امر بدین معناست که کنترل‌کننده موظف است در صورت نیاز، تمام منابع خارجی لازم را فراهم ساخته و ارتباطات را به نمایندگی از واسط انجام دهد. .SH "ثبت وقایع (LOGGING)" .sp اگر یک توصیف‌گر فایل (FD) برای ثبت وقایع از طریق گزینه خط فرمان \fB\-\-log\fP مشخص شود، واسط اطلاعاتی را از طریق این FD ثبت می‌کند. دو نوع مختلف ثبت لاگ پشتیبانی می‌شود: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 اگر FD یک سوکت .BR unix (7) از نوع \fBSOCK_STREAM\fP باشد، اطلاعات به صورت قطعه‌های خط‌به‌خط و خوانا برای انسان ثبت می‌شوند. .IP 2. 3 اگر FD یک سوکت .BR unix (7) از نوع \fBSOCK_DGRAM\fP باشد، اطلاعات به صورت بلوک‌های داده نشانه‌گذاری‌شده بر پایه کلید/مقدار ثبت می‌شوند. این فرمت با فرمت مورد استفاده در systemd\-journal سازگار است (هرچند به systemd وابسته نیست). این نوع ثبت لاگِ مبتنی بر کلید/مقدار، نسبت به ثبت لاگ جریانی بسیار پرجزئیات‌تر است. فراداده‌های فراوانی به صورت کلیدهای مجزا ارائه می‌شوند که امکان ردیابی و تفسیر دقیق داده‌های ثبت‌شده را فراهم می‌سازند. .UNINDENT .UNINDENT .UNINDENT .sp واسط قوانین سخت‌گیرانه‌ای برای زمان ثبت داده‌ها دارد. هنگام راه‌اندازی و خاموش شدن، هر بار یک پیام برای ارائه اطلاعاتی درباره تنظیمات و محیط خود ثبت می‌کند. در زمان اجرا، واسط تنها در شرایط غیرمنتظره اقدام به ثبت لاگ می‌کند؛ به این معنا که هر پیامی که واسط در زمان اجرا ثبت می‌کند، بر اثر عملکرد نادرست یک کلاینت رخ داده است. اگر سیستم به درستی پیکربندی شده باشد، هیچ پیام لاگی در زمان اجرا ثبت نخواهد شد. .sp مواردی که در آن‌ها واسط اقدام به ثبت گزارش می‌کند عبارتند از: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 در هنگام راه‌اندازی و خاموش شدن، واسط یک پیام کوتاه شامل فراداده‌هایی پیرامون کنترل‌کننده، محیط و پیکربندی خود ارسال می‌کند. .IP 2. 3 هر زمان که یک درخواست کلاینت توسط سیاست‌های امنیتی (policy) رد شود، پیامی شامل اطلاعات کلاینت مربوطه و سیاست‌های درگیر ثبت می‌شود. .IP 3. 3 هر زمان که یک کلاینت از سهمیه منابع (resource quota) خود فراتر رود، پیامی حاوی اطلاعات مربوط به آن کلاینت ثبت می‌گردد. .UNINDENT .UNINDENT .UNINDENT .SH "رابط برنامه‌نویسی (API)" .sp رابط‌های زیر توسط واسط بر روی گره‌های متناظر پیاده‌سازی شده‌اند. کنترل‌کننده مجاز است این رابط‌ها را در هر زمان فراخوانی کند. اتصال کنترل‌کننده به عنوان یک اتصال قابل‌اعتماد در نظر گرفته می‌شود و هیچ‌گونه محاسبه منابع یا کنترل دسترسی روی آن انجام نمی‌گیرد. .sp خود کنترل‌کننده نیز موظف است رابط‌هایی را پیاده‌سازی کند تا توسط واسط فراخوانی شوند. برای مشاهده فهرستی از رابط‌های کنترل‌کننده، به بخش‌های پس از این بخش مراجعه نمایید. .nf \fBnode\fP /org/bus1/DBus/Broker { .in +2 \fBinterface\fP org.bus1.DBus.Broker { .in +2 # Create new activatable name @name, accounted on user @uid. The name # will be exposed by the controller as @path (which must fit the # template \fI/org/bus1/DBus/Name/%\fP). \fBmethod\fP AddName(\fBo\fP \fIpath\fP, \fBs\fP \fIname\fP, \fBu\fP \fIuid\fP) \-> () # Add a listener socket to this bus. The listener socket must be # ready in listening mode and specified as @socket. As soon as this # call returns, incoming client connection attempts will be served # on this socket. # The listener is exposed by the controller as @path (which must fit # the template \fI/org/bus1/DBus/Listener/%\fP). # The policy for all clients connecting through this socket is # provided as @policy. See \fBorg.bus1.DBus.Listener.SetPolicy()\fP for # details. \fBmethod\fP AddListener(\fBo\fP \fIpath\fP, \fBh\fP \fIsocket\fP, \fBv\fP \fIpolicy\fP) \-> () # This signal is raised according to client\-requests of # \fBorg.freedesktop.DBus.UpdateActivationEnvironment()\fP\&. \fBsignal\fP SetActivationEnvironment(\fBa{ss}\fP \fIenvironment\fP) .in -2 } .in -2 } \fBnode\fP /org/bus1/DBus/Listener/% { .in +2 \fBinterface\fP org.bus1.DBus.Listener { .in +2 # Release this listener. It will immediately be removed by the broker # and no more connections will be served on it. All clients connected # through this listener are forcefully disconnected. \fBmethod\fP Release() \-> () # Change the policy on this listener socket to @policy. The syntax of # the policy is still subject to change and not stable, yet. \fBmethod\fP SetPolicy(\fBv\fP \fIpolicy\fP) \-> () .in -2 } .in -2 } \fBnode\fP /org/bus1/DBus/Name/% { .in +2 \fBinterface\fP org.bus1.DBus.Name { .in +2 # Release this activatable name. It will be removed with immediate # effect by the broker. Note that the name is still valid to be # acquired by clients, though no activation\-features will be # supported on this name. \fBmethod\fP Release() \-> () # Reset the activation state of this name. Any pending activation # requests are cancelled. The call requires a serial number to be # passed along. This must be the serial number received by the last # activation event on this name. Calls for other serial numbers are # silently ignored and considered stale. # A org.bus1.DBus.Name.Error string is also passed, giving a hint # about the reason the activation was reset. The list is defined below. \fBmethod\fP Reset(\fBt\fP \fIserial\fP, \fBs\fP \fIerror\fP) \-> () # Activation request failed: a concurrent deactivation request is already in progress \fBerror\fP \fIorg.bus1.DBus.Name.Error.DestructiveTransaction\fP # Activation request failed: unknown unit \fBerror\fP \fIorg.bus1.DBus.Name.Error.UnknownUnit\fP # Activation request failed: unit is masked \fBerror\fP \fIorg.bus1.DBus.Name.Error.MaskedUnit\fP # Activation request failed: unit is invalid \fBerror\fP \fIorg.bus1.DBus.Name.Error.InvalidUnit\fP # Unit activation job succeeded, but the unit failed afterwards \fBerror\fP \fIorg.bus1.DBus.Name.Error.UnitFailure\fP # The startup job was valid, but it failed during activation \fBerror\fP \fIorg.bus1.DBus.Name.Error.StartupFailure\fP # The startup job was valid, but it was skipped during activation \fBerror\fP \fIorg.bus1.DBus.Name.Error.StartupSkipped\fP # Activation request cancelled: bus name was released \fBerror\fP \fIorg.bus1.DBus.Name.Error.NameReleased\fP # This signal is sent whenever a client requests activation of this # name. Note that multiple activation requests are coalesced by the # broker. The controller can cancel outstanding requests via the # \fBReset()\fP method. # The broker sends a serial number with the event. This number # represents the activation request and must be used when reacting # to the request with methods like \fIReset()\fP\&. The serial number is # unique for each event, and is never reused. A serial number of 0 # is never sent and considered invalid. \fBsignal\fP Activate(\fBt\fP \fIserial\fP) .in -2 } .in -2 } .fi .sp .sp کنترل‌کننده موظف است رابط‌های زیر را بر روی گره‌های مشخص‌شده پیاده‌سازی کند. این رابط‌ها توسط واسط فراخوانی می‌شوند تا بخش‌هایی از رابط درایور (driver-interface) طبق مشخصات D\-Bus پیاده‌سازی شوند. .sp توجه داشته باشید که تمام فراخوانی‌های متد توسط واسط همواره کاملاً ناهمگام (asynchronous) هستند؛ یعنی صرف‌نظر از مدت زمانی که پاسخ‌گویی به درخواست طول می‌کشد، واسط همچنان کاملاً فعال و عملیاتی باقی می‌ماند و حتی ممکن است درخواست‌های بیشتری را به کنترل‌کننده ارسال کند. .sp کنترل‌کننده مجاز است این متدها را به صورت مسدودکننده (blocking) پیاده‌سازی نماید. با این حال، مسئولیت اطمینان از عدم انجام فراخوانی‌های بازگشتی \fBمسدودکننده\fP به واسط (از هر طریقی) بر عهده کنترل‌کننده خواهد بود. .nf \fBnode\fP /org/bus1/DBus/Controller { .in +2 \fBinterface\fP org.bus1.DBus.Controller { .in +2 # This function is called for each client\-request of # \fIorg.freedesktop.DBus.ReloadConfig()\fP\&. \fBmethod\fP ReloadConfig() \-> () .in -2 } .in -2 } .fi .sp .SH "گزارش باگ‌ها (REPORTING BUGS)" .PP گزارش اشکالات و مشکلات نرم‌افزاری را در سامانه ردیابی پروژه ثبت کنید: \% .SH "همچنین ببینید (SEE ALSO)" .sp .BR dbus\-broker\-launch (1)، .BR dbus\-daemon (1) .SH "یادداشت‌ها (NOTES)" .IP [1] 5 مشخصات D\-Bus: \%