man: Improve the --keepalive section
PATCH 1/1 man: Improve the --keepalive section
Just minor clarifications and corrections of the --keepalive option.
--- doc/openvpn.8 | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-)
doc/openvpn.8 +19 -10
@@ -1614,15 +1614,24 @@ and are mutually exclusive and cannot be used together. .\"********************************************************* .TP -.B \-\-keepalive n m +.B \-\-keepalive ps pto A helper directive designed to simplify the expression of .B \-\-ping and +.B \-\-ping\-restart. + +This option can be used on both client and server side, but it is +in most cases enough to add this on the server side as it will +push appropriate +.B \-\-ping +and .B \-\-ping\-restart -in server mode configurations. +options to the client. If used on both server and client, +the values pushed from server will override the client local values. -The server timeout is set twice the value of the second argument. -This ensures that a timeout is detected on client side +The server-side timeout is the +.B pto +argument doubled. This ensures that a timeout is detected on client side before the server side drops the connection. For example,
@@ -1633,13 +1642,13 @@ expands as follows: .ft 3 .in +4 if mode server: - ping 10 - ping\-restart 120 - push "ping 10" - push "ping\-restart 60" + ping 10 # Argument: ps + ping\-restart 120 # Argument: pto*2 + push "ping 10" # Argument: ps + push "ping\-restart 60" # Argument: pto else - ping 10 - ping\-restart 60 + ping 10 # Argument: ps + ping\-restart 60 # Argument: pto .in -4 .ft .fi
Signature · 1 line
1.8.3.1
Hi,
Quoted 2 lines · David Sommerseth
-.B \-\-keepalive n m
+.B \-\-keepalive ps pto
What does "ps" stand for? I find this not much clearer than "n"...
"pto" sounds like "ping time out", which I find halfway understandable.
Maybe make the first argument "t" for "time"?
Or "i" and "to" for "interval" and "timeout"?
Lots of options for bikeshedding here...
gert
Signature · 4 lines
USENET is *not* the non-clickable part of WWW!
//www.muc.de/~gert/
Gert Doering - Munich, Germany [email protected]...
fax: +49-89-35655025 [email protected]...Quoted 8 lines · Gert Doering
Hi,
Quoted 2 lines · David Sommerseth
-.B \-\-keepalive n m
+.B \-\-keepalive ps ptoWhat does "ps" stand for? I find this not much clearer than "n"...
Quoted 7 lines
"pto" sounds like "ping time out", which I find halfway understandable.
Maybe make the first argument "t" for "time"?
Or "i" and "to" for "interval" and "timeout"?
Lots of options for bikeshedding here...
I have no strong opinions here. I thought pi (ping interval), but considered to close to 3.1415.... ps wasn't goo either, but that's meant to be "ping seconds" (poor interval alternative, I agree). I thought of pt and pti as well, but thought that could be somewhat confusing with pto.
pto is as you decoded, Ping Time-Out. I chose 'pto' as just 'to' could be confusing in the text below ("... timeout is the to argument...").
I also though of 'pin', but that could also be confusing. Even considered a proper word, but then the man page needs to be rendered in a way that these keywords are emphasized (like bold/white). Maybe change ps to int - as in interval]? Or pis (ping interval seconds).
The reasoning for changing n and m to something else was in a hope to it easier to grasp what each of these arguments really meant - and easier see them in a bigger context.
But I'm very open for other suggestions; I don't care about the bikeshed colour as long as it is at least a slight improvement of what we have today.
Signature · 3 lines
kind regards, David Sommerseth
Quoted 28 lines · David Sommerseth
Quoted 6 lines · Gert Doering
Quoted 2 lines · David Sommerseth
-.B \-\-keepalive n m
+.B \-\-keepalive ps ptoWhat does "ps" stand for? I find this not much clearer than "n"...
Quoted 7 lines
"pto" sounds like "ping time out", which I find halfway understandable.
Maybe make the first argument "t" for "time"?
Or "i" and "to" for "interval" and "timeout"?
Lots of options for bikeshedding here...
I have no strong opinions here. I thought pi (ping interval), but considered to close to 3.1415.... ps wasn't goo either, but that's meant to be "ping seconds" (poor interval alternative, I agree). I thought of pt and pti as well, but thought that could be somewhat confusing with pto.
pto is as you decoded, Ping Time-Out. I chose 'pto' as just 'to' could be confusing in the text below ("... timeout is the to argument...").
I also though of 'pin', but that could also be confusing. Even considered a proper word, but then the man page needs to be rendered in a way that these keywords are emphasized (like bold/white). Maybe change ps to int - as in interval]? Or pis (ping interval seconds).
Quoted 6 lines
The reasoning for changing n and m to something else was in a hope to it easier to grasp what each of these arguments really meant - and easier see them in a bigger context.
But I'm very open for other suggestions; I don't care about the bikeshed colour as long as it is at least a slight improvement of what we have today.
"Thou shell never waste an opportunity to bikeshed."
So, we don't have a shortage of characters here, right? Why not simply 'interval' and 'timeout'?
-Steffan
Hi,
Quoted 4 lines · Steffan Karger
Quoted 2 lines
But I'm very open for other suggestions; I don't care about the bikeshed colour as long as it is at least a slight improvement of what we have today.
"Thou shell never waste an opportunity to bikeshed."
Be our guest ;-)
Quoted 2 lines
So, we don't have a shortage of characters here, right? Why not simply 'interval' and 'timeout'?
Works for me.
gert
Signature · 4 lines
USENET is *not* the non-clickable part of WWW!
//www.muc.de/~gert/
Gert Doering - Munich, Germany [email protected]...
fax: +49-89-35655025 [email protected]...PATCH v2 1/1 man: Improve the --keepalive section
In reply to David SommersethJust minor clarifications and corrections of the --keepalive option.
v2 - Changed from ps/pto to interval/timeout
- Rephrased the server-side timeout doubling parapgraph
--- doc/openvpn.8 | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-)
doc/openvpn.8 +20 -11
@@ -1614,16 +1614,25 @@ and are mutually exclusive and cannot be used together. .\"********************************************************* .TP -.B \-\-keepalive n m +.B \-\-keepalive interval timeout A helper directive designed to simplify the expression of .B \-\-ping and +.B \-\-ping\-restart. + +This option can be used on both client and server side, but it is +in enough to add this on the server side as it will push appropriate +.B \-\-ping +and .B \-\-ping\-restart -in server mode configurations. +options to the client. If used on both server and client, +the values pushed from server will override the client local values. -The server timeout is set twice the value of the second argument. -This ensures that a timeout is detected on client side -before the server side drops the connection. +The +.B timeout +argument will be twice as long on the server side. This ensures that +a timeout is detected on client side before the server side drops +the connection. For example, .B \-\-keepalive 10 60
@@ -1633,13 +1642,13 @@ expands as follows: .ft 3 .in +4 if mode server: - ping 10 - ping\-restart 120 - push "ping 10" - push "ping\-restart 60" + ping 10 # Argument: interval + ping\-restart 120 # Argument: timeout*2 + push "ping 10" # Argument: interval + push "ping\-restart 60" # Argument: timeout else - ping 10 - ping\-restart 60 + ping 10 # Argument: interval + ping\-restart 60 # Argument: timeout .in -4 .ft .fi
Signature · 1 line
1.8.3.1
ACK.
Your patch has been applied to the master and release/2.3 branch.
commit beaa6564a7ce3e48473a8bde7b4f9291df490d62 (master) commit 28778220dd50fd68f0f81cbcc1c73fdd16f04be8 (release/2.3)
Author: David Sommerseth Date: Tue Nov 1 14:38:09 2016 +0100
man: Improve the --keepalive section
Signed-off-by: David Sommerseth <[email protected]...>
Acked-by: Gert Doering <[email protected]...>
Message-Id: <[email protected]...>
URL: https://www.mail-archive.com/[email protected]/msg12866.html
Signed-off-by: Gert Doering <[email protected]...>--
kind regards,
Gert Doering