manpage: improve description of --status and --status-version

PATCH In review Gert van Dijk 4 participants 7 messages Nov 11, 2017 – Mar 24, 2018

lore

Share & tools

lore

Gert van Dijk

author

2017-11-11 16:11 UTC #0 lore raw

PATCH 1/2 manpage: improve description of --status and --status-version

Signed-off-by Gert van Dijk <[email protected]...>

---
 doc/openvpn.8 | 31 ++++++++++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

doc/openvpn.8 +28 -3

index a4189ac2..267497fd 100644
@@ -2452,12 +2452,37 @@ seconds.
 Status can also be written to the syslog by sending a
 .B SIGUSR2
 signal.
+
+With multi\-client capability enabled on a server, the status file includes a
+list of clients and a routing table. The output format can be controlled by the
+.B \-\-status\-version
+option in that case.
+
+For clients or instances running in point\-to\-point mode, it will contain the
+traffic statistics.
 .\"*********************************************************
 .TP
 .B \-\-status\-version [n]
-Choose the status file format version number.  Currently
-.B n
-can be 1, 2, or 3 and defaults to 1.
+Set the status file format version number to
+.B n\fR.
+
+This only affects the status file on servers with multi\-client capability
+enabled.
+
+.B 1
+\-\- traditional format (default). The client list contains the following
+fields comma\-separated: Common Name, Real Address, Bytes Received, Bytes Sent,
+Connected Since.
+.br
+.B 2
+\-\- a more reliable format for external processing. Compared to version 1, the
+client list contains some additional fields: Virtual Address, Virtual IPv6
+Address, Username, Client ID, Peer ID.
+Future versions may extend the number of fields.
+.br
+.B 3
+\-\- identical to 2, but fields are tab\-separated.
+
 .\"*********************************************************
 .TP
 .B \-\-mute n

Signature · 1 line

2.15.0

Gert van Dijk

author

2017-11-11 16:11 UTC #1 lore raw

PATCH 2/2 Add negotiated cipher to status file format 2 and 3

With NCP turned off, this will still display the cipher used.

Trac: #814

Signed-off-by Gert van Dijk <[email protected]...>

---
 doc/openvpn.8       |  2 +-
 src/openvpn/multi.c | 11 +++++++----
 2 files changed, 8 insertions(+), 5 deletions(-)

doc/openvpn.8 +1 -1

index 267497fd..00dbff6f 100644
@@ -2477,7 +2477,7 @@ Connected Since.
 .B 2
 \-\- a more reliable format for external processing. Compared to version 1, the
 client list contains some additional fields: Virtual Address, Virtual IPv6
-Address, Username, Client ID, Peer ID.
+Address, Username, Client ID, Peer ID, Data Channel Cipher.
 Future versions may extend the number of fields.
 .br
 .B 3

src/openvpn/multi.c +7 -4

index 82a0b9d9..dfad582f 100644
@@ -50,6 +50,8 @@
 #include "forward-inline.h"
 #include "pf-inline.h"
 
+#include "crypto_backend.h"
+
 /*#define MULTI_DEBUG_EVENT_LOOP*/
 
 #ifdef MULTI_DEBUG_EVENT_LOOP

@@ -940,8 +942,8 @@ multi_print_status(struct multi_context *m, struct status_output *so, const int
              */
             status_printf(so, "TITLE%c%s", sep, title_string);
             status_printf(so, "TIME%c%s%c%u", sep, time_string(now, 0, false, &gc_top), sep, (unsigned int)now);
-            status_printf(so, "HEADER%cCLIENT_LIST%cCommon Name%cReal Address%cVirtual Address%cVirtual IPv6 Address%cBytes Received%cBytes Sent%cConnected Since%cConnected Since (time_t)%cUsername%cClient ID%cPeer ID",
-                          sep, sep, sep, sep, sep, sep, sep, sep, sep, sep, sep, sep);
+            status_printf(so, "HEADER%cCLIENT_LIST%cCommon Name%cReal Address%cVirtual Address%cVirtual IPv6 Address%cBytes Received%cBytes Sent%cConnected Since%cConnected Since (time_t)%cUsername%cClient ID%cPeer ID%cData Channel Cipher",
+                          sep, sep, sep, sep, sep, sep, sep, sep, sep, sep, sep, sep, sep);
             hash_iterator_init(m->hash, &hi);
             while ((he = hash_iterator_next(&hi)))
             {

@@ -956,7 +958,7 @@ multi_print_status(struct multi_context *m, struct status_output *so, const int
 #else
                                   ""
 #endif
-                                  "%c%" PRIu32,
+                                  "%c%" PRIu32 "%c%s",
                                   sep, tls_common_name(mi->context.c2.tls_multi, false),
                                   sep, mroute_addr_print(&mi->real, &gc),
                                   sep, print_in_addr_t(mi->reporting_addr, IA_EMPTY_IF_UNDEF, &gc),

@@ -971,7 +973,8 @@ multi_print_status(struct multi_context *m, struct status_output *so, const int
 #else
                                   sep,
 #endif
-                                  sep, mi->context.c2.tls_multi ? mi->context.c2.tls_multi->peer_id : UINT32_MAX);
+                                  sep, mi->context.c2.tls_multi ? mi->context.c2.tls_multi->peer_id : UINT32_MAX,
+                                  sep, translate_cipher_name_to_openvpn(mi->context.options.ciphername));
                 }
                 gc_free(&gc);
             }

