|
--auth-gen-token args |
| | Returns an authentication token to successfully authenticated clients.
Valid syntax:
auth-gen-token [lifetime] [renewal-time] [external-auth]
After successful user/password authentication, the OpenVPN server will
with this option generate a temporary authentication token and push that
to the client. On the following renegotiations, the OpenVPN client will pass
this token instead of the users password. On the server side the server
will do the token authentication internally and it will NOT do any
additional authentications against configured external user/password
authentication mechanisms.
The tokens implemented by this mechanism include an initial timestamp and
a renew timestamp and are secured by HMAC.
The lifetime argument defines how long the generated token is valid.
The lifetime is defined in seconds. If lifetime is not set or it is set
to 0, the token will never expire.
If renewal-time is not set it defaults to reneg-sec.
The token will expire either after the configured lifetime of the
token is reached or after not being renewed for more than 2 *
renewal-time seconds. Clients will be sent renewed tokens on every TLS
renegotiation. If renewal-time is lower than reneg-sec the server
will push an updated temporary authentication token every reneweal-time
seconds. This is done to invalidate a token if a client is disconnected for a
sufficiently long time, while at the same time permitting much longer token
lifetimes for active clients.
This feature is useful for environments which are configured to use One
Time Passwords (OTP) as part of the user/password authentications and
that authentication mechanism does not implement any auth-token support.
When the external-auth keyword is present the normal
authentication method will always be called even if auth-token succeeds.
Normally other authentications method are skipped if auth-token
verification succeeds or fails.
This option postpones this decision to the external authentication
methods and checks the validity of the account and do other checks.
In this mode the environment will have a session_id variable that
holds the session id from auth-gen-token. Also an environment variable
session_state is present. This variable indicates whether the
auth-token has succeeded or not. It can have the following values:
Initial- No token from client.
Authenticated- Token is valid and not expired.
Expired- Token is valid but has expired.
Invalid- Token is invalid (failed HMAC or wrong length)
AuthenticatedEmptyUser / ExpiredEmptyUser- The token is not valid with the username sent from the client but
would be valid (or expired) if we assume an empty username was
used instead. These two cases are a workaround for behaviour in
OpenVPN 3. If this workaround is not needed these two cases should
be handled in the same way as
Invalid.
Warning: Use this feature only if you want your authentication
method called on every verification. Since the external authentication
is called it needs to also indicate a success or failure of the
authentication. It is strongly recommended to return an authentication
failure in the case of the Invalid/Expired auth-token with the
external-auth option unless the client could authenticate in another
acceptable way (e.g. client certificate), otherwise returning success
will lead to authentication bypass (as does returning success on a wrong
password from a script).
|
|
--auth-gen-token-secret file |
| | Specifies a file that holds a secret for the HMAC used in
--auth-gen-token If file is not present OpenVPN will generate a
random secret on startup. This file should be used if auth-token should
validate after restarting a server or if client should be able to roam
between multiple OpenVPN servers with their auth-token. |
|
--auth-user-pass-optional |
| | Allow connections by clients that do not specify a username/password.
Normally, when --auth-user-pass-verify or
--management-client-auth are specified (or an authentication plugin
module), the OpenVPN server daemon will require connecting clients to
specify a username and password. This option makes the submission of a
username/password by clients optional, passing the responsibility to the
user-defined authentication module/script to accept or deny the client
based on other factors (such as the setting of X509 certificate fields).
When this option is used, and a connecting client does not submit a
username/password, the user-defined authentication module/script will
see the username and password as being set to empty strings (""). The
authentication module/script MUST have logic to detect this condition
and respond accordingly. |
|
--ccd-exclusive |
| | Require, as a condition of authentication, that a connecting client has
a --client-config-dir file. |
|
--client-config-dir dir |
| | Specify a directory dir for custom client config files. After a
connecting client has been authenticated, OpenVPN will look in this
directory for a file having the same name as the client's X509 common
name. If a matching file exists, it will be opened and parsed for
client-specific configuration options. If no matching file is found,
OpenVPN will instead try to open and parse a default file called
"DEFAULT", which may be provided but is not required. Note that the
configuration files must be readable by the OpenVPN process after it has
dropped it's root privileges.
This file can specify a fixed IP address for a given client using
--ifconfig-push, as well as fixed subnets owned by the client using
--iroute.
One of the useful properties of this option is that it allows client
configuration files to be conveniently created, edited, or removed while
the server is live, without needing to restart the server.
The following options are legal in a client-specific context: --push,
--push-reset, --push-remove, --iroute, --ifconfig-push,
--vlan-pvid and --config.
|
|
--client-to-client |
| | Because the OpenVPN server mode handles multiple clients through a
single tun or tap interface, it is effectively a router. The
--client-to-client flag tells OpenVPN to internally route
client-to-client traffic rather than pushing all client-originating
traffic to the TUN/TAP interface.
When this option is used, each client will "see" the other clients which
are currently connected. Otherwise, each client will only see the
server. Don't use this option if you want to firewall tunnel traffic
using custom, per-client rules.
Please note that when using data channel offload this option has no
effect. Packets are always sent to the tunnel interface and then
routed based on the system routing table.
|
|
--disable |
Disable a particular client (based on the common name) from connecting.
Don't use this option to disable a client due to key or password
compromise. Use a CRL (certificate revocation list) instead (see the
--crl-verify option).
This option must be associated with a specific client instance, which
means that it must be specified either in a client instance config file
using --client-config-dir or dynamically generated using a
--client-connect script.
|
|
--connect-freq args |
| | Allow a maximum of n new connections per sec seconds from
clients.
Valid syntax:
connect-freq n sec
This is designed to contain DoS attacks which flood the server
with connection requests using certificates which will ultimately fail
to authenticate.
This limit applies after --connect-freq-initial and
only applies to client that have completed the three-way handshake
or client that use --tls-crypt-v2 without cookie support
(allow-noncookie argument to --tls-crypt-v2).
This is an imperfect solution however, because in a real DoS scenario,
legitimate connections might also be refused.
For the best protection against DoS attacks in server mode, use
--proto udp and either --tls-auth or --tls-crypt.
|
|
--connect-freq-initial args |
| | (UDP only) Allow a maximum of n initial connection packet responses
per sec seconds from the OpenVPN server to clients.
Valid syntax:
connect-freq-initial n sec
OpenVPN starting at 2.6 is very efficient in responding to initial
connection packets. When not limiting the initial responses
an OpenVPN daemon can be abused in reflection attacks.
This option is designed to limit the rate OpenVPN will respond to initial
attacks.
Connection attempts that complete the initial three-way handshake
will not be counted against the limit. The default is to allow
100 initial connection per 10s.
|
|
--duplicate-cn |
Allow multiple clients with the same common name to concurrently
connect. In the absence of this option, OpenVPN will disconnect a client
instance upon connection of a new client having the same common name. |
|
--ifconfig-pool args |
| | Set aside a pool of subnets to be dynamically allocated to connecting
clients, similar to a DHCP server.
Valid syntax:
ifconfig-pool start-IP end-IP [netmask]
For tun-style tunnels, each client
will be given a /30 subnet (for interoperability with Windows clients).
For tap-style tunnels, individual addresses will be allocated, and the
optional netmask parameter will also be pushed to clients.
|
|
--ifconfig-ipv6-pool args |
| | Specify an IPv6 address pool for dynamic assignment to clients.
Valid args:
ifconfig-ipv6-pool ipv6addr/bits
The pool starts at ipv6addr and matches the offset determined from
the start of the IPv4 pool. If the host part of the given IPv6
address is 0, the pool starts at ipv6addr +1.
|
|
--ifconfig-pool-persist args |
| | Persist/unpersist ifconfig-pool data to file, at seconds
intervals (default 600), as well as on program startup and shutdown.
Valid syntax:
ifconfig-pool-persist file [seconds]
The goal of this option is to provide a long-term association between
clients (denoted by their common name) and the virtual IP address
assigned to them from the ifconfig-pool. Maintaining a long-term
association is good for clients because it allows them to effectively
use the --persist-tun option.
file is a comma-delimited ASCII file, formatted as
<Common-Name>,<IP-address>.
If seconds = 0, file will be treated as read-only. This
is useful if you would like to treat file as a configuration file.
Note that the entries in this file are treated by OpenVPN as
suggestions only, based on past associations between a common name and
IP address. They do not guarantee that the given common name will always
receive the given IP address. If you want guaranteed assignment, use
--ifconfig-push
|
|
--ifconfig-push args |
| | Push virtual IP endpoints for client tunnel, overriding the
--ifconfig-pool dynamic allocation.
Valid syntax:
ifconfig-push local remote-netmask [alias]
The parameters local and remote-netmask are set according to the
--ifconfig directive which you want to execute on the client machine
to configure the remote end of the tunnel. Note that the parameters
local and remote-netmask are from the perspective of the client,
not the server. They may be DNS names rather than IP addresses, in which
case they will be resolved on the server at the time of client
connection.
The optional alias parameter may be used in cases where NAT causes
the client view of its local endpoint to differ from the server view. In
this case local/remote-netmask will refer to the server view while
alias/remote-netmask will refer to the client view.
This option must be associated with a specific client instance, which
means that it must be specified either in a client instance config file
using --client-config-dir or dynamically generated using a
--client-connect script.
Remember also to include a --route directive in the main OpenVPN
config file which encloses local, so that the kernel will know to
route it to the server's TUN/TAP interface.
OpenVPN's internal client IP address selection algorithm works as
follows:
- Use
--client-connect script generated file for static IP
(first choice).
- Use
--client-config-dir file for static IP (next choice).
- Use
--ifconfig-pool allocation for dynamic IP (last
choice).
|
|
--ifconfig-ipv6-push args |
| | for --client-config-dir per-client static IPv6 interface
configuration, see --client-config-dir and --ifconfig-push for
more details.
Valid syntax:
ifconfig-ipv6-push ipv6addr/bits ipv6remote
|
|
--multihome |
Configure a multi-homed UDP server. This option needs to be used when a
server has more than one IP address (e.g. multiple interfaces, or
secondary IP addresses), and is not using --local to force binding
to one specific address only. This option will add some extra lookups to
the packet path to ensure that the UDP reply packets are always sent
from the address that the client is talking to. This is not supported on
all platforms, and it adds more processing, so it's not enabled by
default.
- Notes:
- This option is only relevant for UDP servers.
- If you do an IPv6+IPv4 dual-stack bind on a Linux machine with
multiple IPv4 address, connections to IPv4 addresses will not
work right on kernels before 3.15, due to missing kernel
support for the IPv4-mapped case (some distributions have
ported this to earlier kernel versions, though).
|
|
--iroute args |
Generate an internal route to a specific client. The netmask
parameter, if omitted, defaults to 255.255.255.255.
Valid syntax:
iroute network [netmask]
This directive can be used to route a fixed subnet from the server to a
particular client, regardless of where the client is connecting from.
Remember that you must also add the route to the system routing table as
well (such as by using the --route directive). The reason why two
routes are needed is that the --route directive routes the packet
from the kernel to OpenVPN. Once in OpenVPN, the --iroute directive
routes to the specific client.
However, when using DCO, the --iroute directive is usually enough
for DCO to fully configure the routing table. The extra --route
directive is required only if the expected behaviour is to route the
traffic for a specific network to the VPN interface also when the
responsible client is not connected (traffic will then be dropped).
This option must be specified either in a client instance config file
using --client-config-dir or dynamically generated using a
--client-connect script.
The --iroute directive also has an important interaction with
--push "route ...". --iroute essentially defines a subnet which
is owned by a particular client (we will call this client A). If you
would like other clients to be able to reach A's subnet, you can use
--push "route ..." together with --client-to-client to effect
this. In order for all clients to see A's subnet, OpenVPN must push
this route to all clients EXCEPT for A, since the subnet is already
owned by A. OpenVPN accomplishes this by not not pushing a route to
a client if it matches one of the client's iroutes.
|
|
--iroute-ipv6 args |
| | for --client-config-dir per-client static IPv6 route configuration,
see --iroute for more details how to setup and use this, and how
--iroute and --route interact.
Valid syntax:
iroute-ipv6 ipv6addr/bits
|
|
--max-clients n |
| | Limit server to a maximum of n concurrent clients. |
|
--max-routes-per-client n |
| | Allow a maximum of n internal routes per client (default
256). This is designed to help contain DoS attacks where an
authenticated client floods the server with packets appearing to come
from many unique MAC addresses, forcing the server to deplete virtual
memory as its internal routing table expands. This directive can be used
in a --client-config-dir file or auto-generated by a
--client-connect script to override the global value for a particular
client.
Note that this directive affects OpenVPN's internal routing table, not
the kernel routing table.
|
|
--opt-verify |
DEPRECATED Clients that connect with options that are incompatible with
those of the server will be disconnected.
Options that will be compared for compatibility include dev-type,
link-mtu, tun-mtu, proto, ifconfig,
comp-lzo, fragment, keydir, cipher,
auth, keysize, secret, no-replay,
tls-auth, key-method, tls-server
and tls-client.
This option requires that --disable-occ NOT be used.
|
|
--port-share args |
| | Share OpenVPN TCP with another service
Valid syntax:
port-share host port [dir]
When run in TCP server mode, share the OpenVPN port with another
application, such as an HTTPS server. If OpenVPN senses a connection to
its port which is using a non-OpenVPN protocol, it will proxy the
connection to the server at host:port. Currently only designed to
work with HTTP/HTTPS, though it would be theoretically possible to
extend to other protocols such as ssh.
dir specifies an optional directory where a temporary file with name
N containing content C will be dynamically generated for each proxy
connection, where C is the source IP:port of the client connection and N
is the source IP:port of the connection to the proxy receiver. This
directory can be used as a dictionary by the proxy receiver to determine
the origin of the connection. Each generated file will be automatically
deleted when the proxied connection is torn down.
Not implemented on Windows.
|
|
--push option |
Push a config file option back to the client for remote execution. Note
that option must be enclosed in double quotes (""). The
client must specify --pull in its config file. The set of options
which can be pushed is limited by both feasibility and security. Some
options such as those which would execute scripts are banned, since they
would effectively allow a compromised server to execute arbitrary code
on the client. Other options such as TLS or MTU parameters cannot be
pushed because the client needs to know them before the connection to the
server can be initiated.
This is a partial list of options which can currently be pushed:
--route, --route-gateway, --route-delay,
--redirect-gateway, --ip-win32, --dhcp-option, --dns,
--inactive, --ping, --ping-exit, --ping-restart,
--setenv, --auth-token, --persist-key, --persist-tun,
--echo, --comp-lzo, --socket-flags, --sndbuf,
--rcvbuf, --session-timeout
|
|
--push-remove opt |
| | Selectively remove all --push options matching "opt" from the option
list for a client. opt is matched as a substring against the whole
option string to-be-pushed to the client, so --push-remove route
would remove all --push route ... and --push route-ipv6 ...
statements, while --push-remove "route-ipv6 2001:" would only remove
IPv6 routes for 2001:... networks.
--push-remove can only be used in a client-specific context, like in
a --client-config-dir file, or --client-connect script or plugin
-- similar to --push-reset, just more selective.
NOTE: to change an option, --push-remove can be used to first
remove the old value, and then add a new --push option with the new
value.
NOTE 2: due to implementation details, 'ifconfig' and 'ifconfig-ipv6'
can only be removed with an exact match on the option (
push-remove ifconfig), no substring matching and no matching on
the IPv4/IPv6 address argument is possible.
|
|
--push-reset |
Don't inherit the global push list for a specific client instance.
Specify this option in a client-specific context such as with a
--client-config-dir configuration file. This option will ignore
--push options at the global config file level.
NOTE: --push-reset is very thorough: it will remove almost
all options from the list of to-be-pushed options. In many cases,
some of these options will need to be re-configured afterwards -
specifically, --topology subnet and --route-gateway will get
lost and this will break client configs in many cases. Thus, for most
purposes, --push-remove is better suited to selectively remove
push options for individual clients.
|
|
--server args |
A helper directive designed to simplify the configuration of OpenVPN's
server mode. This directive will set up an OpenVPN server which will
allocate addresses to clients out of the given network/netmask. The
server itself will take the .1 address of the given network for
use as the server-side endpoint of the local TUN/TAP interface. If the
optional nopool flag is given, no dynamic IP address pool will
prepared for VPN clients.
Valid syntax:
server network netmask [nopool]
For example, --server 10.8.0.0 255.255.255.0 expands as follows:
mode server
tls-server
push "topology [topology]"
if dev tun AND (topology == net30 OR topology == p2p):
ifconfig 10.8.0.1 10.8.0.2
if !nopool:
ifconfig-pool 10.8.0.4 10.8.0.251
route 10.8.0.0 255.255.255.0
if client-to-client:
push "route 10.8.0.0 255.255.255.0"
else if topology == net30:
push "route 10.8.0.1"
if dev tap OR (dev tun AND topology == subnet):
ifconfig 10.8.0.1 255.255.255.0
if !nopool:
ifconfig-pool 10.8.0.2 10.8.0.253 255.255.255.0
push "route-gateway 10.8.0.1"
if route-gateway unset:
route-gateway 10.8.0.2
Don't use --server if you are ethernet bridging. Use
--server-bridge instead.
|
|
--server-bridge args |
| | A helper directive similar to --server which is designed to simplify
the configuration of OpenVPN's server mode in ethernet bridging
configurations.
Valid syntaxes:
server-bridge gateway netmask pool-start-IP pool-end-IP
server-bridge [nogw]
If --server-bridge is used without any parameters, it will enable a
DHCP-proxy mode, where connecting OpenVPN clients will receive an IP
address for their TAP adapter from the DHCP server running on the
OpenVPN server-side LAN. Note that only clients that support the binding
of a DHCP client with the TAP adapter (such as Windows) can support this
mode. The optional nogw flag (advanced) indicates that gateway
information should not be pushed to the client.
To configure ethernet bridging, you must first use your OS's bridging
capability to bridge the TAP interface with the ethernet NIC interface.
For example, on Linux this is done with the brctl tool, and with
Windows XP it is done in the Network Connections Panel by selecting the
ethernet and TAP adapters and right-clicking on "Bridge Connections".
Next you you must manually set the IP/netmask on the bridge interface.
The gateway and netmask parameters to --server-bridge can be
set to either the IP/netmask of the bridge interface, or the IP/netmask
of the default gateway/router on the bridged subnet.
Finally, set aside a IP range in the bridged subnet, denoted by
pool-start-IP and pool-end-IP, for OpenVPN to allocate to
connecting clients.
For example, server-bridge 10.8.0.4 255.255.255.0 10.8.0.128
10.8.0.254 expands as follows:
mode server
tls-server
ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0
push "route-gateway 10.8.0.4"
In another example, --server-bridge (without parameters) expands as
follows:
mode server
tls-server
push "route-gateway dhcp"
Or --server-bridge nogw expands as follows:
mode server
tls-server
|
|
--server-ipv6 args |
| | Convenience-function to enable a number of IPv6 related options at once,
namely --ifconfig-ipv6, --ifconfig-ipv6-pool and
--push tun-ipv6.
Valid syntax:
server-ipv6 ipv6addr/bits
Pushing of the --tun-ipv6 directive is done for older clients which
require an explicit --tun-ipv6 in their configuration.
|
|
--stale-routes-check args |
| | Remove routes which haven't had activity for n seconds (i.e. the ageing
time). This check is run every t seconds (i.e. check interval).
Valid syntax:
stale-routes-check n [t]
If t is not present it defaults to n.
This option helps to keep the dynamic routing table small. See also
--max-routes-per-client
|
|
--username-as-common-name |
| | Use the authenticated username as the common-name, rather than the
common-name from the client certificate. Requires that some form of
--auth-user-pass verification is in effect. As the replacement happens
after --auth-user-pass verification, the verification script or
plugin will still receive the common-name from the certificate.
The common_name environment variable passed to scripts and plugins invoked
after authentication (e.g, client-connect script) and file names parsed in
client-config directory will match the username.
|
|
--verify-client-cert mode |
| | Specify whether the client is required to supply a valid certificate.
Possible mode options are:
noneA client certificate is not required. the client needs to
authenticate using username/password only. Be aware that using this
directive is less secure than requiring certificates from all
clients.
If you use this directive, the entire responsibility of authentication
will rest on your --auth-user-pass-verify script, so keep in mind
that bugs in your script could potentially compromise the security of
your VPN.
--verify-client-cert none is functionally equivalent to
--client-cert-not-required.
optionalA client may present a certificate but it is not required to do so.
When using this directive, you should also use a
--auth-user-pass-verify script to ensure that clients are
authenticated using a certificate, a username and password, or
possibly even both.
Again, the entire responsibility of authentication will rest on your
--auth-user-pass-verify script, so keep in mind that bugs in your
script could potentially compromise the security of your VPN.
require- This is the default option. A client is required to present a
certificate, otherwise VPN access is refused.
If you don't use this directive (or use --verify-client-cert require)
but you also specify an --auth-user-pass-verify script, then OpenVPN
will perform double authentication. The client certificate verification
AND the --auth-user-pass-verify script will need to succeed in order
for a client to be authenticated and accepted onto the VPN.
|
|
--vlan-tagging |
Server-only option. Turns the OpenVPN server instance into a switch that
understands VLAN-tagging, based on IEEE 802.1Q.
The server TAP device and each of the connecting clients is seen as a
port of the switch. All client ports are in untagged mode and the server
TAP device is VLAN-tagged, untagged or accepts both, depending on the
--vlan-accept setting.
Ethernet frames with a prepended 802.1Q tag are called "tagged". If the
VLAN Identifier (VID) field in such a tag is non-zero, the frame is
called "VLAN-tagged". If the VID is zero, but the Priority Control Point
(PCP) field is non-zero, the frame is called "prio-tagged". If there is
no 802.1Q tag, the frame is "untagged".
Using the --vlan-pvid v option once per client (see
--client-config-dir), each port can be associated with a certain VID.
Packets can only be forwarded between ports having the same VID.
Therefore, clients with differing VIDs are completely separated from
one-another, even if --client-to-client is activated.
The packet filtering takes place in the OpenVPN server. Clients should
not have any VLAN tagging configuration applied.
The --vlan-tagging option is off by default. While turned off,
OpenVPN accepts any Ethernet frame and does not perform any special
processing for VLAN-tagged packets.
This option can only be activated in --dev tap mode.
|
|
--vlan-accept args |
| | Configure the VLAN tagging policy for the server TAP device.
Valid syntax:
vlan-accept all|tagged|untagged
The following modes are available:
tagged- Admit only VLAN-tagged frames. Only VLAN-tagged packets are accepted,
while untagged or priority-tagged packets are dropped when entering
the server TAP device.
untagged- Admit only untagged and prio-tagged frames. VLAN-tagged packets are
not accepted, while untagged or priority-tagged packets entering the
server TAP device are tagged with the value configured for the global
--vlan-pvid setting.
all (default)- Admit all frames. All packets are admitted and then treated like
untagged or tagged mode respectively.
- Note:
- Some vendors refer to switch ports running in
tagged mode
as "trunk ports" and switch ports running in untagged mode
as "access ports".
Packets forwarded from clients to the server are VLAN-tagged with the
originating client's PVID, unless the VID matches the global
--vlan-pvid, in which case the tag is removed.
If no PVID is configured for a given client (see --vlan-pvid) packets
are tagged with 1 by default.
|
|
--vlan-pvid v |
Specifies which VLAN identifier a "port" is associated with. Only valid
when --vlan-tagging is specified.
In the client context, the setting specifies which VLAN ID a client is
associated with. In the global context, the VLAN ID of the server TAP
device is set. The latter only makes sense for --vlan-accept
untagged and --vlan-accept all modes.
Valid values for v go from 1 through to 4094. The
global value defaults to 1. If no --vlan-pvid is specified in
the client context, the global value is inherited.
In some switch implementations, the PVID is also referred to as "Native
VLAN".
|