1
OpenVPN Management Interface Notes
2
----------------------------------
4
The OpenVPN Management interface allows OpenVPN to
5
be administratively controlled from an external program via
6
a TCP or unix domain socket.
8
The interface has been specifically designed for developers
9
who would like to programmatically or remotely control
10
an OpenVPN daemon, and can be used when OpenVPN is running
11
as a client or server.
13
The management interface is implemented using a client/server TCP
14
connection or unix domain socket where OpenVPN will listen on a
15
provided IP address and port for incoming management client connections.
17
The management protocol is currently cleartext without an explicit
18
security layer. For this reason, it is recommended that the
19
management interface either listen on a unix domain socket,
20
localhost (127.0.0.1), or on the local VPN address. It's possible
21
to remotely connect to the management interface over the VPN itself,
22
though some capabilities will be limited in this mode, such as the
23
ability to provide private key passwords.
25
The management interface is enabled in the OpenVPN
26
configuration file using the following directive:
30
See the man page for documentation on this and related
33
Once OpenVPN has started with the management layer enabled,
34
you can telnet to the management port (make sure to use
35
a telnet client which understands "raw" mode).
37
Once connected to the management port, you can use
38
the "help" command to list all commands.
43
The bytecount command is used to request real-time notification
44
of OpenVPN bandwidth usage.
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
52
If OpenVPN is running as a client, the bytecount notification
55
>BYTECOUNT:{BYTES_IN},{BYTES_OUT}
57
BYTES_IN is the number of bytes that have been received from
58
the server and BYTES_OUT is the number of bytes that have been
61
If OpenVPN is running as a server, the bytecount notification
64
>BYTECOUNT_CLI:{CID},{BYTES_IN},{BYTES_OUT}
66
CID is the Client ID, BYTES_IN is the number of bytes that have
67
been received from the client and BYTES_OUT is the number of
68
bytes that have been sent to the client.
70
Note that when the bytecount command is used on the server, every
71
connected client will report its bandwidth numbers once every n
74
When the client disconnects, the final bandwidth numbers will be
75
placed in the 'bytes_received' and 'bytes_sent' environmental variables
76
as included in the >CLIENT:DISCONNECT notification.
81
The echo capability is used to allow GUI-specific
82
parameters to be either embedded in the OpenVPN config file
83
or pushed to an OpenVPN client from a server.
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
93
For example, suppose you are developing a OpenVPN GUI and
94
you want to give the OpenVPN server the ability to ask
95
the GUI to forget any saved passwords.
97
In the OpenVPN server config file, add:
99
push "echo forget-passwords"
101
When the OpenVPN client receives its pulled list of directives
102
from the server, the "echo forget-passwords" directive will
103
be in the list, and it will cause the management interface
104
to save the "forget-passwords" string in its list of echo
107
The management client can use "echo all" to output the full
108
list of echoed parameters, "echo on" to turn on real-time
109
notification of echoed parameters via the ">ECHO:" prefix,
110
or "echo off" to turn off real-time notification.
112
When the GUI connects to the OpenVPN management socket, it
113
can issue an "echo all" command, which would produce output
116
1101519562,forget-passwords
119
Essentially the echo command allowed us to pass parameters from
120
the OpenVPN server to the OpenVPN client, and then to the
121
management client (such as a GUI). The large integer is the
122
unix date/time when the echo parameter was received.
124
If the management client had issued the command "echo on",
125
it would have enabled real-time notifications of echo
126
parameters. In this case, our "forget-passwords" message
127
would be output like this:
129
>ECHO:1101519562,forget-passwords
131
Like the log command, the echo command can atomically show
132
history while simultaneously activating real-time updates:
136
The size of the echo buffer is currently hardcoded to 100
139
COMMAND -- exit, quit
140
---------------------
142
Close the managment session, and resume listening on the
143
management port for connections from other clients. Currently,
144
the OpenVPN daemon can at most support a single management client
150
Print a summary of commands.
155
The hold command can be used to manipulate the hold flag,
156
or release OpenVPN from a hold state.
158
If the hold flag is set on initial startup or
159
restart, OpenVPN will hibernate prior to initializing
160
the tunnel until the management interface receives
161
a "hold release" command.
163
The --management-hold directive of OpenVPN can be used
164
to start OpenVPN with the hold flag set.
166
The hold flag setting is persistent and will not
167
be reset by restarts.
169
OpenVPN will indicate that it is in a hold state by
170
sending a real-time notification to the management
173
>HOLD:Waiting for hold release
177
hold -- show current hold flag, 0=off, 1=on.
178
hold on -- turn on hold flag so that future restarts
180
hold off -- turn off hold flag so that future restarts will
182
hold release -- leave hold state and start OpenVPN, but
183
do not alter the current hold flag setting.
188
In server mode, kill a particlar client instance.
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
197
Use the "status" command to see which clients are connected.
202
Show the OpenVPN log file. Only the most recent n lines
203
of the log file are cached by the management interface, where
204
n is controlled by the OpenVPN --management-log-cache directive.
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.
216
Real-time notification format:
218
Real-time log messages begin with the ">LOG:" prefix followed
219
by the following comma-separated fields:
221
(a) unix integer date/time,
222
(b) zero or more message flags in a single string:
233
Change the OpenVPN --mute parameter. The mute parameter is
234
used to silence repeating messages of the same message
239
mute 40 -- change the mute parameter to 40
240
mute -- show the current mute setting
245
(Windows Only) Produce output equivalent to the OpenVPN
246
--show-net directive. The output includes OpenVPN's view
247
of the system network adapter list and routing table based
248
on information returned by the Windows IP helper API.
253
Shows the process ID of the current OpenVPN process.
255
COMMAND -- password and username
256
--------------------------------
258
The password command is used to pass passwords to OpenVPN.
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
265
When OpenVPN needs a password from the management interface,
266
it will produce a real-time ">PASSWORD:" message.
270
>PASSWORD:Need 'Private Key' password
272
OpenVPN is indicating that it needs a password of type
275
The management client should respond to this query as follows:
277
password "Private Key" foo
281
>PASSWORD:Need 'Auth' username/password
283
OpenVPN needs a --auth-user-pass password. The management
284
client should respond:
289
The username/password itself can be in quotes, and special
290
characters such as double quote or backslash must be escaped,
293
password "Private Key" "foo\"bar"
295
The escaping rules are the same as for the config file.
296
See the "Command Parsing" section below for more info.
298
The PASSWORD real-time message type can also be used to
299
indicate password or other types of authentication failure:
301
Example 3: The private key password is incorrect and OpenVPN
304
>PASSWORD:Verification Failed: 'Private Key'
306
Example 4: The --auth-user-pass username/password failed,
307
and OpenVPN is exiting:
309
>PASSWORD:Verification Failed: 'Auth'
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.
315
>PASSWORD:Verification Failed: 'custom server-generated string'
317
COMMAND -- forget-passwords
318
---------------------------
320
The forget-passwords command will cause the daemon to forget passwords
321
entered during the session.
325
forget-passwords -- forget passwords entered so far.
330
The signal command will send a signal to the OpenVPN daemon.
331
The signal can be one of SIGHUP, SIGTERM, SIGUSR1, or SIGUSR2.
335
signal SIGUSR1 -- send a SIGUSR1 signal to daemon
340
Show the current OpenVPN state, show state history, or
341
enable real-time notification of state changes.
343
These are the OpenVPN states:
345
CONNECTING -- OpenVPN's initial state.
346
WAIT -- (Client only) Waiting for initial response
348
AUTH -- (Client only) Authenticating with server.
349
GET_CONFIG -- (Client only) Downloading configuration options
351
ASSIGN_IP -- Assigning IP address to virtual network
353
ADD_ROUTES -- Adding routes to system.
354
CONNECTED -- Initialization Sequence Completed.
355
RECONNECTING -- A restart has occurred.
356
EXITING -- A graceful exit is in progress.
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.
369
The output format consists of 4 comma-separated parameters:
370
(a) the integer unix date/time,
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
376
(e) optional address of remote server (OpenVPN 2.1 or higher).
378
Real-time state notifications will have a ">STATE:" prefix
384
Show current daemon status information, in the same format as
385
that produced by the OpenVPN --status directive.
389
status -- Show status information using the default status
392
status 3 -- Show status information using the format of
398
See the "password" section above.
403
Change the OpenVPN --verb parameter. The verb parameter
404
controls the output verbosity, and may range from 0 (no output)
405
to 15 (maximum output). See the OpenVPN man page for additional
406
info on verbosity levels.
410
verb 4 -- change the verb parameter to 4
411
mute -- show the current verb setting
416
Show the current OpenVPN and Management Interface versions.
419
COMMAND -- auth-retry
420
---------------------
422
Set the --auth-retry setting to control how OpenVPN responds to
423
username/password authentication errors. See the manual page
428
auth-retry interact -- Don't exit when bad username/passwords are entered.
429
Query for new input and retry.
431
COMMAND -- needok (OpenVPN 2.1 or higher)
432
------------------------------------------
434
Confirm a ">NEED-OK" real-time notification, normally used by
435
OpenVPN to block while waiting for a specific user action.
439
OpenVPN needs the user to insert a cryptographic token,
440
so it sends a real-time notification:
442
>NEED-OK:Need 'token-insertion-request' confirmation MSG:Please insert your cryptographic token
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:
449
needok token-insertion-request ok
451
needok token-insertion-request cancel
453
COMMAND -- needstr (OpenVPN 2.1 or higher)
454
-------------------------------------------
456
Confirm a ">NEED-STR" real-time notification, normally used by
457
OpenVPN to block while waiting for a specific user input.
461
OpenVPN needs the user to specify some input, so it sends a
462
real-time notification:
464
>NEED-STR:Need 'name' input MSG:Please specify your name
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:
473
COMMAND -- pkcs11-id-count (OpenVPN 2.1 or higher)
474
---------------------------------------------------
476
Retrieve available number of certificates.
483
COMMAND -- pkcs11-id-get (OpenVPN 2.1 or higher)
484
-------------------------------------------------
486
Retrieve certificate by index, the ID string should be provided
487
as PKCS#11 identity, the blob is BASE64 encoded certificate.
492
PKCS11ID-ENTRY:'1', ID:'<snip>', BLOB:'<snip>'
494
COMMAND -- client-auth (OpenVPN 2.1 or higher)
495
-----------------------------------------------
497
Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request and specify
498
"client-connect" configuration directives in a subsequent text block.
500
The OpenVPN server should have been started with the
501
--management-client-auth directive so that it will ask the management
502
interface to approve client connections.
505
client-auth {CID} {KID}
512
CID,KID -- client ID and Key ID. See documentation for ">CLIENT:"
513
notification for more info.
515
line_1 to line_n -- client-connect configuration text block, as would be
516
returned by a --client-connect script. The text block may be null, with
517
"END" immediately following the "client-auth" line (using a null text
518
block is equivalent to using the client-auth-nt command).
520
A client-connect configuration text block contains OpenVPN directives
521
that will be applied to the client instance object representing a newly
524
COMMAND -- client-auth-nt (OpenVPN 2.1 or higher)
525
--------------------------------------------------
527
Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request without specifying
528
client-connect configuration text.
530
The OpenVPN server should have been started with the
531
--management-client-auth directive so that it will ask the management
532
interface to approve client connections.
534
client-auth-nt {CID} {KID}
536
CID,KID -- client ID and Key ID. See documentation for ">CLIENT:"
537
notification for more info.
539
COMMAND -- client-deny (OpenVPN 2.1 or higher)
540
-----------------------------------------------
542
Deny a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request.
544
client-deny {CID} {KID} "reason-text" ["client-reason-text"]
546
CID,KID -- client ID and Key ID. See documentation for ">CLIENT:"
547
notification for more info.
549
reason-text: a human-readable message explaining why the authentication
550
request was denied. This message will be output to the OpenVPN log
553
client-reason-text: a message that will be sent to the client as
554
part of the AUTH_FAILED message.
556
Note that client-deny denies a specific Key ID (pertaining to a
557
TLS renegotiation). A client-deny command issued in response to
558
an initial TLS key negotiation (notified by ">CLIENT:CONNECT") will
559
terminate the client session after returning "AUTH-FAILED" to the client.
560
On the other hand, a client-deny command issued in response to
561
a TLS renegotiation (">CLIENT:REAUTH") will invalidate the renegotiated
562
key, however the TLS session associated with the currently active
563
key will continue to live for up to --tran-window seconds before
566
To immediately kill a client session, use "client-kill".
568
COMMAND -- client-kill (OpenVPN 2.1 or higher)
569
-----------------------------------------------
571
Immediately kill a client instance by CID.
575
CID -- client ID. See documentation for ">CLIENT:" notification for more
578
COMMAND -- client-pf (OpenVPN 2.1 or higher)
579
---------------------------------------------
581
Push a packet filter file to a specific client.
583
The OpenVPN server should have been started with the
584
--management-client-pf directive so that it will require that
585
VPN tunnel packets sent or received by client instances must
586
conform to that client's packet filter configuration.
595
CID -- client ID. See documentation for ">CLIENT:" notification for
598
line_1 to line_n -- the packet filter configuration file for this
601
Packet filter file grammar:
603
[CLIENTS DROP|ACCEPT]
607
[SUBNETS DROP|ACCEPT]
613
Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS | "unknown"
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.
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
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.
633
* The SUBNETS section currently only supports IPv4 addresses and
636
* A given client or subnet rule applies to both incoming and
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.
642
* The SUBNETS table is scanned sequentially, and the first item to
643
match is chosen. Therefore the SUBNETS table is NOT order-invariant.
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.
649
Example packet filter spec, as transmitted to the management interface:
661
The above example sets the packet filter policy for the client
662
identified by CID=42. This client may connect to all other clients
663
except those having a common name of "accounting" or "enigma".
664
The client may only interact with external IP addresses in the
665
10.0.0.0/8 subnet, however access to 10.46.79.9 is specifically
668
Another example packet filter spec, as transmitted to the
669
management interface:
681
The above example sets the packet filter policy for the client
682
identified by CID=99. This client may not connect to any other
683
clients except those having a common name of "public". It may
684
interact with any external IP address except those in the
685
10.0.0.0/8 netblock. However interaction with one address in
686
the 10.0.0.0/8 netblock is allowed: 10.10.0.1. Also, the client
687
may not interact with external IP addresses using an "unknown"
688
protocol (i.e. one that is not IPv4 or ARP).
693
(1) Command success/failure indicated by "SUCCESS: [text]" or
696
(2) For commands which print multiple lines of output,
697
the last line will be "END".
699
(3) Real-time messages will be in the form ">[source]:[text]",
700
where source is "CLIENT", "ECHO", "FATAL", "HOLD", "INFO", "LOG",
701
"NEED-OK", "PASSWORD", or "STATE".
703
REAL-TIME MESSAGE FORMAT
704
------------------------
706
The OpenVPN management interface produces two kinds of
707
output: (a) output from a command, or (b) asynchronous,
708
real-time output which can be generated at any time.
710
Real-time messages start with a '>' character in the first
711
column and are immediately followed by a type keyword
712
indicating the type of real-time message. The following
713
types are currently defined:
715
BYTECOUNT -- Real-time bandwidth usage notification, as enabled
716
by "bytecount" command when OpenVPN is running as
719
BYTECOUNT_CLI -- Real-time bandwidth usage notification per-client,
720
as enabled by "bytecount" command when OpenVPN is
723
CLIENT -- Notification of client connections and disconnections
724
on an OpenVPN server. Enabled when OpenVPN is started
725
with the --management-client-auth option. CLIENT
726
notifications may be multi-line. See "The CLIENT
727
notification" section below for detailed info.
729
ECHO -- Echo messages as controlled by the "echo" command.
731
FATAL -- A fatal error which is output to the log file just
732
prior to OpenVPN exiting.
734
HOLD -- Used to indicate that OpenVPN is in a holding state
735
and will not start until it receives a
736
"hold release" command.
738
INFO -- Informational messages such as the welcome message.
740
LOG -- Log message output as controlled by the "log" command.
742
NEED-OK -- OpenVPN needs the end user to do something, such as
743
insert a cryptographic token. The "needok" command can
744
be used to tell OpenVPN to continue.
746
NEED-STR -- OpenVPN needs information from end, such as
747
a certificate to use. The "needstr" command can
748
be used to tell OpenVPN to continue.
750
PASSWORD -- Used to tell the management client that OpenVPN
751
needs a password, also to indicate password
752
verification failure.
754
STATE -- Shows the current OpenVPN state, as controlled
755
by the "state" command.
757
The CLIENT notification
758
-----------------------
760
The ">CLIENT:" notification is enabled by the --management-client-auth
761
OpenVPN configuration directive that gives the management interface client
762
the responsibility to authenticate OpenVPN clients after their client
763
certificate has been verified. CLIENT notifications may be multi-line, and
764
the sequentiality of a given CLIENT notification, its associated environmental
765
variables, and the terminating ">CLIENT:ENV,END" line are guaranteed to be
768
CLIENT notification types:
770
(1) Notify new client connection ("CONNECT") or existing client TLS session
771
renegotiation ("REAUTH"). Information about the client is provided
772
by a list of environmental variables which are documented in the OpenVPN
773
man page. The environmental variables passed are equivalent to those
774
that would be passed to an --auth-user-pass-verify script.
776
>CLIENT:CONNECT|REAUTH,{CID},{KID}
777
>CLIENT:ENV,name1=val1
778
>CLIENT:ENV,name2=val2
782
(2) Notify successful client authentication and session initiation.
783
Called after CONNECT.
785
>CLIENT:ESTABLISHED,{CID}
786
>CLIENT:ENV,name1=val1
787
>CLIENT:ENV,name2=val2
791
(3) Notify existing client disconnection. The environmental variables passed
792
are equivalent to those that would be passed to a --client-disconnect
795
>CLIENT:DISCONNECT,{CID}
796
>CLIENT:ENV,name1=val1
797
>CLIENT:ENV,name2=val2
801
(4) Notify that a particular virtual address or subnet
802
is now associated with a specific client.
804
>CLIENT:ADDRESS,{CID},{ADDR},{PRI}
808
CID -- Client ID, numerical ID for each connecting client, sequence = 0,1,2,...
809
KID -- Key ID, numerical ID for the key associated with a given client TLS session,
811
PRI -- Primary (1) or Secondary (0) VPN address/subnet. All clients have at least
812
one primary IP address. Secondary address/subnets are associated with
813
client-specific "iroute" directives.
814
ADDR -- IPv4 address/subnet in the form 1.2.3.4 or 1.2.3.0/255.255.255.0
816
In the unlikely scenario of an extremely long-running OpenVPN server,
817
CID and KID should be assumed to recycle to 0 after (2^32)-1, however this
818
recycling behavior is guaranteed to be collision-free.
823
The management interface uses the same command line lexical analyzer
824
as is used by the OpenVPN config file parser.
826
Whitespace is a parameter separator.
828
Double quotation or single quotation characters ("", '') can be used
829
to enclose parameters containing whitespace.
831
Backslash-based shell escaping is performed, using the following
832
mappings, when not in single quotations:
834
\\ Maps to a single backslash character (\).
835
\" Pass a literal doublequote character ("), don't
836
interpret it as enclosing a parameter.
837
\[SPACE] Pass a literal space or tab character, don't
838
interpret it as a parameter delimiter.
added
removed
management/management-notes.txt
