[Openvpn-devel] doc: document optional message parameter for management command client-kill
Commit Message
From: Sarvagya Chaturvedi <sarvagya0624@gmail.com>
The client-kill command in the management interface accepts an optional
message parameter (M), which is sent to the client as a control channel
command before terminating the session on the server.
Document the syntax of client-kill, the message format (RESTART or HALT
with optional flags [P] and [N] and human-readable message), and the
resulting notifications emitted on the client management interface.
Github: OpenVPN/openvpn#1096
Acked-by: Frank Lichtenheld <frank@lichtenheld.com>
Change-Id: Ied848552f6e9618ca6541d74e20aa1d340027999
Signed-off-by: Sarvagya Chaturvedi <sarvagya0624@gmail.com>
---
doc/management-notes.txt | 27 ++++++++++++++++++++++++++-
1 file changed, 26 insertions(+), 1 deletion(-)
@@ -828,11 +828,36 @@ COMMAND -- client-kill (OpenVPN 2.1 or higher)
Immediately kill a client instance by CID.
- client-kill {CID}
+ client-kill {CID} [M]
CID -- client ID. See documentation for ">CLIENT:" notification for more
info.
+M -- optional message to send to the client before termination
+(defaults to "RESTART"). The format of M is:
+
+ RESTART|HALT[,[flags][human-readable-message]]
+
+RESTART instructs the client to perform a restart (SIGUSR1).
+HALT instructs the client to exit (SIGTERM).
+
+Optional flags in brackets:
+- [P] -- preserve cached passwords and credentials on client (avoids purging auth).
+- [N] -- advance to the next remote server entry in client configuration.
+
+If a human-readable message string is included after the comma, it is
+logged by the client and forwarded to the client's management interface
+via a ">NOTIFY:" event:
+
+ >NOTIFY:info,server-pushed-connection-reset,<msg> (for RESTART)
+ >NOTIFY:info,server-pushed-halt,<msg> (for HALT)
+
+If the message parameter contains spaces, it should be enclosed in double
+quotes, for example:
+
+ client-kill 1 "HALT,Server shutting down for maintenance"
+ client-kill 1 "RESTART,[P]Reconnecting to update configuration"
+
COMMAND -- remote-entry-count (OpenVPN 2.6+ management version > 3)
-------------------------------------------------------------------