Jump to: navigation, search

FreeIPAv2:SSSD/SBUS

Obsolete Documentation

Please note that this content was marked as obsolete. We left the content here for study and archaeological purposes.

Please check our Documentation for a recent list of topics.

Overview of D-BUS Protocol

The D-BUS protocol was designed as an IPC mechanism for use in desktop components. The D-BUS specification provides a marshalled wire format for transmitting signals and method calls to other processes.

The D-BUS protocol has four primary components:

The D-BUS Server

A common source of confusion, the D-BUS server is not a server in the traditional sense. Rather than accepting connections and listening for requests on that connection, the D-BUS server is instead used only for establishing connections.

The D-BUS Connection

This is the workhorse of the D-BUS protocol. Once a D-BUS connection has been made to a D-BUS server, it becomes a peer-to-peer connection. Either end of the connection can listen for method calls or signals, and either end can initiate them.

The D-BUS Message

D-BUS messages come in three primary forms. These are D-BUS method calls, D-BUS Signals and D-BUS errors. D-BUS signals and D-BUS errors are one-way messages from one end of a D-BUS connection to the other, intended to carry a brief message (such as a signal to start or stop a service, or a notification that an error has occurred in the connection). D-BUS errors are usually generated by the internal D-BUS API itself, though they can be generated by your own code as well.

D-BUS method calls are the bread-and-butter of the D-BUS protocol. The purpose of these calls is to essentially run a method on a remote process and treat it as if it had been run locally. These calls may (or may not) receive replies from the other end of the connection.

D-BUS method calls can be invoked in a blocking or nonblocking method, but within the SSSD we will use the nonblocking approach exclusively (except in unit test binaries, where events should be in serial)

Details of the message specification can be read at http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol

The D-BUS System Bus

The system bus is a special implementation of the D-BUS protocol. It was designed by the freedesktop project to handle communication between the many system daemons. The system bus is an implementation of the D-BUS server that will act as a central routing station for D-BUS communication between services that are registered to it. When using the system bus, a D-BUS client can initiate a connection and then communicate indirectly to other processes also connected to the bus by sending a message with a known destination.

In the SSSD, we do not use the system bus due to the heavy traffic that it sees from the desktop components. Instead we will rely on using the direct connections.

SSSD and D-BUS

In the SSSD, we have implemented a version of the D-BUS protocol that we call the SBUS. The SBUS is built atop libdbus-1 from the freedesktop project, but will implement only a subset of D-BUS features.

SSSD Infrastructure

The SSSD makes use of the event library developed by the Samba project. This event library implements a very robust mainloop for processes.

In order to take advantage of the nonblocking features of the D-BUS server and D-BUS connection, these portions of the D-BUS API must be integrated into the process' mainloop. We have developed a set of SSSD-specific helper functions to simplify this integration. There is a library of SBUS tools located within the "sbus" directory in the SSSD tree.

SBUS Server

The SBUS server will be run on one side or the other of any SSSD process that requires communication from other processes. Some examples of this are the Monitor service (which uses SBUS to verify the availability of the SSSD processes) and the Data Provider (which will listen for cache update requests from NSS, PAM and INFO pipe, as well as serving requests to Data Provider Backends such as FreeIPA)

Instantiating an SBUS server using the SBUS library can be done with the sbus_new_server() helper routine. This call requires a pointer to an event context and a function to properly set up new connections. This helper function will handle the primary duties of setting up a new connection, and then will invoke the function specified by the user. Put more simply, this function describes what to do with a new connection once it's established.

An example from the monitor code is to transmit an identity request to the new connection. Once this request returns, the Monitor will be able to keep track of which of the required services are alive, and which pid they are using.