1OpenVPN Management Interface Notes 2---------------------------------- 3 4The OpenVPN Management interface allows OpenVPN to 5be administratively controlled from an external program via 6a TCP or unix domain socket. 7 8The interface has been specifically designed for developers 9who would like to programmatically or remotely control 10an OpenVPN daemon, and can be used when OpenVPN is running 11as a client or server. 12 13The management interface is implemented using a client/server TCP 14connection or unix domain socket where OpenVPN will listen on a 15provided IP address and port for incoming management client connections. 16 17The management protocol is currently cleartext without an explicit 18security layer. For this reason, it is recommended that the 19management interface either listen on a unix domain socket, 20localhost (127.0.0.1), or on the local VPN address. It's possible 21to remotely connect to the management interface over the VPN itself, 22though some capabilities will be limited in this mode, such as the 23ability to provide private key passwords. 24 25The management interface is enabled in the OpenVPN 26configuration file using the following directive: 27 28--management 29 30See the man page for documentation on this and related 31directives. 32 33Once OpenVPN has started with the management layer enabled, 34you can telnet to the management port (make sure to use 35a telnet client which understands "raw" mode). 36 37Once connected to the management port, you can use 38the "help" command to list all commands. 39 40COMMAND -- bytecount 41-------------------- 42 43The bytecount command is used to request real-time notification 44of OpenVPN bandwidth usage. 45 46Command syntax: 47 48 bytecount n (where n > 0) -- set up automatic notification of 49 bandwidth usage once every n seconds 50 bytecount 0 -- turn off bytecount notifications 51 52If OpenVPN is running as a client, the bytecount notification 53will look like this: 54 55 >BYTECOUNT:{BYTES_IN},{BYTES_OUT} 56 57BYTES_IN is the number of bytes that have been received from 58the server and BYTES_OUT is the number of bytes that have been 59sent to the server. 60 61If OpenVPN is running as a server, the bytecount notification 62will look like this: 63 64 >BYTECOUNT_CLI:{CID},{BYTES_IN},{BYTES_OUT} 65 66CID is the Client ID, BYTES_IN is the number of bytes that have 67been received from the client and BYTES_OUT is the number of 68bytes that have been sent to the client. 69 70Note that when the bytecount command is used on the server, every 71connected client will report its bandwidth numbers once every n 72seconds. 73 74When the client disconnects, the final bandwidth numbers will be 75placed in the 'bytes_received' and 'bytes_sent' environmental variables 76as included in the >CLIENT:DISCONNECT notification. 77 78COMMAND -- echo 79--------------- 80 81The echo capability is used to allow GUI-specific 82parameters to be either embedded in the OpenVPN config file 83or pushed to an OpenVPN client from a server. 84 85Command examples: 86 87 echo on -- turn on real-time notification of echo messages 88 echo all -- print the current echo history list 89 echo off -- turn off real-time notification of echo messages 90 echo on all -- atomically enable real-time notification, 91 plus show any messages in history buffer 92 93For example, suppose you are developing a OpenVPN GUI and 94you want to give the OpenVPN server the ability to ask 95the GUI to forget any saved passwords. 96 97In the OpenVPN server config file, add: 98 99 push "echo forget-passwords" 100 101When the OpenVPN client receives its pulled list of directives 102from the server, the "echo forget-passwords" directive will 103be in the list, and it will cause the management interface 104to save the "forget-passwords" string in its list of echo 105parameters. 106 107The management client can use "echo all" to output the full 108list of echoed parameters, "echo on" to turn on real-time 109notification of echoed parameters via the ">ECHO:" prefix, 110or "echo off" to turn off real-time notification. 111 112When the GUI connects to the OpenVPN management socket, it 113can issue an "echo all" command, which would produce output 114like this: 115 116 1101519562,forget-passwords 117 END 118 119Essentially the echo command allowed us to pass parameters from 120the OpenVPN server to the OpenVPN client, and then to the 121management client (such as a GUI). The large integer is the 122unix date/time when the echo parameter was received. 123 124If the management client had issued the command "echo on", 125it would have enabled real-time notifications of echo 126parameters. In this case, our "forget-passwords" message 127would be output like this: 128 129 >ECHO:1101519562,forget-passwords 130 131Like the log command, the echo command can atomically show 132history while simultaneously activating real-time updates: 133 134 echo on all 135 136The size of the echo buffer is currently hardcoded to 100 137messages. 138 139COMMAND -- exit, quit 140--------------------- 141 142Close the managment session, and resume listening on the 143management port for connections from other clients. Currently, 144the OpenVPN daemon can at most support a single management client 145any one time. 146 147COMMAND -- help 148--------------- 149 150Print a summary of commands. 151 152COMMAND -- hold 153--------------- 154 155The hold command can be used to manipulate the hold flag, 156or release OpenVPN from a hold state. 157 158If the hold flag is set on initial startup or 159restart, OpenVPN will hibernate prior to initializing 160the tunnel until the management interface receives 161a "hold release" command. 162 163The --management-hold directive of OpenVPN can be used 164to start OpenVPN with the hold flag set. 165 166The hold flag setting is persistent and will not 167be reset by restarts. 168 169OpenVPN will indicate that it is in a hold state by 170sending a real-time notification to the management 171client: 172 173 >HOLD:Waiting for hold release 174 175Command examples: 176 177 hold -- show current hold flag, 0=off, 1=on. 178 hold on -- turn on hold flag so that future restarts 179 will hold. 180 hold off -- turn off hold flag so that future restarts will 181 not hold. 182 hold release -- leave hold state and start OpenVPN, but 183 do not alter the current hold flag setting. 184 185COMMAND -- kill 186--------------- 187 188In server mode, kill a particlar client instance. 189 190Command examples: 191 192 kill Test-Client -- kill the client instance having a 193 common name of "Test-Client". 194 kill 1.2.3.4:4000 -- kill the client instance having a 195 source address and port of 1.2.3.4:4000 196 197Use the "status" command to see which clients are connected. 198 199COMMAND -- log 200-------------- 201 202Show the OpenVPN log file. Only the most recent n lines 203of the log file are cached by the management interface, where 204n is controlled by the OpenVPN --management-log-cache directive. 205 206Command examples: 207 208 log on -- Enable real-time output of log messages. 209 log all -- Show currently cached log file history. 210 log on all -- Atomically show all currently cached log file 211 history then enable real-time notification of 212 new log file messages. 213 log off -- Turn off real-time notification of log messages. 214 log 20 -- Show the most recent 20 lines of log file history. 215 216Real-time notification format: 217 218Real-time log messages begin with the ">LOG:" prefix followed 219by the following comma-separated fields: 220 221 (a) unix integer date/time, 222 (b) zero or more message flags in a single string: 223 I -- informational 224 F -- fatal error 225 N -- non-fatal error 226 W -- warning 227 D -- debug, and 228 (c) message text. 229 230COMMAND -- mute 231--------------- 232 233Change the OpenVPN --mute parameter. The mute parameter is 234used to silence repeating messages of the same message 235category. 236 237Command examples: 238 239 mute 40 -- change the mute parameter to 40 240 mute -- show the current mute setting 241 242COMMAND -- net 243-------------- 244 245(Windows Only) Produce output equivalent to the OpenVPN 246--show-net directive. The output includes OpenVPN's view 247of the system network adapter list and routing table based 248on information returned by the Windows IP helper API. 249 250COMMAND -- pid 251-------------- 252 253Shows the process ID of the current OpenVPN process. 254 255COMMAND -- password and username 256-------------------------------- 257 258 The password command is used to pass passwords to OpenVPN. 259 260 If OpenVPN is run with the --management-query-passwords 261 directive, it will query the management interface for RSA 262 private key passwords and the --auth-user-pass 263 username/password. 264 265 When OpenVPN needs a password from the management interface, 266 it will produce a real-time ">PASSWORD:" message. 267 268 Example 1: 269 270 >PASSWORD:Need 'Private Key' password 271 272 OpenVPN is indicating that it needs a password of type 273 "Private Key". 274 275 The management client should respond to this query as follows: 276 277 password "Private Key" foo 278 279 Example 2: 280 281 >PASSWORD:Need 'Auth' username/password 282 283 OpenVPN needs a --auth-user-pass password. The management 284 client should respond: 285 286 username "Auth" foo 287 password "Auth" bar 288 289 The username/password itself can be in quotes, and special 290 characters such as double quote or backslash must be escaped, 291 for example, 292 293 password "Private Key" "foo\"bar" 294 295 The escaping rules are the same as for the config file. 296 See the "Command Parsing" section below for more info. 297 298 The PASSWORD real-time message type can also be used to 299 indicate password or other types of authentication failure: 300 301 Example 3: The private key password is incorrect and OpenVPN 302 is exiting: 303 304 >PASSWORD:Verification Failed: 'Private Key' 305 306 Example 4: The --auth-user-pass username/password failed, 307 and OpenVPN is exiting: 308 309 >PASSWORD:Verification Failed: 'Auth' 310 311 Example 5: The --auth-user-pass username/password failed, 312 and the server provided a custom client-reason-text string 313 using the client-deny server-side management interface command. 314 315 >PASSWORD:Verification Failed: 'custom server-generated string' 316 317COMMAND -- forget-passwords 318--------------------------- 319 320The forget-passwords command will cause the daemon to forget passwords 321entered during the session. 322 323Command example: 324 325 forget-passwords -- forget passwords entered so far. 326 327COMMAND -- signal 328----------------- 329 330The signal command will send a signal to the OpenVPN daemon. 331The signal can be one of SIGHUP, SIGTERM, SIGUSR1, or SIGUSR2. 332 333Command example: 334 335 signal SIGUSR1 -- send a SIGUSR1 signal to daemon 336 337COMMAND -- state 338---------------- 339 340Show the current OpenVPN state, show state history, or 341enable real-time notification of state changes. 342 343These are the OpenVPN states: 344 345CONNECTING -- OpenVPN's initial state. 346WAIT -- (Client only) Waiting for initial response 347 from server. 348AUTH -- (Client only) Authenticating with server. 349GET_CONFIG -- (Client only) Downloading configuration options 350 from server. 351ASSIGN_IP -- Assigning IP address to virtual network 352 interface. 353ADD_ROUTES -- Adding routes to system. 354CONNECTED -- Initialization Sequence Completed. 355RECONNECTING -- A restart has occurred. 356EXITING -- A graceful exit is in progress. 357 358Command examples: 359 360 state -- Print current OpenVPN state. 361 state on -- Enable real-time notification of state changes. 362 state off -- Disable real-time notification of state changes. 363 state all -- Print current state history. 364 state 3 -- Print the 3 most recent state transitions. 365 state on all -- Atomically show state history while at the 366 same time enable real-time state notification 367 of future state transitions. 368 369The output format consists of 4 comma-separated parameters: 370 (a) the integer unix date/time, 371 (b) the state name, 372 (c) optional descriptive string (used mostly on RECONNECTING 373 and EXITING to show the reason for the disconnect), 374 (d) optional TUN/TAP local IP address (shown for ASSIGN_IP 375 and CONNECTED), and 376 (e) optional address of remote server (OpenVPN 2.1 or higher). 377 378Real-time state notifications will have a ">STATE:" prefix 379prepended to them. 380 381COMMAND -- status 382----------------- 383 384Show current daemon status information, in the same format as 385that produced by the OpenVPN --status directive. 386 387Command examples: 388 389status -- Show status information using the default status 390 format version. 391 392status 3 -- Show status information using the format of 393 --status-version 3. 394 395COMMAND -- username 396------------------- 397 398See the "password" section above. 399 400COMMAND -- verb 401--------------- 402 403Change the OpenVPN --verb parameter. The verb parameter 404controls the output verbosity, and may range from 0 (no output) 405to 15 (maximum output). See the OpenVPN man page for additional 406info on verbosity levels. 407 408Command examples: 409 410 verb 4 -- change the verb parameter to 4 411 mute -- show the current verb setting 412 413COMMAND -- version 414------------------ 415 416Show the current OpenVPN and Management Interface versions. 417 418 419COMMAND -- auth-retry 420--------------------- 421 422Set the --auth-retry setting to control how OpenVPN responds to 423username/password authentication errors. See the manual page 424for more info. 425 426Command examples: 427 428 auth-retry interact -- Don't exit when bad username/passwords are entered. 429 Query for new input and retry. 430 431COMMAND -- needok (OpenVPN 2.1 or higher) 432------------------------------------------ 433 434Confirm a ">NEED-OK" real-time notification, normally used by 435OpenVPN to block while waiting for a specific user action. 436 437Example: 438 439 OpenVPN needs the user to insert a cryptographic token, 440 so it sends a real-time notification: 441 442 >NEED-OK:Need 'token-insertion-request' confirmation MSG:Please insert your cryptographic token 443 444 The management client, if it is a GUI, can flash a dialog 445 box containing the text after the "MSG:" marker to the user. 446 When the user acknowledges the dialog box, 447 the management client can issue this command: 448 449 needok token-insertion-request ok 450 or 451 needok token-insertion-request cancel 452 453COMMAND -- needstr (OpenVPN 2.1 or higher) 454------------------------------------------- 455 456Confirm a ">NEED-STR" real-time notification, normally used by 457OpenVPN to block while waiting for a specific user input. 458 459Example: 460 461 OpenVPN needs the user to specify some input, so it sends a 462 real-time notification: 463 464 >NEED-STR:Need 'name' input MSG:Please specify your name 465 466 The management client, if it is a GUI, can flash a dialog 467 box containing the text after the "MSG:" marker to the user. 468 When the user acknowledges the dialog box, 469 the management client can issue this command: 470 471 needstr name "John" 472 473COMMAND -- pkcs11-id-count (OpenVPN 2.1 or higher) 474--------------------------------------------------- 475 476Retrieve available number of certificates. 477 478Example: 479 480 pkcs11-id-count 481 >PKCS11ID-COUNT:5 482 483COMMAND -- pkcs11-id-get (OpenVPN 2.1 or higher) 484------------------------------------------------- 485 486Retrieve certificate by index, the ID string should be provided 487as PKCS#11 identity, the blob is BASE64 encoded certificate. 488 489Example: 490 491 pkcs11-id-get 1 492 PKCS11ID-ENTRY:'1', ID:'<snip>', BLOB:'<snip>' 493 494COMMAND -- client-auth (OpenVPN 2.1 or higher) 495----------------------------------------------- 496 497Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request and specify 498"client-connect" configuration directives in a subsequent text block. 499 500The OpenVPN server should have been started with the 501--management-client-auth directive so that it will ask the management 502interface to approve client connections. 503 504 505 client-auth {CID} {KID} 506 line_1 507 line_2 508 ... 509 line_n 510 END 511 512CID,KID -- client ID and Key ID. See documentation for ">CLIENT:" 513notification for more info. 514 515line_1 to line_n -- client-connect configuration text block, as would be 516returned by a --client-connect script. The text block may be null, with 517"END" immediately following the "client-auth" line (using a null text 518block is equivalent to using the client-auth-nt command). 519 520A client-connect configuration text block contains OpenVPN directives 521that will be applied to the client instance object representing a newly 522connected client. 523 524COMMAND -- client-auth-nt (OpenVPN 2.1 or higher) 525-------------------------------------------------- 526 527Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request without specifying 528client-connect configuration text. 529 530The OpenVPN server should have been started with the 531--management-client-auth directive so that it will ask the management 532interface to approve client connections. 533 534 client-auth-nt {CID} {KID} 535 536CID,KID -- client ID and Key ID. See documentation for ">CLIENT:" 537notification for more info. 538 539COMMAND -- client-deny (OpenVPN 2.1 or higher) 540----------------------------------------------- 541 542Deny a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request. 543 544 client-deny {CID} {KID} "reason-text" ["client-reason-text"] 545 546CID,KID -- client ID and Key ID. See documentation for ">CLIENT:" 547notification for more info. 548 549reason-text: a human-readable message explaining why the authentication 550request was denied. This message will be output to the OpenVPN log 551file or syslog. 552 553client-reason-text: a message that will be sent to the client as 554part of the AUTH_FAILED message. 555 556Note that client-deny denies a specific Key ID (pertaining to a 557TLS renegotiation). A client-deny command issued in response to 558an initial TLS key negotiation (notified by ">CLIENT:CONNECT") will 559terminate the client session after returning "AUTH-FAILED" to the client. 560On the other hand, a client-deny command issued in response to 561a TLS renegotiation (">CLIENT:REAUTH") will invalidate the renegotiated 562key, however the TLS session associated with the currently active 563key will continue to live for up to --tran-window seconds before 564expiration. 565 566To immediately kill a client session, use "client-kill". 567 568COMMAND -- client-kill (OpenVPN 2.1 or higher) 569----------------------------------------------- 570 571Immediately kill a client instance by CID. 572 573 client-kill {CID} 574 575CID -- client ID. See documentation for ">CLIENT:" notification for more 576info. 577 578COMMAND -- client-pf (OpenVPN 2.1 or higher) 579--------------------------------------------- 580 581Push a packet filter file to a specific client. 582 583The OpenVPN server should have been started with the 584--management-client-pf directive so that it will require that 585VPN tunnel packets sent or received by client instances must 586conform to that client's packet filter configuration. 587 588 client-pf {CID} 589 line_1 590 line_2 591 ... 592 line_n 593 END 594 595CID -- client ID. See documentation for ">CLIENT:" notification for 596more info. 597 598line_1 to line_n -- the packet filter configuration file for this 599client. 600 601Packet filter file grammar: 602 603 [CLIENTS DROP|ACCEPT] 604 {+|-}common_name1 605 {+|-}common_name2 606 . . . 607 [SUBNETS DROP|ACCEPT] 608 {+|-}subnet1 609 {+|-}subnet2 610 . . . 611 [END] 612 613 Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS | "unknown" 614 615 CLIENTS refers to the set of clients (by their common-name) which 616 this instance is allowed ('+') to connect to, or is excluded ('-') 617 from connecting to. Note that in the case of client-to-client 618 connections, such communication must be allowed by the packet filter 619 configuration files of both clients AND the --client-to-client 620 directive must have been specified in the OpenVPN server config. 621 622 SUBNETS refers to IP addresses or IP address subnets which this 623 client instance may connect to ('+') or is excluded ('-') from 624 connecting to, and applies to IPv4 and ARP packets. The special 625 "unknown" tag refers to packets of unknown type, i.e. a packet that 626 is not IPv4 or ARP. 627 628 DROP or ACCEPT defines default policy when there is no explicit match 629 for a common-name or subnet. The [END] tag must exist. 630 631 Notes: 632 633 * The SUBNETS section currently only supports IPv4 addresses and 634 subnets. 635 636 * A given client or subnet rule applies to both incoming and 637 outgoing packets. 638 639 * The CLIENTS list is order-invariant. Because the list is stored 640 as a hash-table, the order of the list does not affect its function. 641 642 * The SUBNETS table is scanned sequentially, and the first item to 643 match is chosen. Therefore the SUBNETS table is NOT order-invariant. 644 645 * No client-to-client communication is allowed unless the 646 --client-to-client configuration directive is enabled AND 647 the CLIENTS list of BOTH clients allows the communication. 648 649Example packet filter spec, as transmitted to the management interface: 650 651 client-pf 42 652 [CLIENTS ACCEPT] 653 -accounting 654 -enigma 655 [SUBNETS DROP] 656 -10.46.79.9 657 +10.0.0.0/8 658 [END] 659 END 660 661The above example sets the packet filter policy for the client 662identified by CID=42. This client may connect to all other clients 663except those having a common name of "accounting" or "enigma". 664The client may only interact with external IP addresses in the 66510.0.0.0/8 subnet, however access to 10.46.79.9 is specifically 666excluded. 667 668Another example packet filter spec, as transmitted to the 669management interface: 670 671 client-pf 99 672 [CLIENTS DENY] 673 +public 674 [SUBNETS ACCEPT] 675 +10.10.0.1 676 -10.0.0.0/8 677 -unknown 678 [END] 679 END 680 681The above example sets the packet filter policy for the client 682identified by CID=99. This client may not connect to any other 683clients except those having a common name of "public". It may 684interact with any external IP address except those in the 68510.0.0.0/8 netblock. However interaction with one address in 686the 10.0.0.0/8 netblock is allowed: 10.10.0.1. Also, the client 687may not interact with external IP addresses using an "unknown" 688protocol (i.e. one that is not IPv4 or ARP). 689 690COMMAND -- remote (OpenVPN AS 2.1.5/OpenVPN 2.3 or higher) 691-------------------------------------------- 692 693Provide remote host/port in response to a >REMOTE notification 694(client only). Requires that the --management-query-remote 695directive is used. 696 697 remote ACTION [HOST PORT] 698 699The "remote" command should only be given in response to a >REMOTE 700notification. For example, the following >REMOTE notification 701indicates that the client config file would ordinarily connect 702to vpn.example.com port 1194 (UDP): 703 704 >REMOTE:vpn.example.com,1194,udp 705 706Now, suppose we want to override the host and port, connecting 707instead to vpn.otherexample.com port 1234. After receiving 708the above notification, use this command: 709 710 remote MOD vpn.otherexample.com 1234 711 712To accept the same host and port as the client would ordinarily 713have connected to, use this command: 714 715 remote ACCEPT 716 717To skip the current connection entry and advance to the next one, 718use this command: 719 720 remote SKIP 721 722COMMAND -- proxy (OpenVPN 2.3 or higher) 723-------------------------------------------- 724 725Provide proxy server host/port and flags in response to a >PROXY 726notification (client only). Requires that the --management-query-proxy 727directive is used. 728 729 proxy TYPE HOST PORT ["nct"] 730 731The "proxy" command must only be given in response to a >PROXY 732notification. Use the "nct" flag if you only want to allow 733non-cleartext auth with the proxy server. The following >PROXY 734notification indicates that the client config file would ordinarily 735connect to the first --remote configured, vpn.example.com using TCP: 736 737 >PROXY:1,TCP,vpn.example.com 738 739Now, suppose we want to connect to the remote host using the proxy server 740proxy.intranet port 8080 with secure authentication only, if required. 741After receiving the above notification, use this command: 742 743 proxy HTTP proxy.intranet 8080 nct 744 745You can also use the SOCKS keyword to pass a SOCKS server address, like: 746 747 proxy SOCKS fe00::1 1080 748 749To accept connecting to the host and port directly, use this command: 750 751 proxy NONE 752 753COMMAND -- rsa-sig (OpenVPN 2.3 or higher) 754------------------------------------------ 755Provides support for external storage of the private key. Requires the 756--management-external-key option. This option can be used instead of "key" 757in client mode, and allows the client to run without the need to load the 758actual private key. When the SSL protocol needs to perform an RSA sign 759operation, the data to be signed will be sent to the management interface 760via a notification as follows: 761 762>RSA_SIGN:[BASE64_DATA] 763 764The management interface client should then sign BASE64_DATA 765using the private key and return the SSL signature as follows: 766 767rsa-sig 768[BASE64_SIG_LINE] 769. 770. 771. 772END 773 774Base64 encoded output of RSA_sign(NID_md5_sha1,... will provide a 775correct signature. 776 777This capability is intended to allow the use of arbitrary cryptographic 778service providers with OpenVPN via the management interface. 779 780 781OUTPUT FORMAT 782------------- 783 784(1) Command success/failure indicated by "SUCCESS: [text]" or 785 "ERROR: [text]". 786 787(2) For commands which print multiple lines of output, 788 the last line will be "END". 789 790(3) Real-time messages will be in the form ">[source]:[text]", 791 where source is "CLIENT", "ECHO", "FATAL", "HOLD", "INFO", "LOG", 792 "NEED-OK", "PASSWORD", or "STATE". 793 794REAL-TIME MESSAGE FORMAT 795------------------------ 796 797The OpenVPN management interface produces two kinds of 798output: (a) output from a command, or (b) asynchronous, 799real-time output which can be generated at any time. 800 801Real-time messages start with a '>' character in the first 802column and are immediately followed by a type keyword 803indicating the type of real-time message. The following 804types are currently defined: 805 806BYTECOUNT -- Real-time bandwidth usage notification, as enabled 807 by "bytecount" command when OpenVPN is running as 808 a client. 809 810BYTECOUNT_CLI -- Real-time bandwidth usage notification per-client, 811 as enabled by "bytecount" command when OpenVPN is 812 running as a server. 813 814CLIENT -- Notification of client connections and disconnections 815 on an OpenVPN server. Enabled when OpenVPN is started 816 with the --management-client-auth option. CLIENT 817 notifications may be multi-line. See "The CLIENT 818 notification" section below for detailed info. 819 820ECHO -- Echo messages as controlled by the "echo" command. 821 822FATAL -- A fatal error which is output to the log file just 823 prior to OpenVPN exiting. 824 825HOLD -- Used to indicate that OpenVPN is in a holding state 826 and will not start until it receives a 827 "hold release" command. 828 829INFO -- Informational messages such as the welcome message. 830 831LOG -- Log message output as controlled by the "log" command. 832 833NEED-OK -- OpenVPN needs the end user to do something, such as 834 insert a cryptographic token. The "needok" command can 835 be used to tell OpenVPN to continue. 836 837NEED-STR -- OpenVPN needs information from end, such as 838 a certificate to use. The "needstr" command can 839 be used to tell OpenVPN to continue. 840 841PASSWORD -- Used to tell the management client that OpenVPN 842 needs a password, also to indicate password 843 verification failure. 844 845STATE -- Shows the current OpenVPN state, as controlled 846 by the "state" command. 847 848The CLIENT notification 849----------------------- 850 851The ">CLIENT:" notification is enabled by the --management-client-auth 852OpenVPN configuration directive that gives the management interface client 853the responsibility to authenticate OpenVPN clients after their client 854certificate has been verified. CLIENT notifications may be multi-line, and 855the sequentiality of a given CLIENT notification, its associated environmental 856variables, and the terminating ">CLIENT:ENV,END" line are guaranteed to be 857atomic. 858 859CLIENT notification types: 860 861(1) Notify new client connection ("CONNECT") or existing client TLS session 862 renegotiation ("REAUTH"). Information about the client is provided 863 by a list of environmental variables which are documented in the OpenVPN 864 man page. The environmental variables passed are equivalent to those 865 that would be passed to an --auth-user-pass-verify script. 866 867 >CLIENT:CONNECT|REAUTH,{CID},{KID} 868 >CLIENT:ENV,name1=val1 869 >CLIENT:ENV,name2=val2 870 >CLIENT:ENV,... 871 >CLIENT:ENV,END 872 873(2) Notify successful client authentication and session initiation. 874 Called after CONNECT. 875 876 >CLIENT:ESTABLISHED,{CID} 877 >CLIENT:ENV,name1=val1 878 >CLIENT:ENV,name2=val2 879 >CLIENT:ENV,... 880 >CLIENT:ENV,END 881 882(3) Notify existing client disconnection. The environmental variables passed 883 are equivalent to those that would be passed to a --client-disconnect 884 script. 885 886 >CLIENT:DISCONNECT,{CID} 887 >CLIENT:ENV,name1=val1 888 >CLIENT:ENV,name2=val2 889 >CLIENT:ENV,... 890 >CLIENT:ENV,END 891 892(4) Notify that a particular virtual address or subnet 893 is now associated with a specific client. 894 895 >CLIENT:ADDRESS,{CID},{ADDR},{PRI} 896 897Variables: 898 899CID -- Client ID, numerical ID for each connecting client, sequence = 0,1,2,... 900KID -- Key ID, numerical ID for the key associated with a given client TLS session, 901 sequence = 0,1,2,... 902PRI -- Primary (1) or Secondary (0) VPN address/subnet. All clients have at least 903 one primary IP address. Secondary address/subnets are associated with 904 client-specific "iroute" directives. 905ADDR -- IPv4 address/subnet in the form 1.2.3.4 or 1.2.3.0/255.255.255.0 906 907In the unlikely scenario of an extremely long-running OpenVPN server, 908CID and KID should be assumed to recycle to 0 after (2^32)-1, however this 909recycling behavior is guaranteed to be collision-free. 910 911Command Parsing 912--------------- 913 914The management interface uses the same command line lexical analyzer 915as is used by the OpenVPN config file parser. 916 917Whitespace is a parameter separator. 918 919Double quotation or single quotation characters ("", '') can be used 920to enclose parameters containing whitespace. 921 922Backslash-based shell escaping is performed, using the following 923mappings, when not in single quotations: 924 925\\ Maps to a single backslash character (\). 926\" Pass a literal doublequote character ("), don't 927 interpret it as enclosing a parameter. 928\[SPACE] Pass a literal space or tab character, don't 929 interpret it as a parameter delimiter. 930 931Challenge/Response Protocol 932--------------------------- 933 934The OpenVPN Challenge/Response Protocol allows an OpenVPN server to 935generate challenge questions that are shown to the user, and to see 936the user's responses to those challenges. Based on the responses, the 937server can allow or deny access. 938 939In this way, the OpenVPN Challenge/Response Protocol can be used 940to implement multi-factor authentication. Two different 941variations on the challenge/response protocol are supported: the 942"Dynamic" and "Static" protocols. 943 944The basic idea of Challenge/Response is that the user must enter an 945additional piece of information, in addition to the username and 946password, to successfully authenticate. Normally, this information 947is used to prove that the user posesses a certain key-like device 948such as cryptographic token or a particular mobile phone. 949 950Dynamic protocol: 951 952The OpenVPN dynamic challenge/response protocol works by returning 953a specially formatted error message after initial successful 954authentication. This error message contains the challenge question, 955and is formatted as such: 956 957 CRV1:<flags>:<state_id>:<username_base64>:<challenge_text> 958 959flags: a series of optional, comma-separated flags: 960 E : echo the response when the user types it 961 R : a response is required 962 963state_id: an opaque string that should be returned to the server 964 along with the response. 965 966username_base64 : the username formatted as base64 967 968challenge_text : the challenge text to be shown to the user 969 970Example challenge: 971 972 CRV1:R,E:Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l:Y3Ix:Please enter token PIN 973 974After showing the challenge_text and getting a response from the user 975(if R flag is specified), the client should submit the following 976auth creds back to the OpenVPN server: 977 978Username: [username decoded from username_base64] 979Password: CRV1::<state_id>::<response_text> 980 981Where state_id is taken from the challenge request and response_text 982is what the user entered in response to the challenge_text. 983If the R flag is not present, response_text may be the empty 984string. 985 986Example response (suppose the user enters "8675309" for the token PIN): 987 988 Username: cr1 ("Y3Ix" base64 decoded) 989 Password: CRV1::Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l::8675309 990 991Static protocol: 992 993The static protocol differs from the dynamic protocol in that the 994challenge question and response field is given to the user in the 995initial username/password dialog, and the username, password, and 996response are delivered back to the server in a single transaction. 997 998The "static-challenge" directive is used to give the challenge text 999to OpenVPN and indicate whether or not the response should be echoed. 1000 1001When the "static-challenge" directive is used, the management 1002interface will respond as such when credentials are needed: 1003 1004 >PASSWORD:Need 'Auth' username/password SC:<ECHO>,<TEXT> 1005 1006 ECHO: "1" if response should be echoed, "0" to not echo 1007 TEXT: challenge text that should be shown to the user to 1008 facilitate their response 1009 1010For example: 1011 1012 >PASSWORD:Need 'Auth' username/password SC:1,Please enter token PIN 1013 1014The above notification indicates that OpenVPN needs a --auth-user-pass 1015password plus a response to a static challenge ("Please enter token PIN"). 1016The "1" after the "SC:" indicates that the response should be echoed. 1017 1018The management interface client in this case should add the static 1019challenge text to the auth dialog followed by a field for the user to 1020enter a response. Then the client should pack the password and response 1021together into an encoded password: 1022 1023 username "Auth" foo 1024 password "Auth" "SCRV1:<BASE64_PASSWORD>:<BASE64_RESPONSE>" 1025 1026For example, if the user entered "bar" as the password and 8675309 1027as the PIN, the following management interface commands should be 1028issued: 1029 1030 username "Auth" foo 1031 password "Auth" "SCRV1:Zm9v:ODY3NTMwOQ==" 1032 1033Client-side support for challenge/response protocol: 1034 1035Currently, the Access Server client and standalone OpenVPN 1036client support both static and dynamic challenge/response 1037protocols. However, any OpenVPN client UI that drives OpenVPN 1038via the management interface needs to add explicit support 1039for the challenge/response protocol. 1040