نام (NAME)

dbus-broker - واسط و کارگزار گذرگاه پیام لینوکس D-Bus

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

dbus-broker [ گزینه‌ها ]
dbus-broker --version
dbus-broker --help

توضیحات (DESCRIPTION)

برنامه dbus-broker یک پیاده‌سازی از مشخصات گذرگاه پیام D-Bus [1] است. هر نمونه از آن یک گذرگاه پیام یکتا و مستقل را فراهم می‌کند که کلاینت‌ها می‌توانند به آن متصل شده و از طریق آن پیام ردوبدل کنند. این واسط بر اساس مشخصات D-Bus، وظیفه میانجی‌گری پیام‌ها، کنترل دسترسی، اشتراک‌ها و کنترل گذرگاه را بر عهده دارد.

برنامه dbus-broker یک پیاده‌سازی محض است؛ به این معنی که تنها میانجی‌گری پیام‌ها را انجام می‌دهد. این برنامه به یک فرایند کنترل‌کننده نیاز دارد که برپاسازی گذرگاه و تمامی ارتباطات خارجی را مدیریت کند. برنامه dbus-broker-launch(1) نمونه‌ای از چنین کنترل‌کننده‌ای است که هدف آن سازگاری کامل با dbus-daemon(1)، پیاده‌سازی مرجع D-Bus، می‌باشد. برای مشاهده جزئیات چگونگی راه‌اندازی یک گذرگاه پیام به dbus-broker-launch(1) مراجعه کنید.

این صفحه راهنما رابط میان dbus-broker و کنترل‌کننده آن (مانند dbus-broker-launch(1)) را مستند می‌کند.

گزینه‌ها (OPTIONS)

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

کنترل‌کننده (CONTROLLER)

هر نمونه از dbus-broker یک سوکت unix(7) را از فرایند والد خود به ارث می‌برد. این سوکت باید از طریق گزینه --controller مشخص شود. واسط از این سوکت برای دریافت دستورهای کنترلی از فرایند والد خود (یا از هر کسی که طرف دیگر این سوکت را در اختیار دارد، که کنترل‌کننده نیز نامیده می‌شود) استفاده می‌کند. این سوکت از ارتباطات نقطه به نقطه (P2P) استاندارد D-Bus بهره می‌برد. رابط‌های ارائه‌شده روی این سوکت در بخش رابط برنامه‌نویسی (API) شرح داده شده‌اند.

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

فرایند dbus-broker هرگز به هیچ منبع خارجی فراتر از آنچه از طریق خط فرمان یا رابط‌های کنترل‌کننده به آن منتقل شده است دسترسی پیدا نمی‌کند؛ یعنی هیچ دسترسی به سیستم‌فایل، هیچ فراخوانی nss(5) و هیچ ارتباطی با فرایندهای خارجی توسط واسط انجام نمی‌گیرد. برعکس، واسط هرگز به منبعی جز سوکت‌هایی که توسط کنترل‌کننده به آن اختصاص یافته دسترسی ندارد. این موضوع توسط پیاده‌سازی نرم‌افزار تضمین شده است. در عین حال، این امر بدین معناست که کنترل‌کننده موظف است در صورت نیاز، تمام منابع خارجی لازم را فراهم ساخته و ارتباطات را به نمایندگی از واسط انجام دهد.

ثبت وقایع (LOGGING)

اگر یک توصیف‌گر فایل (FD) برای ثبت وقایع از طریق گزینه خط فرمان --log مشخص شود، واسط اطلاعاتی را از طریق این FD ثبت می‌کند. دو نوع مختلف ثبت لاگ پشتیبانی می‌شود:

واسط قوانین سخت‌گیرانه‌ای برای زمان ثبت داده‌ها دارد. هنگام راه‌اندازی و خاموش شدن، هر بار یک پیام برای ارائه اطلاعاتی درباره تنظیمات و محیط خود ثبت می‌کند. در زمان اجرا، واسط تنها در شرایط غیرمنتظره اقدام به ثبت لاگ می‌کند؛ به این معنا که هر پیامی که واسط در زمان اجرا ثبت می‌کند، بر اثر عملکرد نادرست یک کلاینت رخ داده است. اگر سیستم به درستی پیکربندی شده باشد، هیچ پیام لاگی در زمان اجرا ثبت نخواهد شد.

مواردی که در آن‌ها واسط اقدام به ثبت گزارش می‌کند عبارتند از:

رابط برنامه‌نویسی (API)

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

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

node /org/bus1/DBus/Broker {
interface org.bus1.DBus.Broker {
# Create new activatable name @name, accounted on user @uid. The name
# will be exposed by the controller as @path (which must fit the
# template /org/bus1/DBus/Name/%).
method AddName(o path, s name, u uid) -> ()
# 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 /org/bus1/DBus/Listener/%).
# The policy for all clients connecting through this socket is
# provided as @policy. See org.bus1.DBus.Listener.SetPolicy() for
# details.
method AddListener(o path, h socket, v policy) -> ()
# This signal is raised according to client-requests of
# org.freedesktop.DBus.UpdateActivationEnvironment().
signal SetActivationEnvironment(a{ss} environment)
}
}
node /org/bus1/DBus/Listener/% {
interface org.bus1.DBus.Listener {
# 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.
method Release() -> ()
# Change the policy on this listener socket to @policy. The syntax of
# the policy is still subject to change and not stable, yet.
method SetPolicy(v policy) -> ()
}
}
node /org/bus1/DBus/Name/% {
interface org.bus1.DBus.Name {
# 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.
method 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.
method Reset(t serial, s error) -> ()
# Activation request failed: a concurrent deactivation request is already in progress
error org.bus1.DBus.Name.Error.DestructiveTransaction
# Activation request failed: unknown unit
error org.bus1.DBus.Name.Error.UnknownUnit
# Activation request failed: unit is masked
error org.bus1.DBus.Name.Error.MaskedUnit
# Activation request failed: unit is invalid
error org.bus1.DBus.Name.Error.InvalidUnit
# Unit activation job succeeded, but the unit failed afterwards
error org.bus1.DBus.Name.Error.UnitFailure
# The startup job was valid, but it failed during activation
error org.bus1.DBus.Name.Error.StartupFailure
# The startup job was valid, but it was skipped during activation
error org.bus1.DBus.Name.Error.StartupSkipped
# Activation request cancelled: bus name was released
error org.bus1.DBus.Name.Error.NameReleased
# 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
# Reset() 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 Reset(). The serial number is
# unique for each event, and is never reused. A serial number of 0
# is never sent and considered invalid.
signal Activate(t serial)
}
}

کنترل‌کننده موظف است رابط‌های زیر را بر روی گره‌های مشخص‌شده پیاده‌سازی کند. این رابط‌ها توسط واسط فراخوانی می‌شوند تا بخش‌هایی از رابط درایور (driver-interface) طبق مشخصات D-Bus پیاده‌سازی شوند.

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

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

node /org/bus1/DBus/Controller {
interface org.bus1.DBus.Controller {
# This function is called for each client-request of
# org.freedesktop.DBus.ReloadConfig().
method ReloadConfig() -> ()
}
}

گزارش باگ‌ها (REPORTING BUGS)

گزارش اشکالات و مشکلات نرم‌افزاری را در سامانه ردیابی پروژه ثبت کنید: https://github.com/bus1/dbus-broker/issues

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

dbus-broker-launch(1)، dbus-daemon(1)

یادداشت‌ها (NOTES)

[1]

مشخصات D-Bus: https://dbus.freedesktop.org/doc/dbus-specification.html