summaryrefslogtreecommitdiff
path: root/doc/management-notes.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/management-notes.txt')
-rw-r--r--doc/management-notes.txt1039
1 files changed, 1039 insertions, 0 deletions
diff --git a/doc/management-notes.txt b/doc/management-notes.txt
new file mode 100644
index 0000000..79e71ad
--- /dev/null
+++ b/doc/management-notes.txt
@@ -0,0 +1,1039 @@
+OpenVPN Management Interface Notes
+----------------------------------
+
+The OpenVPN Management interface allows OpenVPN to
+be administratively controlled from an external program via
+a TCP or unix domain socket.
+
+The interface has been specifically designed for developers
+who would like to programmatically or remotely control
+an OpenVPN daemon, and can be used when OpenVPN is running
+as a client or server.
+
+The management interface is implemented using a client/server TCP
+connection or unix domain socket where OpenVPN will listen on a
+provided IP address and port for incoming management client connections.
+
+The management protocol is currently cleartext without an explicit
+security layer. For this reason, it is recommended that the
+management interface either listen on a unix domain socket,
+localhost (127.0.0.1), or on the local VPN address. It's possible
+to remotely connect to the management interface over the VPN itself,
+though some capabilities will be limited in this mode, such as the
+ability to provide private key passwords.
+
+The management interface is enabled in the OpenVPN
+configuration file using the following directive:
+
+--management
+
+See the man page for documentation on this and related
+directives.
+
+Once OpenVPN has started with the management layer enabled,
+you can telnet to the management port (make sure to use
+a telnet client which understands "raw" mode).
+
+Once connected to the management port, you can use
+the "help" command to list all commands.
+
+COMMAND -- bytecount
+--------------------
+
+The bytecount command is used to request real-time notification
+of OpenVPN bandwidth usage.
+
+Command syntax:
+
+ bytecount n (where n > 0) -- set up automatic notification of
+ bandwidth usage once every n seconds
+ bytecount 0 -- turn off bytecount notifications
+
+If OpenVPN is running as a client, the bytecount notification
+will look like this:
+
+ >BYTECOUNT:{BYTES_IN},{BYTES_OUT}
+
+BYTES_IN is the number of bytes that have been received from
+the server and BYTES_OUT is the number of bytes that have been
+sent to the server.
+
+If OpenVPN is running as a server, the bytecount notification
+will look like this:
+
+ >BYTECOUNT_CLI:{CID},{BYTES_IN},{BYTES_OUT}
+
+CID is the Client ID, BYTES_IN is the number of bytes that have
+been received from the client and BYTES_OUT is the number of
+bytes that have been sent to the client.
+
+Note that when the bytecount command is used on the server, every
+connected client will report its bandwidth numbers once every n
+seconds.
+
+When the client disconnects, the final bandwidth numbers will be
+placed in the 'bytes_received' and 'bytes_sent' environmental variables
+as included in the >CLIENT:DISCONNECT notification.
+
+COMMAND -- echo
+---------------
+
+The echo capability is used to allow GUI-specific
+parameters to be either embedded in the OpenVPN config file
+or pushed to an OpenVPN client from a server.
+
+Command examples:
+
+ echo on -- turn on real-time notification of echo messages
+ echo all -- print the current echo history list
+ echo off -- turn off real-time notification of echo messages
+ echo on all -- atomically enable real-time notification,
+ plus show any messages in history buffer
+
+For example, suppose you are developing a OpenVPN GUI and
+you want to give the OpenVPN server the ability to ask
+the GUI to forget any saved passwords.
+
+In the OpenVPN server config file, add:
+
+ push "echo forget-passwords"
+
+When the OpenVPN client receives its pulled list of directives
+from the server, the "echo forget-passwords" directive will
+be in the list, and it will cause the management interface
+to save the "forget-passwords" string in its list of echo
+parameters.
+
+The management client can use "echo all" to output the full
+list of echoed parameters, "echo on" to turn on real-time
+notification of echoed parameters via the ">ECHO:" prefix,
+or "echo off" to turn off real-time notification.
+
+When the GUI connects to the OpenVPN management socket, it
+can issue an "echo all" command, which would produce output
+like this:
+
+ 1101519562,forget-passwords
+ END
+
+Essentially the echo command allowed us to pass parameters from
+the OpenVPN server to the OpenVPN client, and then to the
+management client (such as a GUI). The large integer is the
+unix date/time when the echo parameter was received.
+
+If the management client had issued the command "echo on",
+it would have enabled real-time notifications of echo
+parameters. In this case, our "forget-passwords" message
+would be output like this:
+
+ >ECHO:1101519562,forget-passwords
+
+Like the log command, the echo command can atomically show
+history while simultaneously activating real-time updates:
+
+ echo on all
+
+The size of the echo buffer is currently hardcoded to 100
+messages.
+
+COMMAND -- exit, quit
+---------------------
+
+Close the managment session, and resume listening on the
+management port for connections from other clients. Currently,
+the OpenVPN daemon can at most support a single management client
+any one time.
+
+COMMAND -- help
+---------------
+
+Print a summary of commands.
+
+COMMAND -- hold
+---------------
+
+The hold command can be used to manipulate the hold flag,
+or release OpenVPN from a hold state.
+
+If the hold flag is set on initial startup or
+restart, OpenVPN will hibernate prior to initializing
+the tunnel until the management interface receives
+a "hold release" command.
+
+The --management-hold directive of OpenVPN can be used
+to start OpenVPN with the hold flag set.
+
+The hold flag setting is persistent and will not
+be reset by restarts.
+
+OpenVPN will indicate that it is in a hold state by
+sending a real-time notification to the management
+client:
+
+ >HOLD:Waiting for hold release
+
+Command examples:
+
+ hold -- show current hold flag, 0=off, 1=on.
+ hold on -- turn on hold flag so that future restarts
+ will hold.
+ hold off -- turn off hold flag so that future restarts will
+ not hold.
+ hold release -- leave hold state and start OpenVPN, but
+ do not alter the current hold flag setting.
+
+COMMAND -- kill
+---------------
+
+In server mode, kill a particlar client instance.
+
+Command examples:
+
+ kill Test-Client -- kill the client instance having a
+ common name of "Test-Client".
+ kill 1.2.3.4:4000 -- kill the client instance having a
+ source address and port of 1.2.3.4:4000
+
+Use the "status" command to see which clients are connected.
+
+COMMAND -- log
+--------------
+
+Show the OpenVPN log file. Only the most recent n lines
+of the log file are cached by the management interface, where
+n is controlled by the OpenVPN --management-log-cache directive.
+
+Command examples:
+
+ log on -- Enable real-time output of log messages.
+ log all -- Show currently cached log file history.
+ log on all -- Atomically show all currently cached log file
+ history then enable real-time notification of
+ new log file messages.
+ log off -- Turn off real-time notification of log messages.
+ log 20 -- Show the most recent 20 lines of log file history.
+
+Real-time notification format:
+
+Real-time log messages begin with the ">LOG:" prefix followed
+by the following comma-separated fields:
+
+ (a) unix integer date/time,
+ (b) zero or more message flags in a single string:
+ I -- informational
+ F -- fatal error
+ N -- non-fatal error
+ W -- warning
+ D -- debug, and
+ (c) message text.
+
+COMMAND -- mute
+---------------
+
+Change the OpenVPN --mute parameter. The mute parameter is
+used to silence repeating messages of the same message
+category.
+
+Command examples:
+
+ mute 40 -- change the mute parameter to 40
+ mute -- show the current mute setting
+
+COMMAND -- net
+--------------
+
+(Windows Only) Produce output equivalent to the OpenVPN
+--show-net directive. The output includes OpenVPN's view
+of the system network adapter list and routing table based
+on information returned by the Windows IP helper API.
+
+COMMAND -- pid
+--------------
+
+Shows the process ID of the current OpenVPN process.
+
+COMMAND -- password and username
+--------------------------------
+
+ The password command is used to pass passwords to OpenVPN.
+
+ If OpenVPN is run with the --management-query-passwords
+ directive, it will query the management interface for RSA
+ private key passwords and the --auth-user-pass
+ username/password.
+
+ When OpenVPN needs a password from the management interface,
+ it will produce a real-time ">PASSWORD:" message.
+
+ Example 1:
+
+ >PASSWORD:Need 'Private Key' password
+
+ OpenVPN is indicating that it needs a password of type
+ "Private Key".
+
+ The management client should respond to this query as follows:
+
+ password "Private Key" foo
+
+ Example 2:
+
+ >PASSWORD:Need 'Auth' username/password
+
+ OpenVPN needs a --auth-user-pass password. The management
+ client should respond:
+
+ username "Auth" foo
+ password "Auth" bar
+
+ The username/password itself can be in quotes, and special
+ characters such as double quote or backslash must be escaped,
+ for example,
+
+ password "Private Key" "foo\"bar"
+
+ The escaping rules are the same as for the config file.
+ See the "Command Parsing" section below for more info.
+
+ The PASSWORD real-time message type can also be used to
+ indicate password or other types of authentication failure:
+
+ Example 3: The private key password is incorrect and OpenVPN
+ is exiting:
+
+ >PASSWORD:Verification Failed: 'Private Key'
+
+ Example 4: The --auth-user-pass username/password failed,
+ and OpenVPN is exiting:
+
+ >PASSWORD:Verification Failed: 'Auth'
+
+ Example 5: The --auth-user-pass username/password failed,
+ and the server provided a custom client-reason-text string
+ using the client-deny server-side management interface command.
+
+ >PASSWORD:Verification Failed: 'custom server-generated string'
+
+COMMAND -- forget-passwords
+---------------------------
+
+The forget-passwords command will cause the daemon to forget passwords
+entered during the session.
+
+Command example:
+
+ forget-passwords -- forget passwords entered so far.
+
+COMMAND -- signal
+-----------------
+
+The signal command will send a signal to the OpenVPN daemon.
+The signal can be one of SIGHUP, SIGTERM, SIGUSR1, or SIGUSR2.
+
+Command example:
+
+ signal SIGUSR1 -- send a SIGUSR1 signal to daemon
+
+COMMAND -- state
+----------------
+
+Show the current OpenVPN state, show state history, or
+enable real-time notification of state changes.
+
+These are the OpenVPN states:
+
+CONNECTING -- OpenVPN's initial state.
+WAIT -- (Client only) Waiting for initial response
+ from server.
+AUTH -- (Client only) Authenticating with server.
+GET_CONFIG -- (Client only) Downloading configuration options
+ from server.
+ASSIGN_IP -- Assigning IP address to virtual network
+ interface.
+ADD_ROUTES -- Adding routes to system.
+CONNECTED -- Initialization Sequence Completed.
+RECONNECTING -- A restart has occurred.
+EXITING -- A graceful exit is in progress.
+
+Command examples:
+
+ state -- Print current OpenVPN state.
+ state on -- Enable real-time notification of state changes.
+ state off -- Disable real-time notification of state changes.
+ state all -- Print current state history.
+ state 3 -- Print the 3 most recent state transitions.
+ state on all -- Atomically show state history while at the
+ same time enable real-time state notification
+ of future state transitions.
+
+The output format consists of 4 comma-separated parameters:
+ (a) the integer unix date/time,
+ (b) the state name,
+ (c) optional descriptive string (used mostly on RECONNECTING
+ and EXITING to show the reason for the disconnect),
+ (d) optional TUN/TAP local IP address (shown for ASSIGN_IP
+ and CONNECTED), and
+ (e) optional address of remote server (OpenVPN 2.1 or higher).
+
+Real-time state notifications will have a ">STATE:" prefix
+prepended to them.
+
+COMMAND -- status
+-----------------
+
+Show current daemon status information, in the same format as
+that produced by the OpenVPN --status directive.
+
+Command examples:
+
+status -- Show status information using the default status
+ format version.
+
+status 3 -- Show status information using the format of
+ --status-version 3.
+
+COMMAND -- username
+-------------------
+
+See the "password" section above.
+
+COMMAND -- verb
+---------------
+
+Change the OpenVPN --verb parameter. The verb parameter
+controls the output verbosity, and may range from 0 (no output)
+to 15 (maximum output). See the OpenVPN man page for additional
+info on verbosity levels.
+
+Command examples:
+
+ verb 4 -- change the verb parameter to 4
+ mute -- show the current verb setting
+
+COMMAND -- version
+------------------
+
+Show the current OpenVPN and Management Interface versions.
+
+
+COMMAND -- auth-retry
+---------------------
+
+Set the --auth-retry setting to control how OpenVPN responds to
+username/password authentication errors. See the manual page
+for more info.
+
+Command examples:
+
+ auth-retry interact -- Don't exit when bad username/passwords are entered.
+ Query for new input and retry.
+
+COMMAND -- needok (OpenVPN 2.1 or higher)
+------------------------------------------
+
+Confirm a ">NEED-OK" real-time notification, normally used by
+OpenVPN to block while waiting for a specific user action.
+
+Example:
+
+ OpenVPN needs the user to insert a cryptographic token,
+ so it sends a real-time notification:
+
+ >NEED-OK:Need 'token-insertion-request' confirmation MSG:Please insert your cryptographic token
+
+ The management client, if it is a GUI, can flash a dialog
+ box containing the text after the "MSG:" marker to the user.
+ When the user acknowledges the dialog box,
+ the management client can issue this command:
+
+ needok token-insertion-request ok
+ or
+ needok token-insertion-request cancel
+
+COMMAND -- needstr (OpenVPN 2.1 or higher)
+-------------------------------------------
+
+Confirm a ">NEED-STR" real-time notification, normally used by
+OpenVPN to block while waiting for a specific user input.
+
+Example:
+
+ OpenVPN needs the user to specify some input, so it sends a
+ real-time notification:
+
+ >NEED-STR:Need 'name' input MSG:Please specify your name
+
+ The management client, if it is a GUI, can flash a dialog
+ box containing the text after the "MSG:" marker to the user.
+ When the user acknowledges the dialog box,
+ the management client can issue this command:
+
+ needstr name "John"
+
+COMMAND -- pkcs11-id-count (OpenVPN 2.1 or higher)
+---------------------------------------------------
+
+Retrieve available number of certificates.
+
+Example:
+
+ pkcs11-id-count
+ >PKCS11ID-COUNT:5
+
+COMMAND -- pkcs11-id-get (OpenVPN 2.1 or higher)
+-------------------------------------------------
+
+Retrieve certificate by index, the ID string should be provided
+as PKCS#11 identity, the blob is BASE64 encoded certificate.
+
+Example:
+
+ pkcs11-id-get 1
+ PKCS11ID-ENTRY:'1', ID:'<snip>', BLOB:'<snip>'
+
+COMMAND -- client-auth (OpenVPN 2.1 or higher)
+-----------------------------------------------
+
+Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request and specify
+"client-connect" configuration directives in a subsequent text block.
+
+The OpenVPN server should have been started with the
+--management-client-auth directive so that it will ask the management
+interface to approve client connections.
+
+
+ client-auth {CID} {KID}
+ line_1
+ line_2
+ ...
+ line_n
+ END
+
+CID,KID -- client ID and Key ID. See documentation for ">CLIENT:"
+notification for more info.
+
+line_1 to line_n -- client-connect configuration text block, as would be
+returned by a --client-connect script. The text block may be null, with
+"END" immediately following the "client-auth" line (using a null text
+block is equivalent to using the client-auth-nt command).
+
+A client-connect configuration text block contains OpenVPN directives
+that will be applied to the client instance object representing a newly
+connected client.
+
+COMMAND -- client-auth-nt (OpenVPN 2.1 or higher)
+--------------------------------------------------
+
+Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request without specifying
+client-connect configuration text.
+
+The OpenVPN server should have been started with the
+--management-client-auth directive so that it will ask the management
+interface to approve client connections.
+
+ client-auth-nt {CID} {KID}
+
+CID,KID -- client ID and Key ID. See documentation for ">CLIENT:"
+notification for more info.
+
+COMMAND -- client-deny (OpenVPN 2.1 or higher)
+-----------------------------------------------
+
+Deny a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request.
+
+ client-deny {CID} {KID} "reason-text" ["client-reason-text"]
+
+CID,KID -- client ID and Key ID. See documentation for ">CLIENT:"
+notification for more info.
+
+reason-text: a human-readable message explaining why the authentication
+request was denied. This message will be output to the OpenVPN log
+file or syslog.
+
+client-reason-text: a message that will be sent to the client as
+part of the AUTH_FAILED message.
+
+Note that client-deny denies a specific Key ID (pertaining to a
+TLS renegotiation). A client-deny command issued in response to
+an initial TLS key negotiation (notified by ">CLIENT:CONNECT") will
+terminate the client session after returning "AUTH-FAILED" to the client.
+On the other hand, a client-deny command issued in response to
+a TLS renegotiation (">CLIENT:REAUTH") will invalidate the renegotiated
+key, however the TLS session associated with the currently active
+key will continue to live for up to --tran-window seconds before
+expiration.
+
+To immediately kill a client session, use "client-kill".
+
+COMMAND -- client-kill (OpenVPN 2.1 or higher)
+-----------------------------------------------
+
+Immediately kill a client instance by CID.
+
+ client-kill {CID}
+
+CID -- client ID. See documentation for ">CLIENT:" notification for more
+info.
+
+COMMAND -- client-pf (OpenVPN 2.1 or higher)
+---------------------------------------------
+
+Push a packet filter file to a specific client.
+
+The OpenVPN server should have been started with the
+--management-client-pf directive so that it will require that
+VPN tunnel packets sent or received by client instances must
+conform to that client's packet filter configuration.
+
+ client-pf {CID}
+ line_1
+ line_2
+ ...
+ line_n
+ END
+
+CID -- client ID. See documentation for ">CLIENT:" notification for
+more info.
+
+line_1 to line_n -- the packet filter configuration file for this
+client.
+
+Packet filter file grammar:
+
+ [CLIENTS DROP|ACCEPT]
+ {+|-}common_name1
+ {+|-}common_name2
+ . . .
+ [SUBNETS DROP|ACCEPT]
+ {+|-}subnet1
+ {+|-}subnet2
+ . . .
+ [END]
+
+ Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS | "unknown"
+
+ CLIENTS refers to the set of clients (by their common-name) which
+ this instance is allowed ('+') to connect to, or is excluded ('-')
+ from connecting to. Note that in the case of client-to-client
+ connections, such communication must be allowed by the packet filter
+ configuration files of both clients AND the --client-to-client
+ directive must have been specified in the OpenVPN server config.
+
+ SUBNETS refers to IP addresses or IP address subnets which this
+ client instance may connect to ('+') or is excluded ('-') from
+ connecting to, and applies to IPv4 and ARP packets. The special
+ "unknown" tag refers to packets of unknown type, i.e. a packet that
+ is not IPv4 or ARP.
+
+ DROP or ACCEPT defines default policy when there is no explicit match
+ for a common-name or subnet. The [END] tag must exist.
+
+ Notes:
+
+ * The SUBNETS section currently only supports IPv4 addresses and
+ subnets.
+
+ * A given client or subnet rule applies to both incoming and
+ outgoing packets.
+
+ * The CLIENTS list is order-invariant. Because the list is stored
+ as a hash-table, the order of the list does not affect its function.
+
+ * The SUBNETS table is scanned sequentially, and the first item to
+ match is chosen. Therefore the SUBNETS table is NOT order-invariant.
+
+ * No client-to-client communication is allowed unless the
+ --client-to-client configuration directive is enabled AND
+ the CLIENTS list of BOTH clients allows the communication.
+
+Example packet filter spec, as transmitted to the management interface:
+
+ client-pf 42
+ [CLIENTS ACCEPT]
+ -accounting
+ -enigma
+ [SUBNETS DROP]
+ -10.46.79.9
+ +10.0.0.0/8
+ [END]
+ END
+
+The above example sets the packet filter policy for the client
+identified by CID=42. This client may connect to all other clients
+except those having a common name of "accounting" or "enigma".
+The client may only interact with external IP addresses in the
+10.0.0.0/8 subnet, however access to 10.46.79.9 is specifically
+excluded.
+
+Another example packet filter spec, as transmitted to the
+management interface:
+
+ client-pf 99
+ [CLIENTS DENY]
+ +public
+ [SUBNETS ACCEPT]
+ +10.10.0.1
+ -10.0.0.0/8
+ -unknown
+ [END]
+ END
+
+The above example sets the packet filter policy for the client
+identified by CID=99. This client may not connect to any other
+clients except those having a common name of "public". It may
+interact with any external IP address except those in the
+10.0.0.0/8 netblock. However interaction with one address in
+the 10.0.0.0/8 netblock is allowed: 10.10.0.1. Also, the client
+may not interact with external IP addresses using an "unknown"
+protocol (i.e. one that is not IPv4 or ARP).
+
+COMMAND -- remote (OpenVPN AS 2.1.5/OpenVPN 2.3 or higher)
+--------------------------------------------
+
+Provide remote host/port in response to a >REMOTE notification
+(client only). Requires that the --management-query-remote
+directive is used.
+
+ remote ACTION [HOST PORT]
+
+The "remote" command should only be given in response to a >REMOTE
+notification. For example, the following >REMOTE notification
+indicates that the client config file would ordinarily connect
+to vpn.example.com port 1194 (UDP):
+
+ >REMOTE:vpn.example.com,1194,udp
+
+Now, suppose we want to override the host and port, connecting
+instead to vpn.otherexample.com port 1234. After receiving
+the above notification, use this command:
+
+ remote MOD vpn.otherexample.com 1234
+
+To accept the same host and port as the client would ordinarily
+have connected to, use this command:
+
+ remote ACCEPT
+
+To skip the current connection entry and advance to the next one,
+use this command:
+
+ remote SKIP
+
+COMMAND -- proxy (OpenVPN 2.3 or higher)
+--------------------------------------------
+
+Provide proxy server host/port and flags in response to a >PROXY
+notification (client only). Requires that the --management-query-proxy
+directive is used.
+
+ proxy TYPE HOST PORT ["nct"]
+
+The "proxy" command must only be given in response to a >PROXY
+notification. Use the "nct" flag if you only want to allow
+non-cleartext auth with the proxy server. The following >PROXY
+notification indicates that the client config file would ordinarily
+connect to the first --remote configured, vpn.example.com using TCP:
+
+ >PROXY:1,TCP,vpn.example.com
+
+Now, suppose we want to connect to the remote host using the proxy server
+proxy.intranet port 8080 with secure authentication only, if required.
+After receiving the above notification, use this command:
+
+ proxy HTTP proxy.intranet 8080 nct
+
+You can also use the SOCKS keyword to pass a SOCKS server address, like:
+
+ proxy SOCKS fe00::1 1080
+
+To accept connecting to the host and port directly, use this command:
+
+ proxy NONE
+
+COMMAND -- rsa-sig (OpenVPN 2.3 or higher)
+------------------------------------------
+Provides support for external storage of the private key. Requires the
+--management-external-key option. This option can be used instead of "key"
+in client mode, and allows the client to run without the need to load the
+actual private key. When the SSL protocol needs to perform an RSA sign
+operation, the data to be signed will be sent to the management interface
+via a notification as follows:
+
+>RSA_SIGN:[BASE64_DATA]
+
+The management interface client should then sign BASE64_DATA
+using the private key and return the SSL signature as follows:
+
+rsa-sig
+[BASE64_SIG_LINE]
+.
+.
+.
+END
+
+Base64 encoded output of RSA_sign(NID_md5_sha1,... will provide a
+correct signature.
+
+This capability is intended to allow the use of arbitrarycryptographic
+service providers with OpenVPN via the management interface.
+
+
+OUTPUT FORMAT
+-------------
+
+(1) Command success/failure indicated by "SUCCESS: [text]" or
+ "ERROR: [text]".
+
+(2) For commands which print multiple lines of output,
+ the last line will be "END".
+
+(3) Real-time messages will be in the form ">[source]:[text]",
+ where source is "CLIENT", "ECHO", "FATAL", "HOLD", "INFO", "LOG",
+ "NEED-OK", "PASSWORD", or "STATE".
+
+REAL-TIME MESSAGE FORMAT
+------------------------
+
+The OpenVPN management interface produces two kinds of
+output: (a) output from a command, or (b) asynchronous,
+real-time output which can be generated at any time.
+
+Real-time messages start with a '>' character in the first
+column and are immediately followed by a type keyword
+indicating the type of real-time message. The following
+types are currently defined:
+
+BYTECOUNT -- Real-time bandwidth usage notification, as enabled
+ by "bytecount" command when OpenVPN is running as
+ a client.
+
+BYTECOUNT_CLI -- Real-time bandwidth usage notification per-client,
+ as enabled by "bytecount" command when OpenVPN is
+ running as a server.
+
+CLIENT -- Notification of client connections and disconnections
+ on an OpenVPN server. Enabled when OpenVPN is started
+ with the --management-client-auth option. CLIENT
+ notifications may be multi-line. See "The CLIENT
+ notification" section below for detailed info.
+
+ECHO -- Echo messages as controlled by the "echo" command.
+
+FATAL -- A fatal error which is output to the log file just
+ prior to OpenVPN exiting.
+
+HOLD -- Used to indicate that OpenVPN is in a holding state
+ and will not start until it receives a
+ "hold release" command.
+
+INFO -- Informational messages such as the welcome message.
+
+LOG -- Log message output as controlled by the "log" command.
+
+NEED-OK -- OpenVPN needs the end user to do something, such as
+ insert a cryptographic token. The "needok" command can
+ be used to tell OpenVPN to continue.
+
+NEED-STR -- OpenVPN needs information from end, such as
+ a certificate to use. The "needstr" command can
+ be used to tell OpenVPN to continue.
+
+PASSWORD -- Used to tell the management client that OpenVPN
+ needs a password, also to indicate password
+ verification failure.
+
+STATE -- Shows the current OpenVPN state, as controlled
+ by the "state" command.
+
+The CLIENT notification
+-----------------------
+
+The ">CLIENT:" notification is enabled by the --management-client-auth
+OpenVPN configuration directive that gives the management interface client
+the responsibility to authenticate OpenVPN clients after their client
+certificate has been verified. CLIENT notifications may be multi-line, and
+the sequentiality of a given CLIENT notification, its associated environmental
+variables, and the terminating ">CLIENT:ENV,END" line are guaranteed to be
+atomic.
+
+CLIENT notification types:
+
+(1) Notify new client connection ("CONNECT") or existing client TLS session
+ renegotiation ("REAUTH"). Information about the client is provided
+ by a list of environmental variables which are documented in the OpenVPN
+ man page. The environmental variables passed are equivalent to those
+ that would be passed to an --auth-user-pass-verify script.
+
+ >CLIENT:CONNECT|REAUTH,{CID},{KID}
+ >CLIENT:ENV,name1=val1
+ >CLIENT:ENV,name2=val2
+ >CLIENT:ENV,...
+ >CLIENT:ENV,END
+
+(2) Notify successful client authentication and session initiation.
+ Called after CONNECT.
+
+ >CLIENT:ESTABLISHED,{CID}
+ >CLIENT:ENV,name1=val1
+ >CLIENT:ENV,name2=val2
+ >CLIENT:ENV,...
+ >CLIENT:ENV,END
+
+(3) Notify existing client disconnection. The environmental variables passed
+ are equivalent to those that would be passed to a --client-disconnect
+ script.
+
+ >CLIENT:DISCONNECT,{CID}
+ >CLIENT:ENV,name1=val1
+ >CLIENT:ENV,name2=val2
+ >CLIENT:ENV,...
+ >CLIENT:ENV,END
+
+(4) Notify that a particular virtual address or subnet
+ is now associated with a specific client.
+
+ >CLIENT:ADDRESS,{CID},{ADDR},{PRI}
+
+Variables:
+
+CID -- Client ID, numerical ID for each connecting client, sequence = 0,1,2,...
+KID -- Key ID, numerical ID for the key associated with a given client TLS session,
+ sequence = 0,1,2,...
+PRI -- Primary (1) or Secondary (0) VPN address/subnet. All clients have at least
+ one primary IP address. Secondary address/subnets are associated with
+ client-specific "iroute" directives.
+ADDR -- IPv4 address/subnet in the form 1.2.3.4 or 1.2.3.0/255.255.255.0
+
+In the unlikely scenario of an extremely long-running OpenVPN server,
+CID and KID should be assumed to recycle to 0 after (2^32)-1, however this
+recycling behavior is guaranteed to be collision-free.
+
+Command Parsing
+---------------
+
+The management interface uses the same command line lexical analyzer
+as is used by the OpenVPN config file parser.
+
+Whitespace is a parameter separator.
+
+Double quotation or single quotation characters ("", '') can be used
+to enclose parameters containing whitespace.
+
+Backslash-based shell escaping is performed, using the following
+mappings, when not in single quotations:
+
+\\ Maps to a single backslash character (\).
+\" Pass a literal doublequote character ("), don't
+ interpret it as enclosing a parameter.
+\[SPACE] Pass a literal space or tab character, don't
+ interpret it as a parameter delimiter.
+
+Challenge/Response Protocol
+---------------------------
+
+The OpenVPN Challenge/Response Protocol allows an OpenVPN server to
+generate challenge questions that are shown to the user, and to see
+the user's responses to those challenges. Based on the responses, the
+server can allow or deny access.
+
+In this way, the OpenVPN Challenge/Response Protocol can be used
+to implement multi-factor authentication. Two different
+variations on the challenge/response protocol are supported: the
+"Dynamic" and "Static" protocols.
+
+The basic idea of Challenge/Response is that the user must enter an
+additional piece of information, in addition to the username and
+password, to successfully authenticate. Normally, this information
+is used to prove that the user posesses a certain key-like device
+such as cryptographic token or a particular mobile phone.
+
+Dynamic protocol:
+
+The OpenVPN dynamic challenge/response protocol works by returning
+a specially formatted error message after initial successful
+authentication. This error message contains the challenge question,
+and is formatted as such:
+
+ CRV1:<flags>:<state_id>:<username_base64>:<challenge_text>
+
+flags: a series of optional, comma-separated flags:
+ E : echo the response when the user types it
+ R : a response is required
+
+state_id: an opaque string that should be returned to the server
+ along with the response.
+
+username_base64 : the username formatted as base64
+
+challenge_text : the challenge text to be shown to the user
+
+Example challenge:
+
+ CRV1:R,E:Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l:Y3Ix:Please enter token PIN
+
+After showing the challenge_text and getting a response from the user
+(if R flag is specified), the client should submit the following
+auth creds back to the OpenVPN server:
+
+Username: [username decoded from username_base64]
+Password: CRV1::<state_id>::<response_text>
+
+Where state_id is taken from the challenge request and response_text
+is what the user entered in response to the challenge_text.
+If the R flag is not present, response_text may be the empty
+string.
+
+Example response (suppose the user enters "8675309" for the token PIN):
+
+ Username: cr1 ("Y3Ix" base64 decoded)
+ Password: CRV1::Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l::8675309
+
+Static protocol:
+
+The static protocol differs from the dynamic protocol in that the
+challenge question and response field is given to the user in the
+initial username/password dialog, and the username, password, and
+response are delivered back to the server in a single transaction.
+
+The "static-challenge" directive is used to give the challenge text
+to OpenVPN and indicate whether or not the response should be echoed.
+
+When the "static-challenge" directive is used, the management
+interface will respond as such when credentials are needed:
+
+ >PASSWORD:Need 'Auth' username/password SC:<ECHO>,<TEXT>
+
+ ECHO: "1" if response should be echoed, "0" to not echo
+ TEXT: challenge text that should be shown to the user to
+ facilitate their response
+
+For example:
+
+ >PASSWORD:Need 'Auth' username/password SC:1,Please enter token PIN
+
+The above notification indicates that OpenVPN needs a --auth-user-pass
+password plus a response to a static challenge ("Please enter token PIN").
+The "1" after the "SC:" indicates that the response should be echoed.
+
+The management interface client in this case should add the static
+challenge text to the auth dialog followed by a field for the user to
+enter a response. Then the client should pack the password and response
+together into an encoded password:
+
+ username "Auth" foo
+ password "Auth" "SCRV1:<BASE64_PASSWORD>:<BASE64_RESPONSE>"
+
+For example, if the user entered "bar" as the password and 8675309
+as the PIN, the following management interface commands should be
+issued:
+
+ username "Auth" foo
+ password "Auth" "SCRV1:Zm9v:ODY3NTMwOQ=="
+
+Client-side support for challenge/response protocol:
+
+Currently, the Access Server client and standalone OpenVPN
+client support both static and dynamic challenge/response
+protocols. However, any OpenVPN client UI that drives OpenVPN
+via the management interface needs to add explicit support
+for the challenge/response protocol.
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-05 22:23:41 +0000