Signature · 1 line

2.15.0

Arne Schwabe

Acked-by Tested-by on v1 2/2

2017-11-12 20:09 UTC #2 lore raw

Re: [Openvpn-devel] [PATCH 2/2] Add negotiated cipher to status file format 2 and 3

Am 11.11.17 um 17:11 schrieb Gert van Dijk:

Quoted 15 lines

With NCP turned off, this will still display the cipher used.
Trac: #814
Signed-off-by Gert van Dijk <[email protected]...>
---
 doc/openvpn.8       |  2 +-
 src/openvpn/multi.c | 11 +++++++----
 2 files changed, 8 insertions(+), 5 deletions(-)
doc/openvpn.8 +0 -0
index 267497fd..00dbff6f 100644

doc/openvpn.8 Connected Since. · line 2483

Quoted 8 lines

doc/openvpn.8 +1 -1

@@ -2477,7 +2477,7 @@ Connected Since.
 .B 2
 \-\- a more reliable format for external processing. Compared to version 1, the
 client list contains some additional fields: Virtual Address, Virtual IPv6
-Address, Username, Client ID, Peer ID.
+Address, Username, Client ID, Peer ID, Data Channel Cipher.
 Future versions may extend the number of fields.
 .br
 .B 3

This part of the patch is okay but does not apply cleanly for me. Might need some on the fly fixing on apply.

