diff options
Diffstat (limited to 'doc/gui-notes.txt')
| -rw-r--r-- | doc/gui-notes.txt | 369 |
1 files changed, 369 insertions, 0 deletions
diff --git a/doc/gui-notes.txt b/doc/gui-notes.txt new file mode 100644 index 0000000..e3bbf24 --- /dev/null +++ b/doc/gui-notes.txt @@ -0,0 +1,369 @@ +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. |