aboutsummaryrefslogtreecommitdiff
path: root/management
diff options
context:
space:
mode:
authorjames <james@e7ae566f-a301-0410-adde-c780ea21d3b5>2008-06-11 08:45:09 +0000
committerjames <james@e7ae566f-a301-0410-adde-c780ea21d3b5>2008-06-11 08:45:09 +0000
commit90efcacba6378a4e29275cd6e9914d73d836a4a4 (patch)
treeda032ba71582994f9e1f2ed7162ba14f152cb7d7 /management
parentAdded support for building and linking with (diff)
downloadopenvpn-90efcacba6378a4e29275cd6e9914d73d836a4a4.tar.xz
Updated version to 2.1_rc7e.
Added client authentication and packet filtering capability to management interface. Extended packet filtering capability to work on both --dev tun and --dev tap tunnels. Updated valgrind-suppress file. Made "Linux ip addr del failed" error nonfatal. Amplified --client-cert-not-required warning. Added #pragma pack to proto.h. git-svn-id: http://svn.openvpn.net/projects/openvpn/branches/BETA21/openvpn@2991 e7ae566f-a301-0410-adde-c780ea21d3b5
Diffstat (limited to 'management')
-rw-r--r--management/management-notes.txt262
1 files changed, 257 insertions, 5 deletions
diff --git a/management/management-notes.txt b/management/management-notes.txt
index 73f82a5..4d86111 100644
--- a/management/management-notes.txt
+++ b/management/management-notes.txt
@@ -25,13 +25,12 @@ Future versions of the management interface may allow out-of-band
connections (i.e. not over the VPN) and secured with SSL/TLS.
The management interface is enabled in the OpenVPN
-configuration file using the following directives:
+configuration file using the following directive:
--management
---management-query-passwords
---management-log-cache
-See the man page for documentation on these directives.
+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
@@ -444,6 +443,199 @@ 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"
+
+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.
+
+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).
+
OUTPUT FORMAT
-------------
@@ -454,7 +646,7 @@ OUTPUT FORMAT
the last line will be "END".
(3) Real-time messages will be in the form ">[source]:[text]",
- where source is "ECHO", "FATAL", "HOLD", "INFO", "LOG",
+ where source is "CLIENT", "ECHO", "FATAL", "HOLD", "INFO", "LOG",
"NEED-OK", "PASSWORD", or "STATE".
REAL-TIME MESSAGE FORMAT
@@ -469,6 +661,12 @@ column and are immediately followed by a type keyword
indicating the type of real-time message. The following
types are currently defined:
+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
@@ -497,6 +695,60 @@ PASSWORD -- Used to tell the management client that OpenVPN
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 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
+
+(3) 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
---------------