doc/openvpn.8 multi_print_status(struct multi_context *m, struct status_output *so, const int · line 945

Quoted 7 lines

doc/openvpn.8 +1 -2

@@ -940,8 +942,8 @@ multi_print_status(struct multi_context *m, struct status_output *so, const int
              */
             status_printf(so, "TITLE%c%s", sep, title_string);
             status_printf(so, "TIME%c%s%c%u", sep, time_string(now, 0, false, &gc_top), sep, (unsigned int)now);
-            status_printf(so, "HEADER%cCLIENT_LIST%cCommon Name%cReal Address%cVirtual Address%cVirtual IPv6 Address%cBytes Received%cBytes Sent%cConnected Since%cConnected Since (time_t)%cUsername%cClient ID%cPeer ID",
-                          sep, sep, sep, sep, sep, sep, sep, sep, sep, sep, sep, sep);
+            status_printf(so, "HEADER%cCLIENT_LIST%cCommon Name%cReal Address%cVirtual Address%cVirtual IPv6 Address%cBytes Received%cBytes Sent%cConnected Since%cConnected Since (time_t)%cUsername%cClient ID%cPeer ID%cData Channel Cipher",

Extremely long line, but not your fault, so I will let it pass.

Works for me and code is good so:

Acked-by Arne Schwabe <[email protected]...>

Tested-by Arne Schwabe <[email protected]...>

Arne

Gert van Dijk

author

2017-11-12 20:18 UTC #3 lore raw

Re: [Openvpn-devel] [PATCH 2/2] Add negotiated cipher to status file format 2 and 3

Hi Arne,

Thanks for reviewing this :)

Quoted 20 lines · Arne Schwabe

Am 11.11.17 um 17:11 schrieb Gert van Dijk:
Quoted 19 lines
With NCP turned off, this will still display the cipher used.
Trac: #814
Signed-off-by Gert van Dijk <[email protected]...>
---
 doc/openvpn.8       |  2 +-
 src/openvpn/multi.c | 11 +++++++----
 2 files changed, 8 insertions(+), 5 deletions(-)
doc/openvpn.8 +0 -1
index 267497fd..00dbff6f 100644
@@ -2477,7 +2477,7 @@ Connected Since.
 .B 2
 \-\- a more reliable format for external processing. Compared to version 1, the
 client list contains some additional fields: Virtual Address, Virtual IPv6
-Address, Username, Client ID, Peer ID.

Quoted 9 lines

doc/openvpn.8 Connected Since. · line 2483
Quoted 4 lines
doc/openvpn.8 +1 -0
+Address, Username, Client ID, Peer ID, Data Channel Cipher.
 Future versions may extend the number of fields.
 .br
 .B 3
This part of the patch is okay but does not apply cleanly for me. Might need some on the fly fixing on apply.

Did you apply the first part ([PATCH 1/2] manpage: improve description of --status and --status-version)?

Quoted 20 lines

doc/openvpn.8 multi_print_status(struct multi_context *m, struct status_output *so, const int · line 945

Quoted 7 lines

doc/openvpn.8 +1 -2

@@ -940,8 +942,8 @@ multi_print_status(struct multi_context *m, struct status_output *so, const int
              */
             status_printf(so, "TITLE%c%s", sep, title_string);
             status_printf(so, "TIME%c%s%c%u", sep, time_string(now, 0, false, &gc_top), sep, (unsigned int)now);
-            status_printf(so, "HEADER%cCLIENT_LIST%cCommon Name%cReal Address%cVirtual Address%cVirtual IPv6 Address%cBytes Received%cBytes Sent%cConnected Since%cConnected Since (time_t)%cUsername%cClient ID%cPeer ID",
-                          sep, sep, sep, sep, sep, sep, sep, sep, sep, sep, sep, sep);
+            status_printf(so, "HEADER%cCLIENT_LIST%cCommon Name%cReal Address%cVirtual Address%cVirtual IPv6 Address%cBytes Received%cBytes Sent%cConnected Since%cConnected Since (time_t)%cUsername%cClient ID%cPeer ID%cData Channel Cipher",

Extremely long line, but not your fault, so I will let it pass.

Works for me and code is good so:

Acked-by Arne Schwabe <[email protected]...>

Tested-by Arne Schwabe <[email protected]...>>

Arne

Gert Doering

2018-03-24 18:35 UTC #4 lore raw

[Openvpn-devel] [PATCH applied] Re: Add negotiated cipher to status file format 2 and 3

In reply to Gert van Dijk

Your patch has been applied to the master branch.

(Only to master, because "new feature" - while harmless enough, we want to lure people into running 2.5 eventually, so: immediate benefit... :-) wrt the side discussion about "applies cleanly" - it does, with 1/2 in place)

commit 8acc40b6a64451d9a17cf4fa12fac2450ca26095

Author: Gert van Dijk
Date:   Sat Nov 11 17:11:22 2017 +0100

     Add negotiated cipher to status file format 2 and 3

     Signed-off-by: Gert van Dijk <[email protected]...>
     Acked-by: Arne Schwabe <[email protected]...>
     Message-Id: <[email protected]...>
     URL: https://www.mail-archive.com/[email protected]/msg15817.html
     Signed-off-by: Gert Doering <[email protected]...>

--
kind regards,

Gert Doering

Steffan Karger

2017-11-26 10:02 UTC #5 lore raw

In reply to Gert van Dijk

Hi,

A very welcome improvement of the man page, but one consideration:

Quoted 10 lines · Gert van Dijk

Signed-off-by Gert van Dijk <[email protected]...>
---
 doc/openvpn.8 | 31 ++++++++++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)
doc/openvpn.8 +0 -0
index a4189ac2..267497fd 100644

doc/openvpn.8 seconds. · line 2456

Quoted 5 lines

doc/openvpn.8 +2 -0

@@ -2452,12 +2452,37 @@ seconds.
 Status can also be written to the syslog by sending a
 .B SIGUSR2
 signal.
+
+With multi\-client capability enabled on a server, the status file includes a

Although 'server mode' is somewhat ambiguous, that is what most of the man page uses. So I'd suggest to change this to 'In server mode, ...'.

(With 'server mode' we mean '--mode server' as described in the 'Server mode' section, but some might interpret 'tls-server' or 'tcp-server' as a 'server mode'.)

-Steffan

Gert Doering

Acked-by on v1 1/2

2018-03-24 18:26 UTC #6 lore raw

In reply to Gert van Dijk

Acked-by Gert Doering <[email protected]...>

Documentation is always welcome, and the new text is an improvement.

Your patch has been applied to the master and release/2.4 branch.

commit 308c9d7f001a97daebcccf503f255947c0e09183 (master) commit 5213573f7d6ba41639edc362801efe076906a7e4 (release/2.4)

Author: Gert van Dijk
Date:   Sat Nov 11 17:11:21 2017 +0100

     manpage: improve description of --status and --status-version

     Signed-off-by: Gert van Dijk <[email protected]...>
     Acked-by: Gert Doering <[email protected]...>
     Message-Id: <[email protected]...>
     URL: https://www.mail-archive.com/[email protected]/msg15818.html
     Signed-off-by: Gert Doering <[email protected]...>

--
kind regards,

Gert Doering