summaryrefslogtreecommitdiff
path: root/main/openvpn/doc/management-notes.txt
diff options
context:
space:
mode:
authorArne Schwabe <arne@rfc2549.org>2015-04-15 00:17:26 +0200
committerArne Schwabe <arne@rfc2549.org>2015-04-15 00:20:23 +0200
commitc3ae4aaac9f0b168aed063d3e86c5196608eaba1 (patch)
tree1a18e7d8751d4dd3682d82d12c8441b335112984 /main/openvpn/doc/management-notes.txt
parent5e42114d22faefe7c272b1b498fdf5640da494c7 (diff)
Move more to git, add submodules, fix build script, change hgignore to gitignore
Diffstat (limited to 'main/openvpn/doc/management-notes.txt')
m---------main/openvpn0
-rw-r--r--main/openvpn/doc/management-notes.txt1039
2 files changed, 0 insertions, 1039 deletions
diff --git a/main/openvpn b/main/openvpn
new file mode 160000
+Subproject 7aaf01766f9718375986600216607aeb6397200
diff --git a/main/openvpn/doc/management-notes.txt b/main/openvpn/doc/management-notes.txt
deleted file mode 100644
index ef39b855..00000000
--- a/main/openvpn/doc/management-notes.txt
+++ /dev/null
@@ -1,1039 +0,0 @@
-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 arbitrary cryptographic
-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.