Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update introspection docs for r6 #340

Merged
merged 1 commit into from
Dec 1, 2023
Merged

Update introspection docs for r6 #340

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions docs/dbus/blockdev.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -323,4 +323,49 @@
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
</property>
</interface>
<interface name="org.storage.stratis3.blockdev.r6">
<!-- Device node of the block device. -->
<property name="Devnode" type="s" access="read">
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
</property>
<!-- Optional hardware id for this block device. -->
<property name="HardwareInfo" type="(bs)" access="read">
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
</property>
<!-- Time that stratisd initialized the block device. -->
<property name="InitializationTime" type="t" access="read">
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
</property>
<!--
Size of the block device's devnode, if different from the size recorded
in the Stratis metadata.
-->
<property name="NewPhysicalSize" type="(bs)" access="read" />
<!--
Physical path of the block device. This may be different from the device
represented by the Devnode property. For example, with encryption, the
PhysicalPath property is the device on which the Stratis LUKS metadata
is written; the Devnode property is the opened device on which the
Stratis metadata is written.
-->
<property name="PhysicalPath" type="s" access="read">
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
</property>
<!-- Object path of the parent pool. -->
<property name="Pool" type="o" access="read">
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
</property>
<!-- Tier the block device occupies, either Data(0) or Cache(1). -->
<property name="Tier" type="q" access="read">
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="false" />
</property>
<!-- Size of the block device's Devnode. -->
<property name="TotalPhysicalSize" type="s" access="read" />
<!-- Optional user-defined string associated with this block device. -->
<property name="UserInfo" type="(bs)" access="readwrite" />
<!-- Stratis UUID of this block device. -->
<property name="Uuid" type="s" access="read">
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
</property>
</interface>
</node>
38 changes: 38 additions & 0 deletions docs/dbus/filesystem.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,4 +242,42 @@
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
</property>
</interface>
<interface name="org.storage.stratis3.filesystem.r6">
<!-- Set the filesystem name. -->
<method name="SetName">
<!-- The new name of the filesystem. -->
<arg name="name" type="s" direction="in" />
<!--
b: True if the name was changed, otherwise false.
s: UUID of the filesystem or a default UUID if no change was made.
-->
<arg name="result" type="(bs)" direction="out" />
<arg name="return_code" type="q" direction="out" />
<arg name="return_string" type="s" direction="out" />
</method>
<!-- Time the filesystem was created. -->
<property name="Created" type="s" access="read">
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
</property>
<!-- Filesystem device node. -->
<property name="Devnode" type="s" access="read">
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="invalidates" />
</property>
<!-- Name of the filesystem. -->
<property name="Name" type="s" access="read" />
<!-- Object path of the parent pool. -->
<property name="Pool" type="o" access="read">
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
</property>
<!-- Logical size of the filesystem. -->
<property name="Size" type="s" access="read" />
<!-- Logical size limit of the filesystem. -->
<property name="SizeLimit" type="(bs)" access="readwrite" />
<!-- Filesystem usage. -->
<property name="Used" type="(bs)" access="read" />
<!-- Filesystem UUID. -->
<property name="Uuid" type="s" access="read">
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
</property>
</interface>
</node>
177 changes: 177 additions & 0 deletions docs/dbus/manager.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -893,6 +893,169 @@
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
</property>
</interface>
<interface name="org.storage.stratis3.Manager.r6">
<!-- Create a single pool with the specified name and blockdevs. -->
<method name="CreatePool">
<!-- Name of the pool. -->
<arg name="name" type="s" direction="in" />
<!-- Device nodes of devices to form the pool -->
<arg name="devices" type="as" direction="in" />
<!-- Optional key description of the key to use to encrypt the pool -->
<arg name="key_desc" type="(bs)" direction="in" />
<!--
Optional Clevis information to use to encrypt the pool.
s: Clevis "pin" specification, "tang" or "tpm".
s: pin-specfic Clevis configuration
-->
<arg name="clevis_info" type="(b(ss))" direction="in" />
<!--
b: True if a pool was created, otherwise false.
(oao): Result of the creation action, default values if no pool
was created.
o: Object path of the created pool.
ao: Object paths of all the block devices in the pool.
-->
<arg name="result" type="(b(oao))" direction="out" />
<arg name="return_code" type="q" direction="out" />
<arg name="return_string" type="s" direction="out" />
</method>
<!-- Destroy the specified pool. -->
<method name="DestroyPool">
<!-- Object path of the pool to destroy. -->
<arg name="pool" type="o" direction="in" />
<!--
b: True if the pool was destroyed, otherwise false.
s: UUID of the pool destroyed or a default value if no action was
taken.
-->
<arg name="result" type="(bs)" direction="out" />
<arg name="return_code" type="q" direction="out" />
<arg name="return_string" type="s" direction="out" />
</method>
<!--
Return JSON representing the internal state of the daemon. The method
signature is stable, but the JSON output format is not guaranteed to be
stable.
-->
<method name="EngineStateReport">
<!-- JSON output representing the engine state. -->
<arg name="result" type="s" direction="out" />
<arg name="return_code" type="q" direction="out" />
<arg name="return_string" type="s" direction="out" />
</method>
<!-- Return a list of the Stratis keys in the kernel keyring. -->
<method name="ListKeys">
<!-- Array of key descriptions. -->
<arg name="result" type="as" direction="out" />
<arg name="return_code" type="q" direction="out" />
<arg name="return_string" type="s" direction="out" />
</method>
<!--
Refresh the state of every running pool instance.
This method is for troubleshooting and debugging only.
-->
<method name="RefreshState">
<arg name="return_code" type="q" direction="out" />
<arg name="return_string" type="s" direction="out" />
</method>
<!-- Set a Stratis key in the kernel keyring. -->
<method name="SetKey">
<!-- Key description to assign to the set key. -->
<arg name="key_desc" type="s" direction="in" />
<!-- File descriptor through which to read the key data. -->
<arg name="key_fd" type="h" direction="in" />
<!--
b: True if the key state was changed, otherwise false.
b: True if the key was newly set in the keyring. False if a key with the
given key description already existed.
-->
<arg name="result" type="(bb)" direction="out" />
<arg name="return_code" type="q" direction="out" />
<arg name="return_string" type="s" direction="out" />
</method>
<!-- Start a pool. -->
<method name="StartPool">
<!-- identifier of pool to be started -->
<arg name="id" type="s" direction="in" />
<!-- id type: "uuid" or "name" -->
<arg name="id_type" type="s" direction="in" />
<!-- Unlock method to use if pool is encrypted
b: True if an unlock method argument is being specified.
s: Method to use to unlock the pool, may be "keyring" or "clevis".
-->
<arg name="unlock_method" type="(bs)" direction="in" />
<!--
b: True if the pool was started, otherwise false.
o: Object path of the started pool.
ao: Array of object paths of block devices belonging to the pool.
ao: Array of object paths of filesystems belonging to the pool.
-->
<arg name="result" type="(b(oaoao))" direction="out" />
<arg name="return_code" type="q" direction="out" />
<arg name="return_string" type="s" direction="out" />
</method>
<!-- Stop a running pool. -->
<method name="StopPool">
<!-- identifier of pool to be stopped -->
<arg name="id" type="s" direction="in" />
<!-- id type: "uuid" or "name" -->
<arg name="id_type" type="s" direction="in" />
<!-- Object path of pool to be stopped. -->
<arg name="pool" type="o" direction="in" />
<!--
b: True if the pool was stopped.
s: UUID of the stopped pool.
-->
<arg name="result" type="(bs)" direction="out" />
<arg name="return_code" type="q" direction="out" />
<arg name="return_string" type="s" direction="out" />
</method>
<!-- Unset a key in the kernel keyring. -->
<method name="UnsetKey">
<!-- Key description of the key to unset. -->
<arg name="key_desc" type="s" direction="in" />
<!-- b: True if the key was in the keyring, otherwise false. -->
<arg name="result" type="b" direction="out" />
<arg name="return_code" type="q" direction="out" />
<arg name="return_string" type="s" direction="out" />
</method>
<!--
a{sa{sv}}: Mapping of Stratis pool UUIDs to information about the
devices associated with the UUID. These sets of devices may comprise
a Stratis pool that can be started with the StartPool message.
s: Stratis pool UUIDs
a{sv}: key/value mapping
s: keys: possible values are "devs", "key_description", "clevis_info"
v: Values for the keys:
"devs": always present, an array of mappings of device information
Contains two keys: "uuid" and "devnode"
"clevis_info": optional, not present if pool is unencrypted.
(bv): information about Clevis configuration for all devices
if b is true:
devices have consistent Clevis information
v = (bs): Clevis configuration information for all devices
b: if false, devices are not encrypted with Clevis
s: Clevis configuration
else:
devices have inconsistent Clevis configurations
v = s: error message explaining inconsistency
"key_description": optional, not present if pool is unencrypted.
(bv): information about kernel key encryption for all devices
if b is true:
devices have consistent key information
v = (bs): key information for all devices
b: if false, devices are not encrypted with a key
s: key description
else:
devices have inconsistent key information
v = s: error message explaining inconsistency
-->
<property name="StoppedPools" type="a{sa{sv}}" access="read" />
<!-- stratisd version -->
<property name="Version" type="s" access="read">
<annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const" />
</property>
</interface>
<!--
The Report interface is an unstable interface for querying internal stratisd
data structure state. It provides reports as JSON, and while the reports can
Expand Down Expand Up @@ -984,6 +1147,20 @@
<arg name="return_string" type="s" direction="out" />
</method>
</interface>
<interface name="org.storage.stratis3.Report.r6">
<!--
This method allows fetching a report by name. If a report by the supplied
name does not exist, an error is returned.
-->
<method name="GetReport">
<!-- Name of the report. -->
<arg name="name" type="s" direction="in" />
<!-- s: Report. -->
<arg name="result" type="s" direction="out" />
<arg name="return_code" type="q" direction="out" />
<arg name="return_string" type="s" direction="out" />
</method>
</interface>
<node name="0" />
<node name="1" />
<node name="2" />
Expand Down
Loading