mirror of
https://github.com/OpenVPN/openvpn.git
synced 2024-09-20 03:52:28 +02:00
370 lines
12 KiB
Plaintext
370 lines
12 KiB
Plaintext
|
Management Interface "echo" protocol
|
||
|
|
||
|
================================================================================
|
||
|
THIS IS A PRELIMINARY VERSION OF THIS DOCUMENT. ALL INFORMATION IN IT
|
||
|
IS SUBJECT TO CHANGE.
|
||
|
================================================================================
|
||
|
|
||
|
|
||
|
CONTENTS
|
||
|
THE OPENVPN --ECHO OPTION
|
||
|
ENVIRONMENT COMMAND
|
||
|
MESSSAGE COMMANDS
|
||
|
PASSWORD COMMANDS
|
||
|
QUOTING
|
||
|
COMMMAND DETAILS
|
||
|
|
||
|
|
||
|
=========================
|
||
|
THE OPENVPN --ECHO OPTION
|
||
|
=========================
|
||
|
|
||
|
The OpenVPN --echo option causes commands to be sent out through the
|
||
|
management interface, typically to a Graphic User Interface (GUI) such
|
||
|
as "OpenVPN for Android", "Tunnelblick" (for macOS), or "Windows
|
||
|
OpenVPN GUI". It can be included in a configuration file or on a
|
||
|
command line, or can be pushed from the server.
|
||
|
|
||
|
This document describes the commands that can be sent and how they are
|
||
|
interpreted by various GUIs.
|
||
|
|
||
|
* OpenVPN does not process the commands in an --echo option; it only
|
||
|
sends them out through the management interface.
|
||
|
|
||
|
* "echo" commands are processed by the GUI if, as, when, and in the
|
||
|
order they are received. If no GUI is present the processing of
|
||
|
commands may be delayed, the commands may never be processed, or only
|
||
|
some commands may be processed. (That can happen if OpenVPN discards
|
||
|
commands because its buffer for the commands fills up.)
|
||
|
|
||
|
* There is no mechanism for the GUI to acknowledge the receipt,
|
||
|
success, or failure of a command.
|
||
|
|
||
|
* "echo" commands are stored by OpenVPN (within limits, see the next
|
||
|
point) and sent only when the GUI requests them through the management
|
||
|
interface. "echo" commands in the configuration file or the command
|
||
|
line are typically requested and processed at the start of a
|
||
|
connection attempt. "echo" commands that are pushed by the server are
|
||
|
also typically asked for at the start of a connection attempt but can
|
||
|
be sent at any time. They are processed in the middle of a connection
|
||
|
attempt or after a connection is established, as the "push" options
|
||
|
are received by the client from the server.
|
||
|
|
||
|
* OpenVPN's storage for echo commands is limited in size, so a large
|
||
|
number of commands or commands with long messages may require that
|
||
|
some commands be removed from the storage. If that happens, some of
|
||
|
the commands may not be sent through the management interface when a
|
||
|
GUI does connect to it or asks for the "echo" commands.
|
||
|
|
||
|
* On SIGUSR1 and SIGHUP connection restarts, "echo" commands that
|
||
|
were sent through the management interface and have been saved by
|
||
|
OpenVPN are sent again and will be re-processed by the GUI. (The
|
||
|
message commands include a mechanism for muting (skipping) duplicate
|
||
|
messages, see MESSAGE COMMANDS, below.)
|
||
|
|
||
|
* OpenVPN limits the number of separate arguments in each line of a
|
||
|
configuration file. Arguments may be quoted to work around this
|
||
|
limitation, see QUOTING, below.
|
||
|
|
||
|
* OpenVPN limits the size of each "echo" command sent over the
|
||
|
management interface to 255 bytes, including overhead characters. To
|
||
|
allow messages of arbitrary length, several message commands can be
|
||
|
concatenated together before being displayed to the user, see MESSAGE
|
||
|
COMMANDS, below.
|
||
|
|
||
|
* There no indication to the GUI of the source of the command
|
||
|
(configuration file, command line option, or pushed from a server). It
|
||
|
might be possible for the GUI to deduce that a command was pushed from
|
||
|
a server because of timing or other management interface interactions.
|
||
|
|
||
|
|
||
|
===================
|
||
|
ENVIRONMENT COMMAND
|
||
|
===================
|
||
|
|
||
|
Typically, a GUI allows users to specify shell commands (typically
|
||
|
scripts) to run at certain points in the connection/disconnection
|
||
|
process, in addition to those provided by OpenVPN options such as
|
||
|
"--up" and "--down".
|
||
|
|
||
|
The "setenv" command can be used to set environment variables that are
|
||
|
available to the scripts run by the GUI. Each "setenv" command
|
||
|
specifies a value for one environment variable that is available to
|
||
|
the scripts that the GUI runs.
|
||
|
|
||
|
This is similar to Openvpn's "--setenv" option, which specifies an
|
||
|
additional environment variable that is included in the environment
|
||
|
variables that are available to the scripts that OpenVPN runs.
|
||
|
|
||
|
|
||
|
=================
|
||
|
MESSSAGE COMMANDS
|
||
|
=================
|
||
|
|
||
|
Four commands can be used to display a message to the user from the
|
||
|
OpenVPN configuration or server:
|
||
|
|
||
|
msg
|
||
|
msg-n
|
||
|
msg-window
|
||
|
msg-notify
|
||
|
|
||
|
"msg" and "msg-n" commands are concatenated to construct a message.
|
||
|
When a "msg-window"or "msg-notify" command is received the message is
|
||
|
displayed to the user.
|
||
|
|
||
|
Identical messages (same title, text, and destination) received during
|
||
|
one connection may be ignored or muted. Some GUIs may only show the
|
||
|
first message for a connection, or the first message shown in a window
|
||
|
and the first message shown as a notification.
|
||
|
|
||
|
|
||
|
=================
|
||
|
PASSWORD COMMANDS
|
||
|
=================
|
||
|
|
||
|
Three commands can be used to control the GUI's storage of usernames,
|
||
|
passwords, and private keys:
|
||
|
|
||
|
disable-save-passwords
|
||
|
forget-passwords
|
||
|
save-passwords
|
||
|
|
||
|
|
||
|
=======
|
||
|
QUOTING
|
||
|
=======
|
||
|
|
||
|
* In a configuration file, the rest of the line is parsed into
|
||
|
separate arguments and then 'echo' and the arguments are passed, each
|
||
|
separated by a single space, through the management interface. For
|
||
|
example:
|
||
|
|
||
|
echo argument1 argument2
|
||
|
echo " argument1 argument2"
|
||
|
|
||
|
will be sent through the management interface as
|
||
|
|
||
|
>ECHO:timestamp,argument1 argument2
|
||
|
>ECHO:timestamp, argument1 argument2
|
||
|
|
||
|
* In a command line option, the single argument following "--echo" is
|
||
|
parsed similarly, so
|
||
|
|
||
|
--echo argument1 argument2
|
||
|
--echo " argument1 argument2"
|
||
|
|
||
|
will be sent through the management interface as
|
||
|
|
||
|
>ECHO:timestamp,argument1 argument2
|
||
|
>ECHO:timestamp, argument1 argument2
|
||
|
|
||
|
* In a "push" option in a server configuration file, the single
|
||
|
option following "push" is parsed similarly, so
|
||
|
|
||
|
push "echo argument1 argument2 argument3 argument4"
|
||
|
push "echo ' argument1 argument2 argument3 argument4'"
|
||
|
|
||
|
will be sent through the management interface as
|
||
|
|
||
|
>ECHO:timestamp,argument1 argument2 argument3 argument4
|
||
|
>ECHO:timestamp, argument1 argument2 argument3 argument4
|
||
|
|
||
|
|
||
|
================
|
||
|
COMMMAND DETAILS
|
||
|
================
|
||
|
|
||
|
|
||
|
COMMAND -- disable-save-passwords
|
||
|
---------------------------------
|
||
|
|
||
|
Syntax: disable-save-passwords
|
||
|
|
||
|
The GUI is instructed to not allow the user to save passwords or
|
||
|
private keys for the configuration. The user is still allowed to save
|
||
|
usernames. Any passwords or private keys that have been saved will be
|
||
|
forgotten.
|
||
|
|
||
|
This command will be effective at startup only if present in the
|
||
|
configuration file or as a command line option. If pushed from the
|
||
|
server, saving passwords will be disabled in password prompts only
|
||
|
after the initial prompt has been shown to the user.
|
||
|
|
||
|
Android: ??????
|
||
|
|
||
|
Tunnelblick: Planned. This command will disable saving of
|
||
|
passwords or private keys and forget any saved usernames, passwords,
|
||
|
or private keys regardless of the normal (non-forced) global or
|
||
|
per-configuration settings. A computer administrator can "force" this
|
||
|
setting, overriding this command.
|
||
|
|
||
|
Windows OpenVPN GUI: Planned. This command will disable saving of
|
||
|
passwords or private keys and forget any saved usernames, passwords,
|
||
|
or private keys regardless of any global settings.
|
||
|
|
||
|
|
||
|
COMMAND -- forget-passwords
|
||
|
---------------------------
|
||
|
|
||
|
Syntax: forget-passwords
|
||
|
|
||
|
The GUI is instructed to forget any usernames, passwords, and private
|
||
|
keys it has saved for the configuration. Useful when pushed from the
|
||
|
server so that it is processed after authentication.
|
||
|
|
||
|
Android: ??????
|
||
|
|
||
|
Tunnelblick: Planned.
|
||
|
|
||
|
Windows OpenVPN GUI: supported since release 2.4.1 (GUI version 11.5.0)
|
||
|
|
||
|
|
||
|
COMMAND -- msg
|
||
|
--------------
|
||
|
|
||
|
Syntax: msg text
|
||
|
|
||
|
The text is appended to any previous text from "msg" or "msg-n"
|
||
|
commands, and a newline is appended after that.
|
||
|
|
||
|
A trailing newline will be removed from the completed message before
|
||
|
it is displayed to the user.
|
||
|
|
||
|
The text may include any UTF-8 character except a comma (","), CR
|
||
|
(0x0D), LF (0x0A), or NUL (0x00).
|
||
|
|
||
|
The text may not contain percent ("%") except in "percent encoding"
|
||
|
sequences. To display a percent sign, use %25.
|
||
|
|
||
|
The text may not contain commas (",") because of constraints imposed
|
||
|
by OpenVPN. Commas should be encoded using "percent encoding" (URL
|
||
|
encoding): a '%' character followed by two hexadecimal digits, the
|
||
|
high- and then low-nibble of the ASCII code for the character to be
|
||
|
shown. Examples: a comma is encoded as %2C or %2c; a percent sign is
|
||
|
encoded as %25.
|
||
|
|
||
|
Text containing comment characters # and ; must be enclosed in quotes to
|
||
|
survive after option parsing by openvpn.
|
||
|
|
||
|
The insertion of line endings (CR, LF) in the text is discouraged
|
||
|
because it is OS dependent. Instead, use the "msg" command, which
|
||
|
appends a line ending appropriate for the OS on which the GUI is
|
||
|
running.
|
||
|
|
||
|
Android: Planned.
|
||
|
|
||
|
Tunnelblick: Planned.
|
||
|
|
||
|
Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
|
||
|
(GUI version v11.22.0)
|
||
|
|
||
|
COMMAND -- msg-n
|
||
|
----------------
|
||
|
|
||
|
Syntax: msg-n text
|
||
|
|
||
|
The text is appended to any previous text from "msg"" or "msg-n""
|
||
|
commands. (Like "msg" except that no newline is appended.)
|
||
|
|
||
|
See "COMMAND -- msg" for details about "text".
|
||
|
|
||
|
Android: Planned.
|
||
|
|
||
|
Tunnelblick: Planned.
|
||
|
|
||
|
Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
|
||
|
(GUI version v11.22.0)
|
||
|
|
||
|
COMMAND -- msg-notify
|
||
|
---------------------
|
||
|
|
||
|
Syntax: msg-notify title
|
||
|
|
||
|
The text from previous "msg" and/or "msg-n" commands is displayed to
|
||
|
the user as a notification with title "title" and the previous text is
|
||
|
forgotten.
|
||
|
|
||
|
Android: Planned.
|
||
|
|
||
|
Tunnelblick: Planned.
|
||
|
|
||
|
Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
|
||
|
(GUI version v11.22.0)
|
||
|
|
||
|
Note: The max length that will correctly display as a notification
|
||
|
message is OS dependent.
|
||
|
|
||
|
|
||
|
COMMAND -- msg-window title
|
||
|
---------------------------
|
||
|
|
||
|
Syntax: msg-window title
|
||
|
|
||
|
The text from previous "msg" and/or "msg-n" commands is displayed to
|
||
|
the user in a non-modal popup window with title "title" and the
|
||
|
previous text is forgotten. How the title is displayed exactly is left
|
||
|
to the implementation. Could be set as the window title or as a
|
||
|
differently formatted text as the heading of the message, for example.
|
||
|
|
||
|
Android: Planned.
|
||
|
|
||
|
Tunnelblick: Planned.
|
||
|
|
||
|
Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
|
||
|
(GUI version v11.22.0)
|
||
|
|
||
|
|
||
|
COMMAND -- save-passwords
|
||
|
-------------------------
|
||
|
|
||
|
Syntax: save-passwords
|
||
|
|
||
|
The GUI is instructed to allow the user to save usernames, passwords
|
||
|
and private keys for the configuration.
|
||
|
|
||
|
This command will be effective at startup only if present in the
|
||
|
configuration file or as a command line option. If pushed from the
|
||
|
server, saving passwords will be allowed in password prompts only
|
||
|
after the initial prompt has been shown to the user.
|
||
|
|
||
|
This command typically has the effect of presenting the password
|
||
|
dialogs to the user with a "save password" checkbox checked. The user
|
||
|
may still uncheck it during the dialog.
|
||
|
|
||
|
Android: ??????
|
||
|
|
||
|
Tunnelblick: Planned. Tunnelblick ignores this command. Usernames,
|
||
|
passwords, and private keys may be saved by default, and this command
|
||
|
will not override the separate Tunnelblick global or per-configuration
|
||
|
settings used to disable saving them.
|
||
|
|
||
|
Windows OpenVPN GUI: Supported since release 2.4.1 (GUI version 11.5.0)
|
||
|
|
||
|
|
||
|
COMMAND -- setenv
|
||
|
-----------------
|
||
|
|
||
|
Syntax: setenv name value
|
||
|
|
||
|
Sets an environment variable that will be available to the scripts run
|
||
|
by the GUI.
|
||
|
|
||
|
This will set environment variable "OPENVPN_name" to value "value" for
|
||
|
the scripts run by the GUI. "name" is changed to "OPENVPN_name" to
|
||
|
prevent overwriting sensitive variables such as PATH. Variables are
|
||
|
set in the order received, with later values replacing earlier ones
|
||
|
for the same "name".
|
||
|
|
||
|
Names may include only alphanumeric characters and underscores. A
|
||
|
"setenv" command with an invalid name will be ignored.
|
||
|
|
||
|
Android: ??????
|
||
|
|
||
|
Tunnelblick: Planned.
|
||
|
|
||
|
Windows OpenVPN GUI: supported since release v2.4.7 (GUI version v11.12.0)
|
||
|
The variables set by "setenv" are merged with those for the process
|
||
|
environment. In case of duplicate names the one in the setenv list is
|
||
|
chosen.
|