doc/gui-notes.txt

   1 Management Interface "echo" protocol
   2
   3 ================================================================================
   4 THIS IS A PRELIMINARY VERSION OF THIS DOCUMENT. ALL INFORMATION IN IT
   5 IS SUBJECT TO CHANGE.
   6 ================================================================================
   7
   8
   9     CONTENTS
  10         THE OPENVPN --ECHO OPTION
  11         ENVIRONMENT COMMAND
  12         MESSSAGE COMMANDS
  13         PASSWORD COMMANDS
  14         QUOTING
  15         COMMMAND DETAILS
  16
  17
  18 =========================
  19 THE OPENVPN --ECHO OPTION
  20 =========================
  21
  22 The OpenVPN --echo option causes commands to be sent out through the
  23 management interface, typically to a Graphic User Interface (GUI) such
  24 as "OpenVPN for Android", "Tunnelblick" (for macOS), or "Windows
  25 OpenVPN GUI". It can be included in a configuration file or on a
  26 command line, or can be pushed from the server.
  27
  28 This document describes the commands that can be sent and how they are
  29 interpreted by various GUIs.
  30
  31  * OpenVPN does not process the commands in an --echo option; it only
  32 sends them out through the management interface.
  33
  34  * "echo" commands are processed by the GUI if, as, when, and in the
  35 order they are received. If no GUI is present the processing of
  36 commands may be delayed, the commands may never be processed, or only
  37 some commands may be processed. (That can happen if OpenVPN discards
  38 commands because its buffer for the commands fills up.)
  39
  40  * There is no mechanism for the GUI to acknowledge the receipt,
  41 success, or failure of a command.
  42
  43  * "echo" commands are stored by OpenVPN (within limits, see the next
  44 point) and sent only when the GUI requests them through the management
  45 interface. "echo" commands in the configuration file or the command
  46 line are typically requested and processed at the start of a
  47 connection attempt. "echo" commands that are pushed by the server are
  48 also typically asked for at the start of a connection attempt but can
  49 be sent at any time. They are processed in the middle of a connection
  50 attempt or after a connection is established, as the "push" options
  51 are received by the client from the server.
  52
  53   * OpenVPN's storage for echo commands is limited in size, so a large
  54 number of commands or commands with long messages may require that
  55 some commands be removed from the storage. If that happens, some of
  56 the commands may not be sent through the management interface when a
  57 GUI does connect to it or asks for the "echo" commands.
  58
  59  * On SIGUSR1 and SIGHUP connection restarts, "echo" commands that
  60 were sent through the management interface and have been saved by
  61 OpenVPN are sent again and will be re-processed by the GUI. (The
  62 message commands include a mechanism for muting (skipping) duplicate
  63 messages, see MESSAGE COMMANDS, below.)
  64
  65  * OpenVPN limits the number of separate arguments in each line of a
  66 configuration file. Arguments may be quoted to work around this
  67 limitation, see QUOTING, below.
  68
  69  * OpenVPN limits the size of each "echo" command sent over the
  70 management interface to 255 bytes, including overhead characters. To
  71 allow messages of arbitrary length, several message commands can be
  72 concatenated together before being displayed to the user, see MESSAGE
  73 COMMANDS, below.
  74
  75  * There no indication to the GUI of the source of the command
  76 (configuration file, command line option, or pushed from a server). It
  77 might be possible for the GUI to deduce that a command was pushed from
  78 a server because of timing or other management interface interactions.
  79
  80
  81 ===================
  82 ENVIRONMENT COMMAND
  83 ===================
  84
  85 Typically, a GUI allows users to specify shell commands (typically
  86 scripts) to run at certain points in the connection/disconnection
  87 process, in addition to those provided by OpenVPN options such as
  88 "--up" and "--down".
  89
  90 The "setenv" command can be used to set environment variables that are
  91 available to the scripts run by the GUI. Each "setenv" command
  92 specifies a value for one environment variable that is available to
  93 the scripts that the GUI runs.
  94
  95 This is similar to Openvpn's "--setenv" option, which specifies an
  96 additional environment variable that is included in the environment
  97 variables that are available to the scripts that OpenVPN runs.
  98
  99
 100 =================
 101 MESSSAGE COMMANDS
 102 =================
 103
 104 Four commands can be used to display a message to the user from the
 105 OpenVPN configuration or server:
 106
 107     msg
 108     msg-n
 109     msg-window
 110     msg-notify
 111
 112 "msg" and "msg-n" commands are concatenated to construct a message.
 113 When a "msg-window"or "msg-notify" command is received the message is
 114 displayed to the user.
 115
 116 Identical messages (same title, text, and destination) received during
 117 one connection may be ignored or muted. Some GUIs may only show the
 118 first message for a connection, or the first message shown in a window
 119 and the first message shown as a notification.
 120
 121
 122 =================
 123 PASSWORD COMMANDS
 124 =================
 125
 126 Three commands can be used to control the GUI's storage of usernames,
 127 passwords, and private keys:
 128
 129     disable-save-passwords
 130     forget-passwords
 131     save-passwords
 132
 133
 134 =======
 135 QUOTING
 136 =======
 137
 138  * In a configuration file, the rest of the line is parsed into
 139 separate arguments  and then 'echo' and the arguments are passed, each
 140 separated by a single space, through the management interface. For
 141 example:
 142
 143     echo     argument1 argument2
 144     echo    "     argument1      argument2"
 145
 146 will be sent through the management interface as
 147
 148     >ECHO:timestamp,argument1 argument2
 149     >ECHO:timestamp,     argument1      argument2
 150
 151  * In a command line option, the single argument following "--echo" is
 152 parsed similarly, so
 153
 154     --echo   argument1     argument2
 155     --echo   "    argument1     argument2"
 156
 157 will be sent through the management interface as
 158
 159     >ECHO:timestamp,argument1 argument2
 160     >ECHO:timestamp,     argument1      argument2
 161
 162  * In a "push" option in a server configuration file, the single
 163 option following "push" is parsed similarly, so
 164
 165     push "echo argument1 argument2 argument3   argument4"
 166     push "echo '    argument1 argument2 argument3   argument4'"
 167
 168 will be sent through the management interface as
 169
 170     >ECHO:timestamp,argument1 argument2 argument3 argument4
 171     >ECHO:timestamp,     argument1 argument2 argument3   argument4
 172
 173
 174 ================
 175 COMMMAND DETAILS
 176 ================
 177
 178
 179 COMMAND -- disable-save-passwords
 180 ---------------------------------
 181
 182 Syntax: disable-save-passwords
 183
 184 The GUI is instructed to not allow the user to save passwords or
 185 private keys for the configuration. The user is still allowed to save
 186 usernames. Any passwords or private keys that have been saved will be
 187 forgotten.
 188
 189 This command will be effective at startup only if present in the
 190 configuration file or as a command line option. If pushed from the
 191 server, saving passwords will be disabled in password prompts only
 192 after the initial prompt has been shown to the user.
 193
 194     Android: ??????
 195
 196     Tunnelblick: Planned. This command will disable saving of
 197 passwords or private keys and forget any saved usernames, passwords,
 198 or private keys regardless of the normal (non-forced) global or
 199 per-configuration settings. A computer administrator can "force" this
 200 setting, overriding this command.
 201
 202     Windows OpenVPN GUI: Planned. This command will disable saving of
 203 passwords or private keys and forget any saved usernames, passwords,
 204 or private keys regardless of any global settings.
 205
 206
 207 COMMAND -- forget-passwords
 208 ---------------------------
 209
 210 Syntax: forget-passwords
 211
 212 The GUI is instructed to forget any usernames, passwords, and private
 213 keys it has saved for the configuration. Useful when pushed from the
 214 server so that it is processed after authentication.
 215
 216     Android: ??????
 217
 218     Tunnelblick: Planned.
 219
 220     Windows OpenVPN GUI: supported since release 2.4.1 (GUI version 11.5.0)
 221
 222
 223 COMMAND -- msg
 224 --------------
 225
 226 Syntax: msg text
 227
 228 The text is appended to any previous text from "msg" or "msg-n"
 229 commands, and a newline is appended after that.
 230
 231 A trailing newline will be removed from the completed message before
 232 it is displayed to the user.
 233
 234 The text may include any UTF-8 character except a comma (","), CR
 235 (0x0D), LF (0x0A), or NUL (0x00).
 236
 237 The text may not contain percent ("%") except in "percent encoding"
 238 sequences. To display a percent sign, use %25.
 239
 240 The text may not contain commas (",") because of constraints imposed
 241 by OpenVPN. Commas should be encoded using "percent encoding" (URL
 242 encoding): a '%' character followed by two hexadecimal digits, the
 243 high- and then low-nibble of the ASCII code for the character to be
 244 shown. Examples: a comma is encoded as %2C or %2c; a percent sign is
 245 encoded as %25.
 246
 247 Text containing comment characters # and ; must be enclosed in quotes to
 248 survive after option parsing by openvpn.
 249
 250 The insertion of line endings (CR, LF) in the text is discouraged
 251 because it is OS dependent. Instead, use the "msg" command, which
 252 appends a line ending appropriate for the OS on which the GUI is
 253 running.
 254
 255     Android: Planned.
 256
 257     Tunnelblick: Planned.
 258
 259     Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
 260                          (GUI version v11.22.0)
 261
 262 COMMAND -- msg-n
 263 ----------------
 264
 265 Syntax: msg-n text
 266
 267 The text is appended to any previous text from "msg"" or "msg-n""
 268 commands. (Like "msg" except that no newline is appended.)
 269
 270 See "COMMAND -- msg" for details about "text".
 271
 272     Android: Planned.
 273
 274     Tunnelblick: Planned.
 275
 276     Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
 277                          (GUI version v11.22.0)
 278
 279 COMMAND -- msg-notify
 280 ---------------------
 281
 282 Syntax: msg-notify title
 283
 284 The text from previous "msg" and/or "msg-n" commands is displayed to
 285 the user as a notification with title "title" and the previous text is
 286 forgotten.
 287
 288     Android: Planned.
 289
 290     Tunnelblick: Planned.
 291
 292     Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
 293                          (GUI version v11.22.0)
 294
 295 Note: The max length that will correctly display as a notification
 296 message is OS dependent.
 297
 298
 299 COMMAND -- msg-window title
 300 ---------------------------
 301
 302 Syntax: msg-window title
 303
 304 The text from previous "msg" and/or "msg-n" commands is displayed to
 305 the user in a non-modal popup window with title "title" and the
 306 previous text is forgotten.  How the title is displayed exactly is left
 307 to the implementation. Could be set as the window title or as a
 308 differently formatted text as the heading of the message, for example.
 309
 310     Android: Planned.
 311
 312     Tunnelblick: Planned.
 313
 314     Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
 315                          (GUI version v11.22.0)
 316
 317
 318 COMMAND -- save-passwords
 319 -------------------------
 320
 321 Syntax: save-passwords
 322
 323 The GUI is instructed to allow the user to save usernames, passwords
 324 and private keys for the configuration.
 325
 326 This command will be effective at startup only if present in the
 327 configuration file or as a command line option. If pushed from the
 328 server, saving passwords will be allowed in password prompts only
 329 after the initial prompt has been shown to the user.
 330
 331 This command typically has the effect of presenting the password
 332 dialogs to the user with a "save password" checkbox checked. The user
 333 may still uncheck it during the dialog.
 334
 335     Android: ??????
 336
 337     Tunnelblick: Planned. Tunnelblick ignores this command. Usernames,
 338 passwords, and private keys may be saved by default, and this command
 339 will not override the separate Tunnelblick global or per-configuration
 340 settings used to disable saving them.
 341
 342     Windows OpenVPN GUI: Supported since release 2.4.1 (GUI version 11.5.0)
 343
 344
 345 COMMAND -- setenv
 346 -----------------
 347
 348 Syntax: setenv name value
 349
 350 Sets an environment variable that will be available to the scripts run
 351 by the GUI.
 352
 353 This will set environment variable "OPENVPN_name" to value "value" for
 354 the scripts run by the GUI. "name" is changed to "OPENVPN_name" to
 355 prevent overwriting sensitive variables such as PATH. Variables are
 356 set in the order received, with later values replacing earlier ones
 357 for the same "name".
 358
 359 Names may include only alphanumeric characters and underscores. A
 360 "setenv" command with an invalid name will be ignored.
 361
 362     Android: ??????
 363
 364     Tunnelblick: Planned.
 365
 366     Windows OpenVPN GUI: supported since release v2.4.7 (GUI version v11.12.0)
 367 The variables set by "setenv" are merged with those for the process
 368 environment.  In case of duplicate names the one in the setenv list is
 369 chosen.