src/openvpn/management/management-notes.txt

   1 OpenVPN Management Interface Notes
   2 ----------------------------------
   3
   4 The OpenVPN Management interface allows OpenVPN to
   5 be administratively controlled from an external program via
   6 a TCP socket.
   7
   8 The interface has been specifically designed for GUI developers
   9 and those who would like to programmatically or remotely control
  10 an OpenVPN daemon.
  11
  12 The management interface is implemented using a client/server TCP
  13 connection, where OpenVPN will listen on a provided IP address
  14 and port for incoming management client connections.
  15
  16 The management protocol is currently cleartext without an explicit
  17 security layer.  For this reason, it is recommended that the
  18 management interface either listen on localhost (127.0.0.1)
  19 or on the local VPN address.  It's possible to remotely connect
  20 to the management interface over the VPN itself, though some
  21 capabilities will be limited in this mode, such as the ability
  22 to provide private key passwords.
  23
  24 Future versions of the management interface may allow out-of-band
  25 connections (i.e. not over the VPN) and secured with SSL/TLS.
  26
  27 The management interface is enabled in the OpenVPN
  28 configuration file using the following directives:
  29
  30 --management
  31 --management-query-passwords
  32 --management-log-cache
  33
  34 See the man page for documentation on these directives.
  35
  36 Once OpenVPN has started with the management layer enabled,
  37 you can telnet to the management port (make sure to use
  38 a telnet client which understands "raw" mode).
  39
  40 Once connected to the management port, you can use
  41 the "help" command to list all commands.
  42
  43 COMMAND -- echo
  44 ---------------
  45
  46 The echo capability is used to allow GUI-specific
  47 parameters to be either embedded in the OpenVPN config file
  48 or pushed to an OpenVPN client from a server.
  49
  50 Command examples:
  51
  52   echo on      -- turn on real-time notification of echo messages
  53   echo all     -- print the current echo history list
  54   echo off     -- turn off real-time notification of echo messages
  55   echo on all  -- atomically enable real-time notification,
  56                   plus show any messages in history buffer
  57
  58 For example, suppose you are developing a OpenVPN GUI and
  59 you want to give the OpenVPN server the ability to ask
  60 the GUI to forget any saved passwords.
  61
  62 In the OpenVPN server config file, add:
  63
  64   push "echo forget-passwords"
  65
  66 When the OpenVPN client receives its pulled list of directives
  67 from the server, the "echo forget-passwords" directive will
  68 be in the list, and it will cause the management interface
  69 to save the "forget-passwords" string in its list of echo
  70 parameters.
  71
  72 The management client can use "echo all" to output the full
  73 list of echoed parameters, "echo on" to turn on real-time
  74 notification of echoed parameters via the ">ECHO:" prefix,
  75 or "echo off" to turn off real-time notification.
  76
  77 When the GUI connects to the OpenVPN management socket, it
  78 can issue an "echo all" command, which would produce output
  79 like this:
  80
  81   1101519562,forget-passwords
  82   END
  83
  84 Essentially the echo command allowed us to pass parameters from
  85 the OpenVPN server to the OpenVPN client, and then to the
  86 management client (such as a GUI).  The large integer is the
  87 unix date/time when the echo parameter was received.
  88
  89 If the management client had issued the command "echo on",
  90 it would have enabled real-time notifications of echo
  91 parameters.  In this case, our "forget-passwords" message
  92 would be output like this:
  93
  94   >ECHO:1101519562,forget-passwords
  95
  96 Like the log command, the echo command can atomically show
  97 history while simultaneously activating real-time updates:
  98
  99   echo on all
 100
 101 The size of the echo buffer is currently hardcoded to 100
 102 messages.
 103
 104 COMMAND -- exit, quit
 105 ---------------------
 106
 107 Close the managment session, and resume listening on the
 108 management port for connections from other clients. Currently,
 109 the OpenVPN daemon can at most support a single management client
 110 any one time.
 111
 112 COMMAND -- help
 113 ---------------
 114
 115 Print a summary of commands.
 116
 117 COMMAND -- hold
 118 ---------------
 119
 120 The hold command can be used to manipulate the hold flag,
 121 or release OpenVPN from a hold state.
 122
 123 If the hold flag is set on initial startup or
 124 restart, OpenVPN will hibernate prior to initializing
 125 the tunnel until the management interface receives
 126 a "hold release" command.
 127
 128 The --management-hold directive of OpenVPN can be used
 129 to start OpenVPN with the hold flag set.
 130
 131 The hold flag setting is persistent and will not
 132 be reset by restarts.
 133
 134 OpenVPN will indicate that it is in a hold state by
 135 sending a real-time notification to the management
 136 client:
 137
 138   >HOLD:Waiting for hold release
 139
 140 Command examples:
 141
 142   hold         -- show current hold flag, 0=off, 1=on.
 143   hold on      -- turn on hold flag so that future restarts
 144                   will hold.
 145   hold off     -- turn off hold flag so that future restarts will
 146                   not hold.
 147   hold release -- leave hold state and start OpenVPN, but
 148                   do not alter the current hold flag setting.
 149
 150 COMMAND -- kill
 151 ---------------
 152
 153 In server mode, kill a particlar client instance.
 154
 155 Command examples:
 156
 157   kill Test-Client -- kill the client instance having a
 158                       common name of "Test-Client".
 159   kill 1.2.3.4:4000 -- kill the client instance having a
 160                        source address and port of 1.2.3.4:4000
 161
 162 Use the "status" command to see which clients are connected.
 163
 164 COMMAND -- log
 165 --------------
 166
 167 Show the OpenVPN log file.  Only the most recent n lines
 168 of the log file are cached by the management interface, where
 169 n is controlled by the OpenVPN --management-log-cache directive.
 170
 171 Command examples:
 172
 173   log on     -- Enable real-time output of log messages.
 174   log all    -- Show currently cached log file history.
 175   log on all -- Atomically show all currently cached log file
 176                 history then enable real-time notification of
 177                 new log file messages.
 178   log off    -- Turn off real-time notification of log messages.
 179   log 20     -- Show the most recent 20 lines of log file history.
 180
 181 Real-time notification format:
 182
 183 Real-time log messages begin with the ">LOG:" prefix followed
 184 by the following comma-separated fields:
 185
 186   (a) unix integer date/time,
 187   (b) zero or more message flags in a single string:
 188       I -- informational
 189       F -- fatal error
 190       N -- non-fatal error
 191       W -- warning
 192       D -- debug, and
 193   (c) message text.
 194
 195 COMMAND -- mute
 196 ---------------
 197
 198 Change the OpenVPN --mute parameter.  The mute parameter is
 199 used to silence repeating messages of the same message
 200 category.
 201
 202 Command examples:
 203
 204   mute 40 -- change the mute parameter to 40
 205   mute    -- show the current mute setting
 206
 207 COMMAND -- net
 208 --------------
 209
 210 (Windows Only) Produce output equivalent to the OpenVPN
 211 --show-net directive.  The output includes OpenVPN's view
 212 of the system network adapter list and routing table based
 213 on information returned by the Windows IP helper API.
 214
 215 COMMAND -- password and username
 216 --------------------------------
 217
 218   The password command is used to pass passwords to OpenVPN.
 219
 220   If OpenVPN is run with the --management-query-passwords
 221   directive, it will query the management interface for RSA
 222   private key passwords and the --auth-user-pass
 223   username/password.
 224
 225   When OpenVPN needs a password from the management interface,
 226   it will produce a real-time ">PASSWORD:" message.
 227
 228   Example 1:
 229
 230     >PASSWORD:Need 'Private Key' password
 231
 232   OpenVPN is indicating that it needs a password of type
 233   "Private Key".
 234
 235   The management client should respond to this query as follows:
 236
 237     password "Private Key" foo
 238
 239   Example 2:
 240
 241     >PASSWORD:Need 'Auth' username/password
 242
 243   OpenVPN needs a --auth-user-pass password.  The management
 244   client should respond:
 245
 246     username "Auth" foo
 247     password "Auth" bar
 248
 249   The username/password itself can be in quotes, and special
 250   characters such as double quote or backslash must be escaped,
 251   for example,
 252
 253     password "Private Key" "foo\"bar"
 254
 255   The escaping rules are the same as for the config file.
 256   See the "Command Parsing" section below for more info.
 257
 258   The PASSWORD real-time message type can also be used to
 259   indicate password or other types of authentication failure:
 260
 261   Example 3: The private key password is incorrect and OpenVPN
 262   is exiting:
 263
 264     >PASSWORD:Verification Failed: 'Private Key'
 265
 266   Example 4: The --auth-user-pass username/password failed,
 267   and OpenVPN is exiting:
 268
 269     >PASSWORD:Verification Failed: 'Auth'
 270
 271 COMMAND -- signal
 272 -----------------
 273
 274 The signal command will send a signal to the OpenVPN daemon.
 275 The signal can be one of SIGHUP, SIGTERM, SIGUSR1, or SIGUSR2.
 276
 277 Command example:
 278
 279   signal SIGUSR1 -- send a SIGUSR1 signal to daemon
 280
 281 COMMAND -- state
 282 ----------------
 283
 284 Show the current OpenVPN state, show state history, or
 285 enable real-time notification of state changes.
 286
 287 These are the OpenVPN states:
 288
 289 CONNECTING    -- OpenVPN's initial state.
 290 WAIT          -- (Client only) Waiting for initial response
 291                  from server.
 292 AUTH          -- (Client only) Authenticating with server.
 293 GET_CONFIG    -- (Client only) Downloading configuration options
 294                  from server.
 295 ASSIGN_IP     -- Assigning IP address to virtual network
 296                  interface.
 297 ADD_ROUTES    -- Adding routes to system.
 298 CONNECTED     -- Initialization Sequence Completed.
 299 RECONNECTING  -- A restart has occurred.
 300 EXITING       -- A graceful exit is in progress.
 301
 302 Command examples:
 303
 304   state        -- Print current OpenVPN state.
 305   state on     -- Enable real-time notification of state changes.
 306   state off    -- Disable real-time notification of state changes.
 307   state all    -- Print current state history.
 308   state 3      -- Print the 3 most recent state transitions.
 309   state on all -- Atomically show state history while at the
 310                   same time enable real-time state notification
 311                   of future state transitions.
 312
 313 The output format consists of 4 comma-separated parameters:
 314   (a) the integer unix date/time,
 315   (b) the state name,
 316   (c) optional descriptive string (used mostly on RECONNECTING
 317       and EXITING to show the reason for the disconnect), and
 318   (d) optional TUN/TAP local IP address (shown for ASSIGN_IP
 319       and CONNECTED).
 320
 321 Real-time state notifications will have a ">STATE:" prefix
 322 prepended to them.
 323
 324 COMMAND -- status
 325 -----------------
 326
 327 Show current daemon status information, in the same format as
 328 that produced by the OpenVPN --status directive.
 329
 330 Command examples:
 331
 332 status   -- Show status information using the default status
 333             format version.
 334
 335 status 2 -- Show status information using status format version 2.
 336
 337 COMMAND -- username
 338 -------------------
 339
 340 See the "password" section above.
 341
 342 COMMAND -- verb
 343 ---------------
 344
 345 Change the OpenVPN --verb parameter.  The verb parameter
 346 controls the output verbosity, and may range from 0 (no output)
 347 to 15 (maximum output).  See the OpenVPN man page for additional
 348 info on verbosity levels.
 349
 350 Command examples:
 351
 352   verb 4  -- change the verb parameter to 4
 353   mute    -- show the current verb setting
 354
 355 COMMAND -- version
 356 ------------------
 357
 358 Show the current OpenVPN and Management Interface versions.
 359
 360
 361 COMMAND -- auth-retry
 362 ---------------------
 363
 364 Set the --auth-retry setting to control how OpenVPN responds to
 365 username/password authentication errors.  See the manual page
 366 for more info.
 367
 368 Command examples:
 369
 370   auth-retry interact -- Don't exit when bad username/passwords are entered.
 371                          Query for new input and retry.
 372
 373 OUTPUT FORMAT
 374 -------------
 375
 376 (1) Command success/failure indicated by "SUCCESS: [text]" or
 377     "ERROR: [text]".
 378
 379 (2) For commands which print multiple lines of output,
 380     the last line will be "END".
 381
 382 (3) Real-time messages will be in the form ">[source]:[text]",
 383     where source is "ECHO", "FATAL", "HOLD", "INFO", "LOG",
 384     "PASSWORD", or "STATE".
 385
 386 REAL-TIME MESSAGE FORMAT
 387 ------------------------
 388
 389 The OpenVPN management interface produces two kinds of
 390 output: (a) output from a command, or (b) asynchronous,
 391 real-time output which can be generated at any time.
 392
 393 Real-time messages start with a '>' character in the first
 394 column and are immediately followed by a type keyword
 395 indicating the type of real-time message.  The following
 396 types are currently defined:
 397
 398 ECHO     -- Echo messages as controlled by the "echo" command.
 399
 400 FATAL    -- A fatal error which is output to the log file just
 401             prior to OpenVPN exiting.
 402
 403 HOLD     -- Used to indicate that OpenVPN is in a holding state
 404             and will not start until it receives a
 405             "hold release" command.
 406
 407 INFO     -- Informational messages such as the welcome message.
 408
 409 LOG      -- Log message output as controlled by the "log" command.
 410
 411 PASSWORD -- Used to tell the management client that OpenVPN
 412             needs a password, also to indicate password
 413             verification failure.
 414
 415 STATE    -- Shows the current OpenVPN state, as controlled
 416             by the "state" command.
 417
 418 Command Parsing
 419 ---------------
 420
 421 OpenVPN uses the same command line lexical analyzer as is used
 422 by the OpenVPN config file parser.
 423
 424 Whitespace is a parameter separator.
 425
 426 Double  quotation characters ("") can be used to enclose
 427 parameters containing whitespace
 428
 429 Backslash-based shell escaping is performed, using the following
 430 mappings
 431
 432 \\       Maps to a single backslash character (\).
 433 \"       Pass a literal doublequote character ("), don't
 434          interpret it as enclosing a parameter.
 435 \[SPACE] Pass a literal space or tab character, don't
 436          interpret it as a parameter delimiter.