Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- docs/drvsecret.html.in | 82 ------------------------------------------ docs/drvsecret.rst | 65 +++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 66 insertions(+), 83 deletions(-) delete mode 100644 docs/drvsecret.html.in create mode 100644 docs/drvsecret.rst diff --git a/docs/drvsecret.html.in b/docs/drvsecret.html.in deleted file mode 100644 index 1bd7d75215..0000000000 --- a/docs/drvsecret.html.in +++ /dev/null @@ -1,82 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml";> - <body> - <h1>Secret information management</h1> - - <p> - The secrets driver in libvirt provides a simple interface for - storing and retrieving secret information. - </p> - - <h2><a id="uris">Connections to SECRET driver</a></h2> - - <p> - The libvirt SECRET driver is a multi-instance driver, providing a single - system wide privileged driver (the "system" instance), and per-user - unprivileged drivers (the "session" instance). A connection to the secret - driver is automatically available when opening a connection to one of the - stateful primary hypervisor drivers. It is none the less also possible to - explicitly open just the secret driver, using the URI protocol "secret" - Some example connection URIs for the driver are: - </p> - -<pre> -secret:///session (local access to per-user instance) -secret+unix:///session (local access to per-user instance) - -secret:///system (local access to system instance) -secret+unix:///system (local access to system instance) -secret://example.com/system (remote access, TLS/x509) -secret+tcp://example.com/system (remote access, SASl/Kerberos) -secret+ssh://root@xxxxxxxxxxx/system (remote access, SSH tunnelled) -</pre> - - <h3><a id="uriembedded">Embedded driver</a></h3> - - <p> - Since 6.1.0 the secret driver has experimental support for operating - in an embedded mode. In this scenario, rather than connecting to - the libvirtd daemon, the secret driver runs in the client application - process directly. To open the driver in embedded mode the app use the - new URI path and specify a virtual root directory under which the - driver will create content. - </p> - - <pre> - secret:///embed?root=/some/dir - </pre> - - <p> - Under the specified root directory the following locations will - be used - </p> - - <pre> -/some/dir - | - +- etc - | | - | +- secrets - | - +- run - | - +- secrets - </pre> - - <p> - The application is responsible for recursively purging the contents - of this directory tree once they no longer require a connection, - though it can also be left intact for reuse when opening a future - connection. - </p> - - <p> - The range of functionality is intended to be on a par with that - seen when using the traditional system or session libvirt connections - to QEMU. Normal practice would be to open the secret driver in embedded - mode any time one of the other drivers is opened in embedded mode so - that the two drivers can interact in-process. - </p> - </body> -</html> diff --git a/docs/drvsecret.rst b/docs/drvsecret.rst new file mode 100644 index 0000000000..76a9097d2b --- /dev/null +++ b/docs/drvsecret.rst @@ -0,0 +1,65 @@ +============================= +Secret information management +============================= + +The secrets driver in libvirt provides a simple interface for storing and +retrieving secret information. + +Connections to SECRET driver +---------------------------- + +The libvirt SECRET driver is a multi-instance driver, providing a single system +wide privileged driver (the "system" instance), and per-user unprivileged +drivers (the "session" instance). A connection to the secret driver is +automatically available when opening a connection to one of the stateful primary +hypervisor drivers. It is none the less also possible to explicitly open just +the secret driver, using the URI protocol "secret" Some example connection URIs +for the driver are: + +:: + + secret:///session (local access to per-user instance) + secret+unix:///session (local access to per-user instance) + + secret:///system (local access to system instance) + secret+unix:///system (local access to system instance) + secret://example.com/system (remote access, TLS/x509) + secret+tcp://example.com/system (remote access, SASl/Kerberos) + secret+ssh://root@xxxxxxxxxxx/system (remote access, SSH tunnelled) + +Embedded driver +~~~~~~~~~~~~~~~ + +Since 6.1.0 the secret driver has experimental support for operating in an +embedded mode. In this scenario, rather than connecting to the libvirtd daemon, +the secret driver runs in the client application process directly. To open the +driver in embedded mode the app use the new URI path and specify a virtual root +directory under which the driver will create content. + +:: + + secret:///embed?root=/some/dir + +Under the specified root directory the following locations will be used + +:: + + /some/dir + | + +- etc + | | + | +- secrets + | + +- run + | + +- secrets + +The application is responsible for recursively purging the contents of this +directory tree once they no longer require a connection, though it can also be +left intact for reuse when opening a future connection. + +The range of functionality is intended to be on a par with that seen when using +the traditional system or session libvirt connections to QEMU. Normal practice +would be to open the secret driver in embedded mode any time one of the other +drivers is opened in embedded mode so that the two drivers can interact +in-process. diff --git a/docs/meson.build b/docs/meson.build index d936091091..8499b3d595 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -22,7 +22,6 @@ docs_html_in_files = [ 'csharp', 'dbus', 'docs', - 'drvsecret', 'drvtest', 'drvvbox', 'drvvirtuozzo', @@ -81,6 +80,7 @@ docs_rst_files = [ 'drvnodedev', 'drvopenvz', 'drvqemu', + 'drvsecret', 'errors', 'formatbackup', 'formatcheckpoint', -- 2.35.1
