[libvirt] [PATCH] docs: Add docs for new extra parameter pkipath
* docs/remote.html.in --- docs/remote.html.in | 30 ++++++++++++++++++++++++++++++ 1 files changed, 30 insertions(+), 0 deletions(-) diff --git a/docs/remote.html.in b/docs/remote.html.in index b0fdb7c..a68d0fa 100644 --- a/docs/remote.html.in +++ b/docs/remote.html.in @@ -308,6 +308,22 @@ Note that parameter values must be <td colspan="2"/> <td> Example: <code>no_tty=1</code> </td> </tr> + <tr> + <td> + <code>pkipath</code> + </td> + <td> tls</td> + <td> + Specifies x509 certificates path for client. As long as one of the + certificates (CA cerfificate, client key, client certificate) doesn't + exist in the specified path, the connection will fail with fatal + error. +</td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>pkipath=/tmp/pki/client</code> </td> + </tr> </table> <h3> <a name="Remote_certificates">Generating TLS certificates</a> @@ -372,6 +388,20 @@ next section. </td> </tr> </table> + <p> +If 'pkipath' is specified in URI, then all the client certificates should +be able to found in the path specified, otherwise, connection will fail +with fatal error. And if 'pkipath' is not specified: +</p> + <ul> + <li> For user who is non-root, libvirt trys to find the certificates +in $HOME/.pki/libvirt, if one of the required certificates can not be found, +global default locations(/etc/pki/CA/cacert.pem, +/etc/pki/libvirt/private/clientkey, /etc/pki/libvirt/clientcert.pem) will be +used. +</li> + <li> For user who is root, global default location will be used. </li> + </ul> <h4> <a name="Remote_TLS_background">Background to TLS certificates</a> </h4> -- 1.7.3.2
On 27/01/2011, at 8:01 PM, Osier Yang wrote:
* docs/remote.html.in --- docs/remote.html.in | 30 ++++++++++++++++++++++++++++++ 1 files changed, 30 insertions(+), 0 deletions(-)
diff --git a/docs/remote.html.in b/docs/remote.html.in index b0fdb7c..a68d0fa 100644 --- a/docs/remote.html.in +++ b/docs/remote.html.in @@ -308,6 +308,22 @@ Note that parameter values must be <td colspan="2"/> <td> Example: <code>no_tty=1</code> </td> </tr> + <tr> + <td> + <code>pkipath</code> + </td> + <td> tls</td> + <td> + Specifies x509 certificates path for client. As long as one of the + certificates (CA cerfificate, client key, client certificate) doesn't + exist in the specified path, the connection will fail with fatal + error.
Typo. The "certificate" after the CA is misspelled. ("f" instead of "t" in it). The wording for this paragraph could probably be tweaked a bit anyway. How about something like: Specifies the x509 certificates path for the client. If any of the CA certificate, client certificate, or client key are missing, the connection will fair with a fatal error.
+</td>
Indentation is off?
+ </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>pkipath=/tmp/pki/client</code> </td> + </tr> </table> <h3> <a name="Remote_certificates">Generating TLS certificates</a> @@ -372,6 +388,20 @@ next section. </td> </tr> </table> + <p> +If 'pkipath' is specified in URI, then all the client certificates should +be able to found in the path specified, otherwise, connection will fail +with fatal error. And if 'pkipath' is not specified:
"should be able to found" -> "must be found" "otherwise, connection will fail with fatal" -> "otherwise the connection will fail with a fatal" "And if" -> "If" (yeah, I'm being picky, they're not actually Too Bad as it is) :)
+</p>
Indentation again?
+ <ul> + <li> For user who is non-root, libvirt trys to find the certificates
"For a non-root user, ..." maybe? "trys" -> "tries"
+in $HOME/.pki/libvirt, if one of the required certificates can not be found,
Needs to be a full stop rather than a comma at the end of the "pki/libvirt" string. The "If once of the ..." text after is sounds like a new sentence.
+global default locations(/etc/pki/CA/cacert.pem,
Missing a space before the "(/etc" bit. It's probably slightly better wording to add "then the" before the word "global" here too. So its "then the global". It just sounds better. :)
+/etc/pki/libvirt/private/clientkey, /etc/pki/libvirt/clientcert.pem) will be +used. +</li>
Indentation.
+ <li> For user who is root, global default location will be used. </li>
"For the root user, ..."
+ </ul> <h4> <a name="Remote_TLS_background">Background to TLS certificates</a> </h4> -- 1.7.3.2
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
于 2011年01月27日 21:42, Justin Clift 写道:
On 27/01/2011, at 8:01 PM, Osier Yang wrote:
* docs/remote.html.in --- docs/remote.html.in | 30 ++++++++++++++++++++++++++++++ 1 files changed, 30 insertions(+), 0 deletions(-)
diff --git a/docs/remote.html.in b/docs/remote.html.in index b0fdb7c..a68d0fa 100644 --- a/docs/remote.html.in +++ b/docs/remote.html.in @@ -308,6 +308,22 @@ Note that parameter values must be <td colspan="2"/> <td> Example:<code>no_tty=1</code> </td> </tr> +<tr> +<td> +<code>pkipath</code> +</td> +<td> tls</td> +<td> + Specifies x509 certificates path for client. As long as one of the + certificates (CA cerfificate, client key, client certificate) doesn't + exist in the specified path, the connection will fail with fatal + error.
Typo. The "certificate" after the CA is misspelled. ("f" instead of "t" in it). The wording for this paragraph could probably be tweaked a bit anyway. How about something like:
Specifies the x509 certificates path for the client. If any of the CA certificate, client certificate, or client key are missing, the connection will fair with a fatal error.
+</td>
Indentation is off?
+</tr> +<tr> +<td colspan="2"/> +<td> Example:<code>pkipath=/tmp/pki/client</code> </td> +</tr> </table> <h3> <a name="Remote_certificates">Generating TLS certificates</a> @@ -372,6 +388,20 @@ next section. </td> </tr> </table> +<p> +If 'pkipath' is specified in URI, then all the client certificates should +be able to found in the path specified, otherwise, connection will fail +with fatal error. And if 'pkipath' is not specified:
"should be able to found" -> "must be found"
"otherwise, connection will fail with fatal" -> "otherwise the connection will fail with a fatal"
"And if" -> "If"
(yeah, I'm being picky, they're not actually Too Bad as it is) :)
+</p>
Indentation again?
+<ul> +<li> For user who is non-root, libvirt trys to find the certificates
"For a non-root user, ..." maybe?
"trys" -> "tries"
+in $HOME/.pki/libvirt, if one of the required certificates can not be found,
Needs to be a full stop rather than a comma at the end of the "pki/libvirt" string. The "If once of the ..." text after is sounds like a new sentence.
+global default locations(/etc/pki/CA/cacert.pem,
Missing a space before the "(/etc" bit.
It's probably slightly better wording to add "then the" before the word "global" here too. So its "then the global". It just sounds better. :)
+/etc/pki/libvirt/private/clientkey, /etc/pki/libvirt/clientcert.pem) will be +used. +</li>
Indentation.
+<li> For user who is root, global default location will be used.</li>
"For the root user, ..."
+</ul> <h4> <a name="Remote_TLS_background">Background to TLS certificates</a> </h4> -- 1.7.3.2
Ok, thanks for the carefully reviewing, will update all your suggestions, :-) Regards Osier
* docs/remote.html.in --- docs/remote.html.in | 29 +++++++++++++++++++++++++++++ 1 files changed, 29 insertions(+), 0 deletions(-) diff --git a/docs/remote.html.in b/docs/remote.html.in index b0fdb7c..51afa07 100644 --- a/docs/remote.html.in +++ b/docs/remote.html.in @@ -308,6 +308,21 @@ Note that parameter values must be <td colspan="2"/> <td> Example: <code>no_tty=1</code> </td> </tr> + <tr> + <td> + <code>pkipath</code> + </td> + <td> tls</td> + <td> + Specifies x509 certificates path for the client. if any of the + CA certificate, client certificate, and client key is missing, + the connection will fail with a fatal error. + </td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>pkipath=/tmp/pki/client</code> </td> + </tr> </table> <h3> <a name="Remote_certificates">Generating TLS certificates</a> @@ -372,6 +387,20 @@ next section. </td> </tr> </table> + <p> +If 'pkipath' is specified in URI, then all the client certificates must +be found in the path specified, otherwise the connection will fail with +a fatal error. If 'pkipath' is not specified: + </p> + <ul> + <li> For a non-root user, libvirt tries to find the certificates +in $HOME/.pki/libvirt. If any of the required certificates can not be +found, then the global default locations (/etc/pki/CA/cacert.pem, +/etc/pki/libvirt/private/clientkey, /etc/pki/libvirt/clientcert.pem) will +be used. + </li> + <li> For the root user, the global default locations will be used.</li> + </ul> <h4> <a name="Remote_TLS_background">Background to TLS certificates</a> </h4> -- 1.7.3.2
On 28/01/2011, at 1:08 AM, Osier Yang wrote:
* docs/remote.html.in --- docs/remote.html.in | 29 +++++++++++++++++++++++++++++ 1 files changed, 29 insertions(+), 0 deletions(-)
diff --git a/docs/remote.html.in b/docs/remote.html.in index b0fdb7c..51afa07 100644 --- a/docs/remote.html.in +++ b/docs/remote.html.in @@ -308,6 +308,21 @@ Note that parameter values must be <td colspan="2"/> <td> Example: <code>no_tty=1</code> </td> </tr> + <tr> + <td> + <code>pkipath</code> + </td> + <td> tls</td> + <td> + Specifies x509 certificates path for the client. if any of the + CA certificate, client certificate, and client key is missing, + the connection will fail with a fatal error.
Not sure if this is an emailer problem or something, but the indentation of the text isn't correct. It needs to be two spaces in from the opening tag. i.e: <td> <-- lets say this starts at 2 spaces in Specified x509 certificates path... <--- so this would start 4 spaces in </td> <-- starts 2 spaces in again
+ </td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>pkipath=/tmp/pki/client</code> </td> + </tr> </table> <h3> <a name="Remote_certificates">Generating TLS certificates</a> @@ -372,6 +387,20 @@ next section. </td> </tr> </table> + <p> +If 'pkipath' is specified in URI, then all the client certificates must +be found in the path specified, otherwise the connection will fail with +a fatal error. If 'pkipath' is not specified:
Same here.
+ </p> + <ul> + <li> For a non-root user, libvirt tries to find the certificates +in $HOME/.pki/libvirt. If any of the required certificates can not be +found, then the global default locations (/etc/pki/CA/cacert.pem, +/etc/pki/libvirt/private/clientkey, /etc/pki/libvirt/clientcert.pem) will +be used.
And here.
+ </li> + <li> For the root user, the global default locations will be used.</li> + </ul> <h4> <a name="Remote_TLS_background">Background to TLS certificates</a> </h4>
ACK, with the indentation bits fixed. :)
于 2011年01月27日 22:22, Justin Clift 写道:
On 28/01/2011, at 1:08 AM, Osier Yang wrote:
* docs/remote.html.in --- docs/remote.html.in | 29 +++++++++++++++++++++++++++++ 1 files changed, 29 insertions(+), 0 deletions(-)
diff --git a/docs/remote.html.in b/docs/remote.html.in index b0fdb7c..51afa07 100644 --- a/docs/remote.html.in +++ b/docs/remote.html.in @@ -308,6 +308,21 @@ Note that parameter values must be <td colspan="2"/> <td> Example:<code>no_tty=1</code> </td> </tr> +<tr> +<td> +<code>pkipath</code> +</td> +<td> tls</td> +<td> + Specifies x509 certificates path for the client. if any of the + CA certificate, client certificate, and client key is missing, + the connection will fail with a fatal error.
Not sure if this is an emailer problem or something, but the indentation of the text isn't correct. It needs to be two spaces in from the opening tag. i.e:
<td> <-- lets say this starts at 2 spaces in Specified x509 certificates path...<--- so this would start 4 spaces in </td> <-- starts 2 spaces in again
+</td> +</tr> +<tr> +<td colspan="2"/> +<td> Example:<code>pkipath=/tmp/pki/client</code> </td> +</tr> </table> <h3> <a name="Remote_certificates">Generating TLS certificates</a> @@ -372,6 +387,20 @@ next section. </td> </tr> </table> +<p> +If 'pkipath' is specified in URI, then all the client certificates must +be found in the path specified, otherwise the connection will fail with +a fatal error. If 'pkipath' is not specified:
Same here.
+</p> +<ul> +<li> For a non-root user, libvirt tries to find the certificates +in $HOME/.pki/libvirt. If any of the required certificates can not be +found, then the global default locations (/etc/pki/CA/cacert.pem, +/etc/pki/libvirt/private/clientkey, /etc/pki/libvirt/clientcert.pem) will +be used.
And here.
+</li> +<li> For the root user, the global default locations will be used.</li> +</ul> <h4> <a name="Remote_TLS_background">Background to TLS certificates</a> </h4>
ACK, with the indentation bits fixed. :)
Thanks. I saw indention in the doc is not that strict, so didn't pay much attention on it. :-) Regards Osier
On Thu, Jan 27, 2011 at 10:27:09PM +0800, Osier Yang wrote:
于 2011年01月27日 22:22, Justin Clift 写道: [..]
+<tr> +<td> +<code>pkipath</code> +</td> +<td> tls</td> +<td> + Specifies x509 certificates path for the client. if any of the + CA certificate, client certificate, and client key is missing, + the connection will fail with a fatal error.
Not sure if this is an emailer problem or something, but the indentation of the text isn't correct. It needs to be two spaces in from the opening tag. i.e: [...] ACK, with the indentation bits fixed. :)
Thanks.
I saw indention in the doc is not that strict, so didn't pay much attention on it. :-)
Honnestly one or 2 spaces in HTML does not matter, the HTML renderer will just make it equivalent to one space (with space being characters 0x20, CR, LF, and tabs), so except for purely core review, that doesn't change much on the user side, even with XHTML rendering. Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
On 28/01/2011, at 1:41 PM, Daniel Veillard wrote: <snip>
Honnestly one or 2 spaces in HTML does not matter, the HTML renderer will just make it equivalent to one space (with space being characters 0x20, CR, LF, and tabs), so except for purely core review, that doesn't change much on the user side, even with XHTML rendering.
That's also the case with indentation and spacing in our C code, and we really prefer that to be consistent. :)
On 01/27/2011 07:22 AM, Justin Clift wrote:
+ <td> + Specifies x509 certificates path for the client. if any of the + CA certificate, client certificate, and client key is missing, + the connection will fail with a fatal error.
Not sure if this is an emailer problem or something, but the indentation of the text isn't correct.
ACK, with the indentation bits fixed. :)
I reformatted those lines (emacs is great for some things), and pushed. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
于 2011年01月28日 11:48, Eric Blake 写道:
On 01/27/2011 07:22 AM, Justin Clift wrote:
+<td> + Specifies x509 certificates path for the client. if any of the + CA certificate, client certificate, and client key is missing, + the connection will fail with a fatal error.
Not sure if this is an emailer problem or something, but the indentation of the text isn't correct.
ACK, with the indentation bits fixed. :)
I reformatted those lines (emacs is great for some things), and pushed.
Thanks. :-) Regards Osier
participants (4)
-
Daniel Veillard -
Eric Blake -
Justin Clift -
Osier Yang