Re: [libvirt] [PATCH 4/4] docs: secret: Unify and sanitize examples on how to set secret value

Discourage passing secrets as commandline arguments. Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- docs/formatsecret.html.in | 86 +++++++++++++++++++++++++-------------- 1 file changed, 55 insertions(+), 31 deletions(-) diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in index 8f5383cf64..61a8396682 100644 --- a/docs/formatsecret.html.in +++ b/docs/formatsecret.html.in @@ -76,13 +76,13 @@ <pre> # virsh secret-define volume-secret.xml Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created -# -# MYSECRET=`printf %s "open sesame" | base64` -# virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET -Secret value set -# </pre> + <p> + See <a href="#settingSecrets">virsh secret-set-value</a> on how + to set the value of the secret. + </p> + <p> The volume type secret can be supplied either in volume XML during creation of a <a href="formatstorage.html#StorageVol">storage volume</a> @@ -103,12 +103,11 @@ Secret value set # virsh secret-define luks-secret.xml Secret f52a81b2-424e-490c-823d-6bd4235bc57 created -# -# MYSECRET=`printf %s "letmein" | base64` -# virsh secret-set-value f52a81b2-424e-490c-823d-6bd4235bc57 $MYSECRET -Secret value set -# </pre> + <p> + See <a href="#settingSecrets">virsh secret-set-value</a> on how + to set the value of the secret. + </p> <p> The volume type secret can be supplied in domain XML for a luks storage @@ -156,13 +155,11 @@ Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created UUID Usage ----------------------------------------------------------- 1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example -# -# CEPHPHRASE=`printf %s "pass phrase" | base64` -# virsh secret-set-value 1b40a534-8301-45d5-b1aa-11894ebb1735 $CEPHPHRASE -Secret value set - -# </pre> + <p> + See <a href="#settingSecrets">virsh secret-set-value</a> on how + to set the value of the secret. + </p> <p> The ceph secret can then be used by UUID or by the @@ -229,7 +226,9 @@ incominguser myname mysecret <p> Next, use <code>virsh secret-define iscsi-secret.xml</code> to define - the secret and <code>virsh secret-set-value</code> using the generated + the secret and + <code><a href="#settingSecrets">virsh secret-set-value</a></code> + using the generated UUID value and a base64 generated secret value in order to define the chosen secret pass phrase. The pass phrase must match the password used in the iSCSI authentication configuration file. @@ -243,12 +242,13 @@ Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created ----------------------------------------------------------- c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi -# MYSECRET=`printf %s "mysecret" | base64` -# virsh secret-set-value c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 $MYSECRET -Secret value set -# </pre> + <p> + See <a href="#settingSecrets">virsh secret-set-value</a> on how + to set the value of the secret. + </p> + <p> The iSCSI secret can then be used by UUID or by the usage name via the <code>&lt;auth&gt;</code> element in a domain's @@ -313,19 +313,13 @@ Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created Once the secret is defined, a secret value will need to be set. The secret would be the passphrase used to access the TLS credentials. The following is a simple example of using - <code>virsh secret-set-value</code> to set the secret value. The + <code><a href="#settingSecrets">virsh secret-set-value</a></code> to set + the secret value. The <a href="html/libvirt-libvirt-secret.html#virSecretSetValue"> <code>virSecretSetValue</code></a> API may also be used to set a more secure secret without using printable/readable characters. </p> - <pre> -# MYSECRET=`printf %s "letmein" | base64` -# virsh secret-set-value 718c71bd-67b5-4a2b-87ec-a24e8ca200dc $MYSECRET -Secret value set - - </pre> - <h3><a id="vTPMUsageType">Usage type "vtpm"</a></h3> <p> @@ -370,17 +364,47 @@ Secret 6dd3e4a5-1d76-44ce-961f-f119f5aad935 created Once the secret is defined, a secret value will need to be set. The secret would be the passphrase used to decrypt the vTPM state. The following is a simple example of using - <code>virsh secret-set-value</code> to set the secret value. The + <code><a href="#settingSecrets">virsh secret-set-value</a></code> + to set the secret value. The <a href="html/libvirt-libvirt-secret.html#virSecretSetValue"> <code>virSecretSetValue</code></a> API may also be used to set a more secure secret without using printable/readable characters. </p> + <h2><a id="settingSecrets">Setting secret values in virsh</a></h2> + + <p> + To set the value of the secret you can use the following virsh commands. + If the secret is a password-like string (printable characters, no newline) + you can use: + </p> + <pre> +# virsh secret-passwd 6dd3e4a5-1d76-44ce-961f-f119f5aad935 +Enter new value for secret: +Secret value set + </pre> + + <p> + Another secure option is to read the secret from a file. This way the + secret can contain any bytes (even NUL and non-printable characters). The + length of the secret is the length of the input file. + </p> + + <pre> +# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 --file secretinfile +Secret value set + </pre> + + <p> + The secret can also be set via an argument, but note that other users + may see it in the process listing output. The secret must be base64 + encoded. + </p>