From nobody Mon Feb 9 09:47:20 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1648469531; cv=none; d=zohomail.com; s=zohoarc; b=Kt/jY5qMKwKGzAoz6am0GE6VNCcRBoxNVvRZHwF/cdn7zHlSWFDO8hzueukJNjCHnmTkSbtDUNHUJpd/6Et8eHwEZ5CU3vg3VFL2o5uix2SjBCcT+PSCSjhjXkaSFzy4cGbNvCRGMey57vLEgQxdGHAJqmnCNYrluu6IwT6WAO8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1648469531; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=DKTD9UkhF33wUm8pxMAhjyuLxe9rNn5VDtvn7qQpzIs=; b=mCZPjInnnWutm5Nx8fD7gIxZ8KCXq6JcslDhHOdicJ+yN9H6IaHVr3nLCbCHzazp49j6fRCVh8dNPitq7fV7MQAmWXsLFC3LN78uM55u6GIB3906KqRfdXENXI7w0k/AEuHdujjPayU+YhHNBJACK0Ct/BIufru5x/7e2sz2SJs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1648469531786278.0169665162488; Mon, 28 Mar 2022 05:12:11 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-272-k1oMn1JiMzSKsCz30duzfw-1; Mon, 28 Mar 2022 08:11:02 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 5EEC13C1484D; Mon, 28 Mar 2022 12:10:59 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 4AD0040CFD11; Mon, 28 Mar 2022 12:10:59 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id ABE54193F6D9; Mon, 28 Mar 2022 12:10:58 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 39458193F6E1 for ; Mon, 28 Mar 2022 12:10:56 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 1DCE81400B19; Mon, 28 Mar 2022 12:10:56 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 99D9B1427AE4 for ; Mon, 28 Mar 2022 12:10:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1648469530; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=DKTD9UkhF33wUm8pxMAhjyuLxe9rNn5VDtvn7qQpzIs=; b=jSqOhgll83kYn6LLVMkbwTHVyFLDYb3aUrZoDMy4bVovG07OZFB8iytWicUjU0riUBvRg0 f2q4r3o8iIZhwtCGEKw+O6k/nWA1MDtErHJotcLBimyrD4dHdLiu1U1OB9AmA9GbQ1ZicG bdLqL6Aze3Z28HAw9N8KigSd2BMI+UQ= X-MC-Unique: k1oMn1JiMzSKsCz30duzfw-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 09/29] docs: Convert 'drvsecret' page to rST Date: Mon, 28 Mar 2022 14:10:24 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1648469532834100005 Content-Type: text/plain; charset="utf-8"; x-default="true" Signed-off-by: Peter Krempa Reviewed-by: Erik Skultety --- 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 @@ - - - - -

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 sing= le - system wide privileged driver (the "system" instance), and per-user - unprivileged drivers (the "session" instance). A connection to the sec= ret - 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@example.com/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=3D/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 embed= ded - 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/drvsecret.rst b/docs/drvsecret.rst new file mode 100644 index 0000000000..76a9097d2b --- /dev/null +++ b/docs/drvsecret.rst @@ -0,0 +1,65 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D +Secret information management +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D + +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 s= ystem +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 p= rimary +hypervisor drivers. It is none the less also possible to explicitly open j= ust +the secret driver, using the URI protocol "secret" Some example connection= URIs +for the driver are: + +:: + + secret:///session (local access to per-user instan= ce) + secret+unix:///session (local access to per-user instan= ce) + + 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@example.com/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 da= emon, +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=3D/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 als= o 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 prac= tice +would be to open the secret driver in embedded mode any time one of the ot= her +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 =3D [ 'csharp', 'dbus', 'docs', - 'drvsecret', 'drvtest', 'drvvbox', 'drvvirtuozzo', @@ -81,6 +80,7 @@ docs_rst_files =3D [ 'drvnodedev', 'drvopenvz', 'drvqemu', + 'drvsecret', 'errors', 'formatbackup', 'formatcheckpoint', --=20 2.35.1