# D-Bus API Reference ## General Principles ### Objects versus dict/struct/etc There was discussion if it is better to use in API basic types enclosed in data structures or if we should enclose as much as possible data to own objects that have own properties and methods. We see advantages and disadvantages for both approaches. So we decide to: - use simple data for simple data (like list of languages) - for more complex data (like storage configuration) use objects. We can revisit decision in future. For decision if it is simple or complex we decide for rule, that data should contain *only one level of nesting of dict/struct*. So struct of structs or dictionary with dictionaries or structs should be prevented and instead use for that struct or dictionary object. ### Localization We also discuss aproach how to solve localization of some strings like language human names, error messages from some scripts or strings from libraries. Setting locale for whole service is basically discouraged as there can be multiple clients working with given service, e.g. some log collector beside user doing setup. So we decided for now to - have properties in English - when locale is needed then a dedicated call to get localized strings together with locale should be used. Methods that can return localized error states should be able to get as option requested locale. ### Resources We use these resources to get more familiar with D-Bus API designing. - D-Bus API design guidelines https://dbus.freedesktop.org/doc/dbus-api-design.html - PackageKit design https://www.freedesktop.org/software/PackageKit/gtk-doc/api-reference.html - udisks design http://storaged.org/doc/udisks2-api/2.6.4/ch02.html - network manager design https://people.freedesktop.org/~lkundrak/nm-docs/spec.html - anakonda D-Bus API ( spread in `*_interface.py` files https://github.com/rhinstaller/anaconda/tree/master/pyanaconda/modules ## Language Iface: o.o.YaST.Installer1.Language #### methods: - ToInstall(array(string LangId)) -> void Set list of languages to install Example: ToInstall(["cs_CZ", "de_DE"]) -> () # only lang codes from AvailableLanguages is supported #### Properties (all read only): - AvailableLanguages -> array(struct(string LangId, string LangLabel, dict(string, variant) details)) List of all available languages to install on target system. Example: AvailableLanguages -> [["cs_CZ", "Czech", {}]] # it is lang code, human readable lang name and dict for future extensions to provide more data - MarkedForInstall -> array(string LangId) List of languages to install. Same format as ToInstall #### Signals: - PropertiesChanged ( only standard one from org.freedesktop.DBus.Properties interface ) notes: identifiers: maybe LanguageTag https://www.rubydoc.info/github/yast/yast-packager/master/LanguageTag - move it to yast-yast2 - link to the standard from yard - see https://tools.ietf.org/html/rfc4647 Matching of Language Tags - see https://lists.opensuse.org/archives/list/yast-devel@lists.opensuse.org/message/D52PSZ7TRID2RVM6CE6K2C2RUNNGOS6Z/ ## Base Product Iface: o.o.YaST.Installer1.Software #### methods: - SelectProduct(string ProductId) -> void Select product for installation. TODO: do we need version or arch or any other parameter? should we add generic dict(sv) to it? Example: InstallProduct("SLES") -> () # only name from available BaseProducts is supported #### Properties (all read only): - AvailableBaseProducts -> array(struct(string ProductId, string ProductLabel, dict(string, variant) details)) List of all available base product to install on target system. Note: List is sorted according to defined display order Example: AvailableBaseProducts -> [["SLES", "SUSE Linux Enterprise Server", {}]] # it is product name, human readable name and dict for future extensions to provide more data - SelectedBaseProduct -> string ProductId Base product selected for installation. It is always defined. Example: SelectedBaseProduct -> "SLES" # only name from available BaseProducts is supported #### Signals: - PropertiesChanged ( only standard one from org.freedesktop.DBus.Properties interface ) ## `org.opensuse.DInstaller.Storage` Service Service for managing storage devices. ### Overview ~~~ /DInstaller/Storage1 .ObjectManager .DInstaller.ServiceStatus1 .DInstaller.Progress1 .DInstaller.Validation1 .DInstaller.Storage1 .DInstaller.Storage1.Proposal.Calculator .DInstaller.Storage1.ISCSI.Initiator .DInstaller.Storage1.DASD.Manager (Only available on s390 systems) /DInstaller/Storage1/Proposal .DInstaller.Storage1.Proposal /DInstaller/Storage1/iscsi_nodes/[0-9]+ .DInstaller.Storage1.ISCSI.Node /DInstaller/Storage1/dasds/[0-9]+ (Only available on s390 systems) .DInstaller.Storage1.DASD.device ~~~ ### D-Bus Objects #### `/org/opensuse/DInstaller/Storage1` Object ~~~ /DInstaller/Storage1 .ObjectManager .DInstaller.ServiceStatus1 .DInstaller.Progress1 .DInstaller.Validation1 .DInstaller.Storage1 .DInstaller.Storage1.Proposal.Calculator .DInstaller.Storage1.ISCSI.Initiator .DInstaller.Storage1.DASD.manager ~~~ Main object exported by the service `org.opensuse.DInstaller.Service`. This object implements the `org.freedesktop.DBus.ObjectManager` interface and should be used by clients to discover other objects. This object also implements generic interfaces to manage the service status, progress and validation. Moreover, it implements interfaces to manipulate the global state (perform installation, create proposals, login sessions for iSCSI nodes, etc). #### `/org/opensuse/DInstaller/Storage1/Proposal` Object ~~~ /DInstaller/Storage1/Proposal .DInstaller.Storage1.Proposal ~~~ This object is exported only if a proposal was already calculated (successful or not). It can be used to inspect the result of the calculated proposal. #### `/org/opensuse/DInstaller/Storage1/iscsi_nodes/[0-9]+` Objects ~~~ /DInstaller/Storage1/iscsi_nodes/[0-9]+ .DInstaller.Storage1.ISCSI.Node ~~~ Objects representing iSCSI nodes are dynamically exported when a successful iSCSI discovery is performed, see `.org.opensuse.DInstaller.Storage1.ISCSI.Initiator` interface. #### `/org/opensuse/DInstaller/Storage1/dasds/[0-9]+` Objects ~~~ /DInstaller/Storage1/dasds/[0-9]+ .DInstaller.Storage1.DASD.Device ~~~ Objects representing DASDs are dynamically exported when a successful probing is performed by the `DASD.manager` interface of the main storage object, see `.org.opensuse.DInstaller.Storage1.DASD.manager`. ### D-Bus Interfaces #### `org.opensuse.DInstaller.Storage1` Interface Offers methods for performing general installation actions. ##### Methods ~~~ Probe() Install() Finish() ~~~ #### `org.opensuse.DInstaller.Storage1.Proposal.Calculator` Interface Allows creating a storage proposal. ##### Methods ~~~ Calculate(in a{sv} settings, out u result) ~~~ ##### Properties ~~~ AvailableDevices readable a(ssa{sv}) VolumeTemplates readable aa{sv} Result readable o ~~~ ##### Details ###### `Calculate` method ~~~ Calculate(in a{sv} settings, out u result) ~~~ Calculates a new proposal with the given settings. A proposal object is exported when the proposal is calculated. Arguments: * `in a{sv} settings`: Allowed settings correspond to the properties defined by `org.opensuse.DInstaller.Storage1.Proposal` interface. * `out u result`: `0` on success and `1` on failure. ###### `AvailableDevices` Property ~~~ AvailableDevices readable a(ssa{sv}) ~~~ Array in which each element has a device name, description, and extra data. Example: `1 "/dev/sda" "/dev/sda, 8.00 GiB, USB" 0` Extra data is not used yet. ###### `VolumeTemplates` Property ~~~ VolumeTemplates readable aa{sv} ~~~ Templates that can be used as starting point for the volumes of a new proposal. See `Volumes` property from `org.opensuse.DInstaller.Storage1.Proposal` interface. ###### `Result` Property ~~~ Result readable o ~~~ Path of the object with the proposal result, typically `/org/opensuse/DInstaller/Storage1/Proposal`. If there is no proposal exported yet, then the path points to root `/`. #### `org.opensuse.DInstaller.Storage1.Proposal` Interface Information about the calculated storage proposal. ##### Properties ~~~ CandidateDevices readable as LVM readable b EncryptionPassword readable s Volumes readable aa{sv} Actions readable aa{sv} ~~~ ##### Details ###### `Volumes` Property ~~~ Volumes readable aa{sv} ~~~ List of volumes used for calculating the proposal. Each volume is defined by the following properties: ~~~ DeviceType s Optional b Encrypted b MountPoint s FixedSizeLimits b AdaptiveSizes b MinSize x MaxSize x FsTypes as FsType s Snapshots b SnapshotsConfigurable b SnapshotsAffectSizes b SizeRelevantVolumes as ~~~ Example: ~~~ 1 14 DeviceType s "partition" Optional b false Encrypted b false MountPoint s / FixedSizeLimit b false AdaptiveSizes b false MinSize x 1024 MaxSize x 2048 FsTypes as 3 Btrfs XFS EXT4 FsType Btrfs Snapshots b true SnapshotsConfigurable b true SnapshotsAffectSizes b false VolumeWithFallbackSizes as 1 /home ~~~ ###### `Actions` Property ~~~ Actions readable aa{sv} ~~~ Actions to perform in the system to create the proposal. If the proposal failed, then the list of actions is empty. Each action is defined by the following properties: ~~~ Text readable s Subvol readable b Delete readable b ~~~ Example: ~~~ 2 3 Text s "Create partition /dev/vdb1" Subvol b false Delete b false 3 Text s "Delete Btrfs subvolume @/var" Subvol b true Delete b true ~~~ #### `org.opensuse.DInstaller.Storage1.ISCSI.Initiator` Interface Provides methods for configuring iSCSI initiator and for discovering nodes. ##### Methods ~~~ Discover(in s address, in u port, in a{sv} options, out u result) Delete(in o iscsi_node_path, out u result) ~~~ ##### Properties ~~~ InitiatorName readable,writable s ~~~ ##### Details ###### `Discover` Method ~~~ Discover(in s address, in u port, in a{sv} options, out u result) ~~~ Performs nodes discovery. Discovered nodes are exported with the path `/org/opensuse/DInstaller/iscsi_nodes/[0-9]+`. Arguments: * `in s address`: IP address of the iSCSI server. * `in u port`: Port of the iSCSI server. * `in a{sv} options`: * `Username s`: Username for authentication by target. * `Password s`: Password for authentication by target. * `ReverseUsername s`: Username for authentication by initiator. * `ReversePassword s`: Password for authentication by initiator. * `out u result`: `0` on success and `1` on failure. ##### `Delete` Method ~~~ Delete(in o iscsi_node_path, out u result) ~~~ Deletes a discovered iSCSI node. The iSCSI node object is unexported. Note that connected nodes cannot be deleted. Arguments: * `in o iscsi_node_path`: Path of the iSCSI node to delete. * `out u result`: `0` on success and `1` on failure if the given node is not exported, `2` on failure because any other reason. #### `org.opensuse.DInstaller.Storage1.ISCSI.Node` Interface This interface is implemented by objects exported at `/org/opensuse/DInstaller/Storage1/iscsi_nodes/[0-9]+` path. It provides information about an iSCSI node and allows to perform login and logout. ##### Methods ~~~ Login(in a{sv} options, out u result) Logout(out u result) ~~~ ##### Properties ~~~ Target readable s Address readable s Port readable u Interface readable s IBFT readable b Connected readable b Startup readable,writable s ~~~ ##### Details ###### `Login` Method ~~~ Login(in a{sv} options, out u result) ~~~ Creates an iSCSI session. If the session is created, the corresponding object at the path `/org/opensuse/DInstaller/Storage1/iscsi_nodes/[0-9]+` is updated. Arguments: * `in a{sv} options`: * `Username s`: Username for authentication by target. * `Password s`: Password for authentication by target. * `ReverseUsername s`: Username for authentication by initiator. * `ReversePassword s`: Password for authentication by initiator. * `Startup s`: startup mode (`manual`, `onboot`, `automatic`). * `out u result`: `0` on success, `1` on failure if the given startup value is not valid, and `2` on failure because any other reason. ###### `Logout` Method ~~~ Logout(out u result) ~~~ Closes an iSCSI session. Arguments: * `out u result`: `0` on success and `1` on failure. #### `org.opensuse.DInstaller.Storage1.DASD.Manager` Interface Provides methods for configuring DASDs. It's only available if the D-Bus service is running on a s390x system. ##### A Note About DIAG and YaST The `use_diag` flag of a given DASD controls whether it should use the DIAG access method. Traditionally YaST has managed that flag in a way that may be confusing to newcomers. Nevertheless, for the sake of consistency and easy transition (and also to reuse some YaST components without modifications) D-Installer observes that YaST approach. In a nutshell: - When the list of DASDs is read from the system (see method `Probe()`), the value of the `use_diag` flag for enabled devices is checked from the system and exported with the proper value in the D-Bus representation of the DASD. But for disabled DASDs, the value of the flag is always assumed to be false. - When the value of the `use_diag` flag is changed for an enabled device using the D-Bus interface (see method `SetDiag()`), the change is applied immediately to the system, disabling the device and enabling it again with the new access method. - When the value of the flag is changed for a disabled device, the flag is updated in the D-Bus representation of the DASD but not written to the system configuration. The change will only have effect in the system if the device is enabled afterwards using the `Enable()` method. The change is lost if `Probe()` is called again without having enabled the device. ##### Methods ~~~ Probe() Enable(in ao devices, out u result) Disable(in ao devices, out u result) SetDiag(in ao devices, in b diag, out u result) ~~~ In addition, a `Format()` method is provided, but it's not documented here because it's going to change heavily in the short term. ##### Details ###### `Probe` Method Finds DASDs in the system. Found DASDs are exported with the path `/org/opensuse/DInstaller/Storage1/dasds/[0-9]+`. ###### `Enable` Method ~~~ Enable(in ao devices, out u result) ~~~ Enables the given list of DASDs. See documentation above to understand how the `use_diag` flag of the DASDs is affected by this method. Arguments: * `in ao devices`: paths of the D-Bus objects representing the DASDs to enable. * `out u result`: `0` if all DASDs are successfully enabled. `1` if any of the given paths is invalid (ie. it does not correspond to a known DASD), `2` in case of any other error. ###### `Disable` Method ~~~ Disable(in ao devices, out u result) ~~~ Disables the given list of DASDs. Arguments: * `in ao devices`: paths of the D-Bus objects representing the DASDs to disable. * `out u result`: `0` if all DASDs are successfully disabled. `1` if any of the given paths is invalid (ie. it does not correspond to a known DASD), `2` in case of any other error. ###### `SetDiag` Method ~~~ SetDiag(in ao devices, in b diag, out u result) ~~~ Sets the `use_diag` attribute for the given DASDs to the given value. See documentation above to understand what setting the flag really means (since this follows the same convention than YaST). Arguments: * `in ao devices`: paths of the D-Bus objects representing the DASDs to configure. * `in b diag`: new value for the flag. * `out u result`: `0` if `use_diag` is correctly set for all the requested DASDs. `1` if any of the given paths is invalid (ie. it does not correspond to a known DASD), `2` in case of any other error. #### `org.opensuse.DInstaller.Storage1.DASD.Device` Interface This interface is implemented by objects exported at the `/org/opensuse/DInstaller/Storage1/dasds/[0-9]+` paths. It provides information about a DASD in the system. ##### Properties ~~~ Id readable s Enabled readable b DeviceName readable s Formatted readable b Diag readable b Type readable s AccessType readable s PartitionInfo readable s ~~~ Bear in mind these properties are a quite direct translation of the attributes read and exposed by YaST. Some changes may be introduced in the future to make them easier to consume (eg. the current string `AccessType` could be replaced by a boolean `ReadOnly`). * `Id`: The device channel id (eg. "0.0.0150") * `Enabled`: Whether the device is enabled. * `DeviceName`: Device name of the DASD in the linux system (eg. "/dev/dasda"). Empty string if the device is not enabled. * `Formatted`: whether the device is formatted. * `Diag`: Whether the DIAG access method is used (or will be used when the device is enabled). * `Type`: The DASD type (eg. EKCD or FBA). * `AccessType`: Empty string if unknown. Either "rw" or "ro" otherwise. * `PartitionInfo`: Partition names (and sometimes their type) separated by commas. Eg. "_/dev/dasda1 (Linux native), /dev/dasda2 (Linux native)_". Empty if the information is unknown. ## Users ### iface o.o.Installer1.Users #### methods: - SetRootPassword(string value, boolean encrypted) -> void sets root password. If encrypted is set to true, it means that already encrypted password is send. example: SetRootPassword("test", false) -> () - SetRootSSHKey(string value) -> void set root ssh public keys. Use empty string to unset it. example: SetRootSSHKey("idrsa long key") -> () - SetFirstUser(string FullName, string UserName, string Password, boolean AutoLogin, map AdditionalData) -> void sets one non root user after installation. FullName and UserName has to follow restrictions for respective passwd entry. To unset it use empty UserName. example: SetRootSSHKey("idrsa long key") -> () #### Properties (all read only): - RootPasswordSet -> boolean whenever root password will be set by installer - RootSSHKey -> string root public ssh key that can be used to login to machine Can be empty which means not set - FirstUser -> struct( string FullName, string UserName, string Password, boolean AutoLogin, map AdditionalData) info about first user to set. if Username is empty, it means not set and other values can be ignored ## Questions D-Installers offers a mechanism to communicate with clients. The D-Bus service exports a *Questions* object that implements the *org.freedesktop.DBus.ObjectManager* interface. Individual questions are dynamically exported in a tree under the */org/opensuse/DInstaller/Questions1* path, for example: ~~~ /org/opensuse/DInstaller/Questions1 /org/opensuse/DInstaller/Questions1/1 /org/opensuse/DInstaller/Questions1/2 /org/opensuse/DInstaller/Questions1/4 ~~~ Each D-Bus question implements its own set of interfaces, depending on the type of question. For example, a generic question implements *org.opensuse.DInstaller.Question1*. And a question asking for the activation of a LUKS device also implements *org.opensuse.DInstaller.Question.LuksActivation1*. Questions can be "unexported" from the ObjectManager tree. The service typically unexports a question when the question is answered. ### org.opensuse.DInstaller.Question1 #### Properties - Id -> unsigned 32-bit integer (r) Question id. The question is exported at *root_path/id*. - Text -> string (r) Text of the question. Clients show this text to the users. - Options -> array(string) (r) Options for answering the question. The question only admits an option from the list as valid answer. - DefaultOption -> string (r) Clients should offer this option as default option for answering the question. - Answer -> string (rw) Answer for the question. Clients set an option as answer. ### org.opensuse.DInstaller.Question.LuksActivation1 #### Properties - Password -> string (rw) Password provided to decrypt a LUKS device. - Attempt -> unsigned 32-bit integer (r) Current attempt to decrypt the device. This value is useful for clients to know if the very same question is asked again (i.e., when the provided password did not work). ## ServiceStatus Each service will have an status (*idle* or *busy*). The service should change its status to *busy* when it is going to start an expensive tasks. The status should be set back to *idle* once the long task is done. The main object of a service implements the following interface: ### org.opensuse.DInstaller.ServiceStatus1 #### Properties - All -> array(array(dict(string, variant))) (r) All possible statuses: ~~~ [ {"id" => 0, "label" => "idle"}, {"id" => 1, "label" => "busy"} ] ~~~ - Current -> unsigned 32-bit integer (r) Id of the current status. ## Progress The main object of a service implements the following interface: ### org.opensuse.DInstaller.Progress1 - TotalSteps: unsigned 32-bit integer (r) Number of steps. - CurrentStep: struct(unsigned 32-bit integer, string) (r) Number of the current step and its description. - Finished: b (r) Whether the progress has finished. ## Validation The main object of a service may implement the validation interface. It reports any issue that might block the installation. ### org.opensuse.DInstaller.Validation1 - Errors: array of strings (as) List of validation errors. - Valid: boolean (b) Whether there are validation errors. It is a way to check whether a service is ready for installation without having to retrieve the list of errors. ## Manager ### Installation Phases The installation process follows a set of phases. Only the main service (`DInstaller::Manager`) knows the information about the current installation phase. The rest of services will act as utility services without any knowledge about the whole installation process. A client (e.g., a web UI) will ask to the main service for the current phase of the installation. In principle, the installation will follow 3 possible phases: *Startup*, *Config* and *Install*. * *Startup* Phase This is the initial phase. The manager service will start in this phase and it will not change to another phase until the client asks for performing the next phase. * *Config* Phase The installation is configured during this phase. Configuring the installation means that everything needed from the system is read and the required default proposal are calculated. In YaST terms, the *config* phase implies to probe some modules like storage, language, etc, and to perform their proposals. Note that not all modules have to be probed/proposed. Probing some modules could be delayed to the next *install* phase. * *Install* Phase This phase implies to perform everything to install the system according to the selected options and proposals. Note that this phase is not only a typical YaST commit. For example, some proposals (software?) could be done during this phase. In short, at the beginning of this phase we have all the required information to perform the installation, and at the end of the phase the system is installed. ### Status of the Services Note that the services are blocked meanwhile they are performing a long task. For this reason, the *manager* service will store the status of each service and the clients will ask to *manager* to know that status. ### org.opensuse.DInstaller.Manager1 #### Properties - InstallationPhases -> array(array(dict(string, variant))) (r) All possible phases: ~~~ [ {"id" => 0, "label" => "startup"}, {"id" => 1, "label" => "config"}, {"id" => 2, "label" => "install"} ] ~~~ - CurrentInstallationPhase -> unsigned 32-bit integer (r) Id of the current phase. - BusyServices -> a(s) (r) List of names of the currently busy services.