| 1 | {{{ |
| 2 | openvpn(8) openvpn(8) |
| 3 | |
| 4 | |
| 5 | |
| 6 | NAME |
| 7 | openvpn - secure IP tunnel daemon. |
| 8 | |
| 9 | SYNOPSIS |
| 10 | openvpn [ options ... ] |
| 11 | |
| 12 | INTRODUCTION |
| 13 | OpenVPN is an open source VPN daemon by James Yonan. Because OpenVPN tries to be a universal VPN tool offering a great deal of |
| 14 | flexibility, there are a lot of options on this manual page. If you're new to OpenVPN, you might want to skip ahead to the |
| 15 | examples section where you will see how to construct simple VPNs on the command line without even needing a configuration file. |
| 16 | |
| 17 | Also note that there's more documentation and examples on the OpenVPN web site: http://openvpn.net/ |
| 18 | |
| 19 | And if you would like to see a shorter version of this manual, see the openvpn usage message which can be obtained by running |
| 20 | openvpn without any parameters. |
| 21 | |
| 22 | DESCRIPTION |
| 23 | OpenVPN is a robust and highly flexible VPN daemon. OpenVPN supports SSL/TLS security, ethernet bridging, TCP or UDP tunnel |
| 24 | transport through proxies or NAT, support for dynamic IP addresses and DHCP, scalability to hundreds or thousands of users, and |
| 25 | portability to most major OS platforms. |
| 26 | |
| 27 | OpenVPN is tightly bound to the OpenSSL library, and derives much of its crypto capabilities from it. |
| 28 | |
| 29 | OpenVPN supports conventional encryption using a pre-shared secret key (Static Key mode) or public key security (SSL/TLS mode) |
| 30 | using client & server certificates. OpenVPN also supports non-encrypted TCP/UDP tunnels. |
| 31 | |
| 32 | OpenVPN is designed to work with the TUN/TAP virtual networking interface that exists on most platforms. |
| 33 | |
| 34 | Overall, OpenVPN aims to offer many of the key features of IPSec but with a relatively lightweight footprint. |
| 35 | |
| 36 | OPTIONS |
| 37 | OpenVPN allows any option to be placed either on the command line or in a configuration file. Though all command line options |
| 38 | are preceded by a double-leading-dash ("--"), this prefix can be removed when an option is placed in a configuration file. |
| 39 | |
| 40 | --help Show options. |
| 41 | |
| 42 | --config file |
| 43 | Load additional config options from file where each line corresponds to one command line option, but with the leading |
| 44 | '--' removed. |
| 45 | |
| 46 | If --config file is the only option to the openvpn command, the --config can be removed, and the command can be given as |
| 47 | openvpn file |
| 48 | |
| 49 | Note that configuration files can be nested to a reasonable depth. |
| 50 | |
| 51 | Double quotation or single quotation characters ("", '') can be used to enclose single parameters containing whitespace, |
| 52 | and "#" or ";" characters in the first column can be used to denote comments. |
| 53 | |
| 54 | Note that OpenVPN 2.0 and higher performs backslash-based shell escaping for characters not in single quotations, so the |
| 55 | following mappings should be observed: |
| 56 | |
| 57 | \\ Maps to a single backslash character (\). |
| 58 | \" Pass a literal doublequote character ("), don't |
| 59 | interpret it as enclosing a parameter. |
| 60 | \[SPACE] Pass a literal space or tab character, don't |
| 61 | interpret it as a parameter delimiter. |
| 62 | |
| 63 | For example on Windows, use double backslashes to represent pathnames: |
| 64 | |
| 65 | secret "c:\\OpenVPN\\secret.key" |
| 66 | |
| 67 | For examples of configuration files, see http://openvpn.net/examples.html |
| 68 | |
| 69 | Here is an example configuration file: |
| 70 | |
| 71 | # |
| 72 | # Sample OpenVPN configuration file for |
| 73 | # using a pre-shared static key. |
| 74 | # |
| 75 | # '#' or ';' may be used to delimit comments. |
| 76 | |
| 77 | # Use a dynamic tun device. |
| 78 | dev tun |
| 79 | |
| 80 | # Our remote peer |
| 81 | remote mypeer.mydomain |
| 82 | |
| 83 | # 10.1.0.1 is our local VPN endpoint |
| 84 | # 10.1.0.2 is our remote VPN endpoint |
| 85 | ifconfig 10.1.0.1 10.1.0.2 |
| 86 | |
| 87 | # Our pre-shared static key |
| 88 | secret static.key |
| 89 | |
| 90 | Tunnel Options: |
| 91 | --mode m |
| 92 | Set OpenVPN major mode. By default, OpenVPN runs in point-to-point mode ("p2p"). OpenVPN 2.0 introduces a new mode |
| 93 | ("server") which implements a multi-client server capability. |
| 94 | |
| 95 | --local host |
| 96 | Local host name or IP address for bind. If specified, OpenVPN will bind to this address only. If unspecified, OpenVPN |
| 97 | will bind to all interfaces. |
| 98 | |
| 99 | --remote host [port] [proto] |
| 100 | Remote host name or IP address. On the client, multiple --remote options may be specified for redundancy, each refer‐ |
| 101 | ring to a different OpenVPN server. Specifying multiple --remote options for this purpose is a special case of the more |
| 102 | general connection-profile feature. See the <connection> documentation below. |
| 103 | |
| 104 | The OpenVPN client will try to connect to a server at host:port in the order specified by the list of --remote options. |
| 105 | |
| 106 | proto indicates the protocol to use when connecting with the remote, and may be "tcp" or "udp". |
| 107 | |
| 108 | The client will move on to the next host in the list, in the event of connection failure. Note that at any given time, |
| 109 | the OpenVPN client will at most be connected to one server. |
| 110 | |
| 111 | Note that since UDP is connectionless, connection failure is defined by the --ping and --ping-restart options. |
| 112 | |
| 113 | Note the following corner case: If you use multiple --remote options, AND you are dropping root privileges on the |
| 114 | client with --user and/or --group, AND the client is running a non-Windows OS, if the client needs to switch to a dif‐ |
| 115 | ferent server, and that server pushes back different TUN/TAP or route settings, the client may lack the necessary privi‐ |
| 116 | leges to close and reopen the TUN/TAP interface. This could cause the client to exit with a fatal error. |
| 117 | |
| 118 | If --remote is unspecified, OpenVPN will listen for packets from any IP address, but will not act on those packets |
| 119 | unless they pass all authentication tests. This requirement for authentication is binding on all potential peers, even |
| 120 | those from known and supposedly trusted IP addresses (it is very easy to forge a source IP address on a UDP packet). |
| 121 | |
| 122 | When used in TCP mode, --remote will act as a filter, rejecting connections from any host which does not match host. |
| 123 | |
| 124 | If host is a DNS name which resolves to multiple IP addresses, one will be randomly chosen, providing a sort of basic |
| 125 | load-balancing and failover capability. |
| 126 | |
| 127 | --remote-random-hostname |
| 128 | Add a random string (6 characters) to first DNS label of hostname to prevent DNS caching. For example, "foo.bar.gov" |
| 129 | would be modified to "<random-chars>.foo.bar.gov". |
| 130 | |
| 131 | <connection> |
| 132 | Define a client connection profile. Client connection profiles are groups of OpenVPN options that describe how to con‐ |
| 133 | nect to a given OpenVPN server. Client connection profiles are specified within an OpenVPN configuration file, and each |
| 134 | profile is bracketed by <connection> and </connection>. |
| 135 | |
| 136 | An OpenVPN client will try each connection profile sequentially until it achieves a successful connection. |
| 137 | |
| 138 | --remote-random can be used to initially "scramble" the connection list. |
| 139 | |
| 140 | Here is an example of connection profile usage: |
| 141 | |
| 142 | client |
| 143 | dev tun |
| 144 | |
| 145 | <connection> |
| 146 | remote 198.19.34.56 1194 udp |
| 147 | </connection> |
| 148 | |
| 149 | <connection> |
| 150 | remote 198.19.34.56 443 tcp |
| 151 | </connection> |
| 152 | |
| 153 | <connection> |
| 154 | remote 198.19.34.56 443 tcp |
| 155 | http-proxy 192.168.0.8 8080 |
| 156 | http-proxy-retry |
| 157 | </connection> |
| 158 | |
| 159 | <connection> |
| 160 | remote 198.19.36.99 443 tcp |
| 161 | http-proxy 192.168.0.8 8080 |
| 162 | http-proxy-retry |
| 163 | </connection> |
| 164 | |
| 165 | persist-key |
| 166 | persist-tun |
| 167 | pkcs12 client.p12 |
| 168 | ns-cert-type server |
| 169 | verb 3 |
| 170 | |
| 171 | First we try to connect to a server at 198.19.34.56:1194 using UDP. If that fails, we then try to connect to |
| 172 | 198.19.34.56:443 using TCP. If that also fails, then try connecting through an HTTP proxy at 192.168.0.8:8080 to |
| 173 | 198.19.34.56:443 using TCP. Finally, try to connect through the same proxy to a server at 198.19.36.99:443 using TCP. |
| 174 | |
| 175 | The following OpenVPN options may be used inside of a <connection> block: |
| 176 | |
| 177 | bind, connect-retry, connect-retry-max, connect-timeout, float, http-proxy, http-proxy-option, http-proxy-retry, http- |
| 178 | proxy-timeout, local, lport, nobind, port, proto, remote, rport, socks-proxy, and socks-proxy-retry. |
| 179 | |
| 180 | A defaulting mechanism exists for specifying options to apply to all <connection> profiles. If any of the above options |
| 181 | (with the exception of remote ) appear outside of a <connection> block, but in a configuration file which has one or |
| 182 | more <connection> blocks, the option setting will be used as a default for <connection> blocks which follow it in the |
| 183 | configuration file. |
| 184 | |
| 185 | For example, suppose the nobind option were placed in the sample configuration file above, near the top of the file, |
| 186 | before the first <connection> block. The effect would be as if nobind were declared in all <connection> blocks below |
| 187 | it. |
| 188 | |
| 189 | --proto-force p |
| 190 | When iterating through connection profiles, only consider profiles using protocol p ('tcp'|'udp'). |
| 191 | |
| 192 | --remote-random |
| 193 | When multiple --remote address/ports are specified, or if connection profiles are being used, initially randomize the |
| 194 | order of the list as a kind of basic load-balancing measure. |
| 195 | |
| 196 | --proto p |
| 197 | Use protocol p for communicating with remote host. p can be udp, tcp-client, or tcp-server. |
| 198 | |
| 199 | The default protocol is udp when --proto is not specified. |
| 200 | |
| 201 | For UDP operation, --proto udp should be specified on both peers. |
| 202 | |
| 203 | For TCP operation, one peer must use --proto tcp-server and the other must use --proto tcp-client. A peer started with |
| 204 | tcp-server will wait indefinitely for an incoming connection. A peer started with tcp-client will attempt to connect, |
| 205 | and if that fails, will sleep for 5 seconds (adjustable via the --connect-retry option) and try again infinite or up to |
| 206 | N retries (adjustable via the --connect-retry-max option). Both TCP client and server will simulate a SIGUSR1 restart |
| 207 | signal if either side resets the connection. |
| 208 | |
| 209 | OpenVPN is designed to operate optimally over UDP, but TCP capability is provided for situations where UDP cannot be |
| 210 | used. In comparison with UDP, TCP will usually be somewhat less efficient and less robust when used over unreliable or |
| 211 | congested networks. |
| 212 | |
| 213 | This article outlines some of problems with tunneling IP over TCP: |
| 214 | |
| 215 | http://sites.inka.de/sites/bigred/devel/tcp-tcp.html |
| 216 | |
| 217 | There are certain cases, however, where using TCP may be advantageous from a security and robustness perspective, such |
| 218 | as tunneling non-IP or application-level UDP protocols, or tunneling protocols which don't possess a built-in reliabil‐ |
| 219 | ity layer. |
| 220 | |
| 221 | --connect-retry n |
| 222 | For --proto tcp-client, take n as the number of seconds to wait between connection retries (default=5). |
| 223 | |
| 224 | --connect-timeout n |
| 225 | For --proto tcp-client, set connection timeout to n seconds (default=10). |
| 226 | |
| 227 | --connect-retry-max n |
| 228 | For --proto tcp-client, take n as the number of retries of connection attempt (default=infinite). |
| 229 | |
| 230 | --show-proxy-settings |
| 231 | Show sensed HTTP or SOCKS proxy settings. Currently, only Windows clients support this option. |
| 232 | |
| 233 | --http-proxy server port [authfile|'auto'|'auto-nct'] [auth-method] |
| 234 | Connect to remote host through an HTTP proxy at address server and port port. If HTTP Proxy-Authenticate is required, |
| 235 | authfile is a file containing a username and password on 2 lines, or "stdin" to prompt from console. |
| 236 | |
| 237 | auth-method should be one of "none", "basic", or "ntlm". |
| 238 | |
| 239 | HTTP Digest authentication is supported as well, but only via the auto or auto-nct flags (below). |
| 240 | |
| 241 | The auto flag causes OpenVPN to automatically determine the auth-method and query stdin or the management interface for |
| 242 | username/password credentials, if required. This flag exists on OpenVPN 2.1 or higher. |
| 243 | |
| 244 | The auto-nct flag (no clear-text auth) instructs OpenVPN to automatically determine the authentication method, but to |
| 245 | reject weak authentication protocols such as HTTP Basic Authentication. |
| 246 | |
| 247 | --http-proxy-retry |
| 248 | Retry indefinitely on HTTP proxy errors. If an HTTP proxy error occurs, simulate a SIGUSR1 reset. |
| 249 | |
| 250 | --http-proxy-timeout n |
| 251 | Set proxy timeout to n seconds, default=5. |
| 252 | |
| 253 | --http-proxy-option type [parm] |
| 254 | Set extended HTTP proxy options. Repeat to set multiple options. |
| 255 | |
| 256 | VERSION version -- Set HTTP version number to version (default=1.0). |
| 257 | |
| 258 | AGENT user-agent -- Set HTTP "User-Agent" string to user-agent. |
| 259 | |
| 260 | --socks-proxy server [port] |
| 261 | Connect to remote host through a Socks5 proxy at address server and port port (default=1080). |
| 262 | |
| 263 | --socks-proxy-retry |
| 264 | Retry indefinitely on Socks proxy errors. If a Socks proxy error occurs, simulate a SIGUSR1 reset. |
| 265 | |
| 266 | --resolv-retry n |
| 267 | If hostname resolve fails for --remote, retry resolve for n seconds before failing. |
| 268 | |
| 269 | Set n to "infinite" to retry indefinitely. |
| 270 | |
| 271 | By default, --resolv-retry infinite is enabled. You can disable by setting n=0. |
| 272 | |
| 273 | --float |
| 274 | Allow remote peer to change its IP address and/or port number, such as due to DHCP (this is the default if --remote is |
| 275 | not used). --float when specified with --remote allows an OpenVPN session to initially connect to a peer at a known |
| 276 | address, however if packets arrive from a new address and pass all authentication tests, the new address will take con‐ |
| 277 | trol of the session. This is useful when you are connecting to a peer which holds a dynamic address such as a dial-in |
| 278 | user or DHCP client. |
| 279 | |
| 280 | Essentially, --float tells OpenVPN to accept authenticated packets from any address, not only the address which was |
| 281 | specified in the --remote option. |
| 282 | |
| 283 | --ipchange cmd |
| 284 | Run command cmd when our remote ip-address is initially authenticated or changes. |
| 285 | |
| 286 | cmd consists of a path to script (or executable program), optionally followed by arguments. The path and arguments may |
| 287 | be single- or double-quoted and/or escaped using a backslash, and should be separated by one or more spaces. |
| 288 | |
| 289 | When cmd is executed two arguments are appended after any arguments specified in cmd , as follows: |
| 290 | |
| 291 | cmd ip_address port_number |
| 292 | |
| 293 | Don't use --ipchange in --mode server mode. Use a --client-connect script instead. |
| 294 | |
| 295 | See the "Environmental Variables" section below for additional parameters passed as environmental variables. |
| 296 | |
| 297 | If you are running in a dynamic IP address environment where the IP addresses of either peer could change without |
| 298 | notice, you can use this script, for example, to edit the /etc/hosts file with the current address of the peer. The |
| 299 | script will be run every time the remote peer changes its IP address. |
| 300 | |
| 301 | Similarly if our IP address changes due to DHCP, we should configure our IP address change script (see man page for |
| 302 | dhcpcd(8) ) to deliver a SIGHUP or SIGUSR1 signal to OpenVPN. OpenVPN will then reestablish a connection with its most |
| 303 | recently authenticated peer on its new IP address. |
| 304 | |
| 305 | --port port |
| 306 | TCP/UDP port number for both local and remote. The current default of 1194 represents the official IANA port number |
| 307 | assignment for OpenVPN and has been used since version 2.0-beta17. Previous versions used port 5000 as the default. |
| 308 | |
| 309 | --lport port |
| 310 | TCP/UDP port number for bind. |
| 311 | |
| 312 | --rport port |
| 313 | TCP/UDP port number for remote. |
| 314 | |
| 315 | --bind Bind to local address and port. This is the default unless any of --proto tcp-client , --http-proxy or --socks-proxy are |
| 316 | used. |
| 317 | |
| 318 | --nobind |
| 319 | Do not bind to local address and port. The IP stack will allocate a dynamic port for returning packets. Since the |
| 320 | value of the dynamic port could not be known in advance by a peer, this option is only suitable for peers which will be |
| 321 | initiating connections by using the --remote option. |
| 322 | |
| 323 | --dev tunX | tapX | null |
| 324 | TUN/TAP virtual network device ( X can be omitted for a dynamic device.) |
| 325 | |
| 326 | See examples section below for an example on setting up a TUN device. |
| 327 | |
| 328 | You must use either tun devices on both ends of the connection or tap devices on both ends. You cannot mix them, as |
| 329 | they represent different underlying network layers. |
| 330 | |
| 331 | tun devices encapsulate IPv4 or IPv6 (OSI Layer 3) while tap devices encapsulate Ethernet 802.3 (OSI Layer 2). |
| 332 | |
| 333 | --dev-type device-type |
| 334 | Which device type are we using? device-type should be tun (OSI Layer 3) or tap (OSI Layer 2). Use this option only if |
| 335 | the TUN/TAP device used with --dev does not begin with tun or tap. |
| 336 | |
| 337 | --topology mode |
| 338 | Configure virtual addressing topology when running in --dev tun mode. This directive has no meaning in --dev tap mode, |
| 339 | which always uses a subnet topology. |
| 340 | |
| 341 | If you set this directive on the server, the --server and --server-bridge directives will automatically push your chosen |
| 342 | topology setting to clients as well. This directive can also be manually pushed to clients. Like the --dev directive, |
| 343 | this directive must always be compatible between client and server. |
| 344 | |
| 345 | mode can be one of: |
| 346 | |
| 347 | net30 -- Use a point-to-point topology, by allocating one /30 subnet per client. This is designed to allow point-to- |
| 348 | point semantics when some or all of the connecting clients might be Windows systems. This is the default on OpenVPN |
| 349 | 2.0. |
| 350 | |
| 351 | p2p -- Use a point-to-point topology where the remote endpoint of the client's tun interface always points to the local |
| 352 | endpoint of the server's tun interface. This mode allocates a single IP address per connecting client. Only use when |
| 353 | none of the connecting clients are Windows systems. This mode is functionally equivalent to the --ifconfig-pool-linear |
| 354 | directive which is available in OpenVPN 2.0 and is now deprecated. |
| 355 | |
| 356 | subnet -- Use a subnet rather than a point-to-point topology by configuring the tun interface with a local IP address |
| 357 | and subnet mask, similar to the topology used in --dev tap and ethernet bridging mode. This mode allocates a single IP |
| 358 | address per connecting client and works on Windows as well. Only available when server and clients are OpenVPN 2.1 or |
| 359 | higher, or OpenVPN 2.0.x which has been manually patched with the --topology directive code. When used on Windows, |
| 360 | requires version 8.2 or higher of the TAP-Win32 driver. When used on *nix, requires that the tun driver supports an |
| 361 | ifconfig(8) command which sets a subnet instead of a remote endpoint IP address. |
| 362 | |
| 363 | This option exists in OpenVPN 2.1 or higher. |
| 364 | |
| 365 | --tun-ipv6 |
| 366 | Build a tun link capable of forwarding IPv6 traffic. Should be used in conjunction with --dev tun or --dev tunX. A |
| 367 | warning will be displayed if no specific IPv6 TUN support for your OS has been compiled into OpenVPN. |
| 368 | |
| 369 | See below for further IPv6-related configuration options. |
| 370 | |
| 371 | --dev-node node |
| 372 | Explicitly set the device node rather than using /dev/net/tun, /dev/tun, /dev/tap, etc. If OpenVPN cannot figure out |
| 373 | whether node is a TUN or TAP device based on the name, you should also specify --dev-type tun or --dev-type tap. |
| 374 | |
| 375 | On Windows systems, select the TAP-Win32 adapter which is named node in the Network Connections Control Panel or the raw |
| 376 | GUID of the adapter enclosed by braces. The --show-adapters option under Windows can also be used to enumerate all |
| 377 | available TAP-Win32 adapters and will show both the network connections control panel name and the GUID for each TAP- |
| 378 | Win32 adapter. |
| 379 | |
| 380 | --lladdr address |
| 381 | Specify the link layer address, more commonly known as the MAC address. Only applied to TAP devices. |
| 382 | |
| 383 | --iproute cmd |
| 384 | Set alternate command to execute instead of default iproute2 command. May be used in order to execute OpenVPN in |
| 385 | unprivileged environment. |
| 386 | |
| 387 | --ifconfig l rn |
| 388 | Set TUN/TAP adapter parameters. l is the IP address of the local VPN endpoint. For TUN devices, rn is the IP address |
| 389 | of the remote VPN endpoint. For TAP devices, rn is the subnet mask of the virtual ethernet segment which is being cre‐ |
| 390 | ated or connected to. |
| 391 | |
| 392 | For TUN devices, which facilitate virtual point-to-point IP connections, the proper usage of --ifconfig is to use two |
| 393 | private IP addresses which are not a member of any existing subnet which is in use. The IP addresses may be consecutive |
| 394 | and should have their order reversed on the remote peer. After the VPN is established, by pinging rn, you will be ping‐ |
| 395 | ing across the VPN. |
| 396 | |
| 397 | For TAP devices, which provide the ability to create virtual ethernet segments, --ifconfig is used to set an IP address |
| 398 | and subnet mask just as a physical ethernet adapter would be similarly configured. If you are attempting to connect to |
| 399 | a remote ethernet bridge, the IP address and subnet should be set to values which would be valid on the the bridged eth‐ |
| 400 | ernet segment (note also that DHCP can be used for the same purpose). |
| 401 | |
| 402 | This option, while primarily a proxy for the ifconfig(8) command, is designed to simplify TUN/TAP tunnel configuration |
| 403 | by providing a standard interface to the different ifconfig implementations on different platforms. |
| 404 | |
| 405 | --ifconfig parameters which are IP addresses can also be specified as a DNS or /etc/hosts file resolvable name. |
| 406 | |
| 407 | For TAP devices, --ifconfig should not be used if the TAP interface will be getting an IP address lease from a DHCP |
| 408 | server. |
| 409 | |
| 410 | --ifconfig-noexec |
| 411 | Don't actually execute ifconfig/netsh commands, instead pass --ifconfig parameters to scripts using environmental vari‐ |
| 412 | ables. |
| 413 | |
| 414 | --ifconfig-nowarn |
| 415 | Don't output an options consistency check warning if the --ifconfig option on this side of the connection doesn't match |
| 416 | the remote side. This is useful when you want to retain the overall benefits of the options consistency check (also see |
| 417 | --disable-occ option) while only disabling the ifconfig component of the check. |
| 418 | |
| 419 | For example, if you have a configuration where the local host uses --ifconfig but the remote host does not, use --ifcon‐ |
| 420 | fig-nowarn on the local host. |
| 421 | |
| 422 | This option will also silence warnings about potential address conflicts which occasionally annoy more experienced users |
| 423 | by triggering "false positive" warnings. |
| 424 | |
| 425 | --route network/IP [netmask] [gateway] [metric] |
| 426 | Add route to routing table after connection is established. Multiple routes can be specified. Routes will be automati‐ |
| 427 | cally torn down in reverse order prior to TUN/TAP device close. |
| 428 | |
| 429 | This option is intended as a convenience proxy for the route(8) shell command, while at the same time providing portable |
| 430 | semantics across OpenVPN's platform space. |
| 431 | |
| 432 | netmask default -- 255.255.255.255 |
| 433 | |
| 434 | gateway default -- taken from --route-gateway or the second parameter to --ifconfig when --dev tun is specified. |
| 435 | |
| 436 | metric default -- taken from --route-metric otherwise 0. |
| 437 | |
| 438 | The default can be specified by leaving an option blank or setting it to "default". |
| 439 | |
| 440 | The network and gateway parameters can also be specified as a DNS or /etc/hosts file resolvable name, or as one of three |
| 441 | special keywords: |
| 442 | |
| 443 | vpn_gateway -- The remote VPN endpoint address (derived either from --route-gateway or the second parameter to --ifcon‐ |
| 444 | fig when --dev tun is specified). |
| 445 | |
| 446 | net_gateway -- The pre-existing IP default gateway, read from the routing table (not supported on all OSes). |
| 447 | |
| 448 | remote_host -- The --remote address if OpenVPN is being run in client mode, and is undefined in server mode. |
| 449 | |
| 450 | --max-routes n |
| 451 | Allow a maximum number of n --route options to be specified, either in the local configuration file, or pulled from an |
| 452 | OpenVPN server. By default, n=100. |
| 453 | |
| 454 | --route-gateway gw|'dhcp' |
| 455 | Specify a default gateway gw for use with --route. |
| 456 | |
| 457 | If dhcp is specified as the parameter, the gateway address will be extracted from a DHCP negotiation with the OpenVPN |
| 458 | server-side LAN. |
| 459 | |
| 460 | --route-metric m |
| 461 | Specify a default metric m for use with --route. |
| 462 | |
| 463 | --route-delay [n] [w] |
| 464 | Delay n seconds (default=0) after connection establishment, before adding routes. If n is 0, routes will be added imme‐ |
| 465 | diately upon connection establishment. If --route-delay is omitted, routes will be added immediately after TUN/TAP |
| 466 | device open and --up script execution, before any --user or --group privilege downgrade (or --chroot execution.) |
| 467 | |
| 468 | This option is designed to be useful in scenarios where DHCP is used to set tap adapter addresses. The delay will give |
| 469 | the DHCP handshake time to complete before routes are added. |
| 470 | |
| 471 | On Windows, --route-delay tries to be more intelligent by waiting w seconds (w=30 by default) for the TAP-Win32 adapter |
| 472 | to come up before adding routes. |
| 473 | |
| 474 | --route-up cmd |
| 475 | Run command cmd after routes are added, subject to --route-delay. |
| 476 | |
| 477 | cmd consists of a path to script (or executable program), optionally followed by arguments. The path and arguments may |
| 478 | be single- or double-quoted and/or escaped using a backslash, and should be separated by one or more spaces. |
| 479 | |
| 480 | See the "Environmental Variables" section below for additional parameters passed as environmental variables. |
| 481 | |
| 482 | --route-pre-down cmd |
| 483 | Run command cmd before routes are removed upon disconnection. |
| 484 | |
| 485 | cmd consists of a path to script (or executable program), optionally followed by arguments. The path and arguments may |
| 486 | be single- or double-quoted and/or escaped using a backslash, and should be separated by one or more spaces. |
| 487 | |
| 488 | See the "Environmental Variables" section below for additional parameters passed as environmental variables. |
| 489 | |
| 490 | --route-noexec |
| 491 | Don't add or remove routes automatically. Instead pass routes to --route-up script using environmental variables. |
| 492 | |
| 493 | --route-nopull |
| 494 | When used with --client or --pull, accept options pushed by server EXCEPT for routes and dhcp options like DNS servers. |
| 495 | |
| 496 | When used on the client, this option effectively bars the server from adding routes to the client's routing table, how‐ |
| 497 | ever note that this option still allows the server to set the TCP/IP properties of the client's TUN/TAP interface. |
| 498 | |
| 499 | --allow-pull-fqdn |
| 500 | Allow client to pull DNS names from server (rather than being limited to IP address) for --ifconfig, --route, and |
| 501 | --route-gateway. |
| 502 | |
| 503 | --client-nat snat|dnat network netmask alias |
| 504 | This pushable client option sets up a stateless one-to-one NAT rule on packet addresses (not ports), and is useful in |
| 505 | cases where routes or ifconfig settings pushed to the client would create an IP numbering conflict. |
| 506 | |
| 507 | network/netmask (for example 192.168.0.0/255.255.0.0) defines the local view of a resource from the client perspective, |
| 508 | while alias/netmask (for example 10.64.0.0/255.255.0.0) defines the remote view from the server perspective. |
| 509 | |
| 510 | Use snat (source NAT) for resources owned by the client and dnat (destination NAT) for remote resources. |
| 511 | |
| 512 | Set --verb 6 for debugging info showing the transformation of src/dest addresses in packets. |
| 513 | |
| 514 | --redirect-gateway flags... |
| 515 | Automatically execute routing commands to cause all outgoing IP traffic to be redirected over the VPN. This is a |
| 516 | client-side option. |
| 517 | |
| 518 | This option performs three steps: |
| 519 | |
| 520 | (1) Create a static route for the --remote address which forwards to the pre-existing default gateway. This is done so |
| 521 | that (3) will not create a routing loop. |
| 522 | |
| 523 | (2) Delete the default gateway route. |
| 524 | |
| 525 | (3) Set the new default gateway to be the VPN endpoint address (derived either from --route-gateway or the second param‐ |
| 526 | eter to --ifconfig when --dev tun is specified). |
| 527 | |
| 528 | When the tunnel is torn down, all of the above steps are reversed so that the original default route is restored. |
| 529 | |
| 530 | Option flags: |
| 531 | |
| 532 | local -- Add the local flag if both OpenVPN servers are directly connected via a common subnet, such as with wireless. |
| 533 | The local flag will cause step 1 above to be omitted. |
| 534 | |
| 535 | autolocal -- Try to automatically determine whether to enable local flag above. |
| 536 | |
| 537 | def1 -- Use this flag to override the default gateway by using 0.0.0.0/1 and 128.0.0.0/1 rather than 0.0.0.0/0. This |
| 538 | has the benefit of overriding but not wiping out the original default gateway. |
| 539 | |
| 540 | bypass-dhcp -- Add a direct route to the DHCP server (if it is non-local) which bypasses the tunnel (Available on Win‐ |
| 541 | dows clients, may not be available on non-Windows clients). |
| 542 | |
| 543 | bypass-dns -- Add a direct route to the DNS server(s) (if they are non-local) which bypasses the tunnel (Available on |
| 544 | Windows clients, may not be available on non-Windows clients). |
| 545 | |
| 546 | block-local -- Block access to local LAN when the tunnel is active, except for the LAN gateway itself. This is accom‐ |
| 547 | plished by routing the local LAN (except for the LAN gateway address) into the tunnel. |
| 548 | |
| 549 | --link-mtu n |
| 550 | Sets an upper bound on the size of UDP packets which are sent between OpenVPN peers. It's best not to set this parame‐ |
| 551 | ter unless you know what you're doing. |
| 552 | |
| 553 | --redirect-private [flags] |
| 554 | Like --redirect-gateway, but omit actually changing the default gateway. Useful when pushing private subnets. |
| 555 | |
| 556 | --tun-mtu n |
| 557 | Take the TUN device MTU to be n and derive the link MTU from it (default=1500). In most cases, you will probably want |
| 558 | to leave this parameter set to its default value. |
| 559 | |
| 560 | The MTU (Maximum Transmission Units) is the maximum datagram size in bytes that can be sent unfragmented over a particu‐ |
| 561 | lar network path. OpenVPN requires that packets on the control or data channels be sent unfragmented. |
| 562 | |
| 563 | MTU problems often manifest themselves as connections which hang during periods of active usage. |
| 564 | |
| 565 | It's best to use the --fragment and/or --mssfix options to deal with MTU sizing issues. |
| 566 | |
| 567 | --tun-mtu-extra n |
| 568 | Assume that the TUN/TAP device might return as many as n bytes more than the --tun-mtu size on read. This parameter |
| 569 | defaults to 0, which is sufficient for most TUN devices. TAP devices may introduce additional overhead in excess of the |
| 570 | MTU size, and a setting of 32 is the default when TAP devices are used. This parameter only controls internal OpenVPN |
| 571 | buffer sizing, so there is no transmission overhead associated with using a larger value. |
| 572 | |
| 573 | --mtu-disc type |
| 574 | Should we do Path MTU discovery on TCP/UDP channel? Only supported on OSes such as Linux that supports the necessary |
| 575 | system call to set. |
| 576 | |
| 577 | 'no' -- Never send DF (Don't Fragment) frames |
| 578 | 'maybe' -- Use per-route hints |
| 579 | 'yes' -- Always DF (Don't Fragment) |
| 580 | |
| 581 | --mtu-test |
| 582 | To empirically measure MTU on connection startup, add the --mtu-test option to your configuration. OpenVPN will send |
| 583 | ping packets of various sizes to the remote peer and measure the largest packets which were successfully received. The |
| 584 | --mtu-test process normally takes about 3 minutes to complete. |
| 585 | |
| 586 | --fragment max |
| 587 | Enable internal datagram fragmentation so that no UDP datagrams are sent which are larger than max bytes. |
| 588 | |
| 589 | The max parameter is interpreted in the same way as the --link-mtu parameter, i.e. the UDP packet size after encapsula‐ |
| 590 | tion overhead has been added in, but not including the UDP header itself. |
| 591 | |
| 592 | The --fragment option only makes sense when you are using the UDP protocol ( --proto udp ). |
| 593 | |
| 594 | --fragment adds 4 bytes of overhead per datagram. |
| 595 | |
| 596 | See the --mssfix option below for an important related option to --fragment. |
| 597 | |
| 598 | It should also be noted that this option is not meant to replace UDP fragmentation at the IP stack level. It is only |
| 599 | meant as a last resort when path MTU discovery is broken. Using this option is less efficient than fixing path MTU dis‐ |
| 600 | covery for your IP link and using native IP fragmentation instead. |
| 601 | |
| 602 | Having said that, there are circumstances where using OpenVPN's internal fragmentation capability may be your only |
| 603 | option, such as tunneling a UDP multicast stream which requires fragmentation. |
| 604 | |
| 605 | --mssfix max |
| 606 | Announce to TCP sessions running over the tunnel that they should limit their send packet sizes such that after OpenVPN |
| 607 | has encapsulated them, the resulting UDP packet size that OpenVPN sends to its peer will not exceed max bytes. The |
| 608 | default value is 1450. |
| 609 | |
| 610 | The max parameter is interpreted in the same way as the --link-mtu parameter, i.e. the UDP packet size after encapsula‐ |
| 611 | tion overhead has been added in, but not including the UDP header itself. |
| 612 | |
| 613 | The --mssfix option only makes sense when you are using the UDP protocol for OpenVPN peer-to-peer communication, i.e. |
| 614 | --proto udp. |
| 615 | |
| 616 | --mssfix and --fragment can be ideally used together, where --mssfix will try to keep TCP from needing packet fragmenta‐ |
| 617 | tion in the first place, and if big packets come through anyhow (from protocols other than TCP), --fragment will inter‐ |
| 618 | nally fragment them. |
| 619 | |
| 620 | Both --fragment and --mssfix are designed to work around cases where Path MTU discovery is broken on the network path |
| 621 | between OpenVPN peers. |
| 622 | |
| 623 | The usual symptom of such a breakdown is an OpenVPN connection which successfully starts, but then stalls during active |
| 624 | usage. |
| 625 | |
| 626 | If --fragment and --mssfix are used together, --mssfix will take its default max parameter from the --fragment max |
| 627 | option. |
| 628 | |
| 629 | Therefore, one could lower the maximum UDP packet size to 1300 (a good first try for solving MTU-related connection |
| 630 | problems) with the following options: |
| 631 | |
| 632 | --tun-mtu 1500 --fragment 1300 --mssfix |
| 633 | |
| 634 | --sndbuf size |
| 635 | Set the TCP/UDP socket send buffer size. Currently defaults to 65536 bytes. |
| 636 | |
| 637 | --rcvbuf size |
| 638 | Set the TCP/UDP socket receive buffer size. Currently defaults to 65536 bytes. |
| 639 | |
| 640 | --mark value |
| 641 | Mark encrypted packets being sent with value. The mark value can be matched in policy routing and packetfilter rules. |
| 642 | This option is only supported in Linux and does nothing on other operating systems. |
| 643 | |
| 644 | --socket-flags flags... |
| 645 | Apply the given flags to the OpenVPN transport socket. Currently, only TCP_NODELAY is supported. |
| 646 | |
| 647 | The TCP_NODELAY socket flag is useful in TCP mode, and causes the kernel to send tunnel packets immediately over the TCP |
| 648 | connection without trying to group several smaller packets into a larger packet. This can result in a considerably |
| 649 | improvement in latency. |
| 650 | |
| 651 | This option is pushable from server to client, and should be used on both client and server for maximum effect. |
| 652 | |
| 653 | --txqueuelen n |
| 654 | (Linux only) Set the TX queue length on the TUN/TAP interface. Currently defaults to 100. |
| 655 | |
| 656 | --shaper n |
| 657 | Limit bandwidth of outgoing tunnel data to n bytes per second on the TCP/UDP port. If you want to limit the bandwidth |
| 658 | in both directions, use this option on both peers. |
| 659 | |
| 660 | OpenVPN uses the following algorithm to implement traffic shaping: Given a shaper rate of n bytes per second, after a |
| 661 | datagram write of b bytes is queued on the TCP/UDP port, wait a minimum of (b / n) seconds before queuing the next |
| 662 | write. |
| 663 | |
| 664 | It should be noted that OpenVPN supports multiple tunnels between the same two peers, allowing you to construct full- |
| 665 | speed and reduced bandwidth tunnels at the same time, routing low-priority data such as off-site backups over the |
| 666 | reduced bandwidth tunnel, and other data over the full-speed tunnel. |
| 667 | |
| 668 | Also note that for low bandwidth tunnels (under 1000 bytes per second), you should probably use lower MTU values as well |
| 669 | (see above), otherwise the packet latency will grow so large as to trigger timeouts in the TLS layer and TCP connections |
| 670 | running over the tunnel. |
| 671 | |
| 672 | OpenVPN allows n to be between 100 bytes/sec and 100 Mbytes/sec. |
| 673 | |
| 674 | --inactive n [bytes] |
| 675 | Causes OpenVPN to exit after n seconds of inactivity on the TUN/TAP device. The time length of inactivity is measured |
| 676 | since the last incoming or outgoing tunnel packet. The default value is 0 seconds, which disables this feature. |
| 677 | |
| 678 | If the optional bytes parameter is included, exit if less than bytes of combined in/out traffic are produced on the |
| 679 | tun/tap device in n seconds. |
| 680 | |
| 681 | In any case, OpenVPN's internal ping packets (which are just keepalives) and TLS control packets are not considered |
| 682 | "activity", nor are they counted as traffic, as they are used internally by OpenVPN and are not an indication of actual |
| 683 | user activity. |
| 684 | |
| 685 | --ping n |
| 686 | Ping remote over the TCP/UDP control channel if no packets have been sent for at least n seconds (specify --ping on both |
| 687 | peers to cause ping packets to be sent in both directions since OpenVPN ping packets are not echoed like IP ping pack‐ |
| 688 | ets). When used in one of OpenVPN's secure modes (where --secret, --tls-server, or --tls-client is specified), the ping |
| 689 | packet will be cryptographically secure. |
| 690 | |
| 691 | This option has two intended uses: |
| 692 | |
| 693 | (1) Compatibility with stateful firewalls. The periodic ping will ensure that a stateful firewall rule which allows |
| 694 | OpenVPN UDP packets to pass will not time out. |
| 695 | |
| 696 | (2) To provide a basis for the remote to test the existence of its peer using the --ping-exit option. |
| 697 | |
| 698 | --ping-exit n |
| 699 | Causes OpenVPN to exit after n seconds pass without reception of a ping or other packet from remote. This option can be |
| 700 | combined with --inactive, --ping, and --ping-exit to create a two-tiered inactivity disconnect. |
| 701 | |
| 702 | For example, |
| 703 | |
| 704 | openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60 |
| 705 | |
| 706 | when used on both peers will cause OpenVPN to exit within 60 seconds if its peer disconnects, but will exit after one |
| 707 | hour if no actual tunnel data is exchanged. |
| 708 | |
| 709 | --ping-restart n |
| 710 | Similar to --ping-exit, but trigger a SIGUSR1 restart after n seconds pass without reception of a ping or other packet |
| 711 | from remote. |
| 712 | |
| 713 | This option is useful in cases where the remote peer has a dynamic IP address and a low-TTL DNS name is used to track |
| 714 | the IP address using a service such as http://dyndns.org/ + a dynamic DNS client such as ddclient. |
| 715 | |
| 716 | If the peer cannot be reached, a restart will be triggered, causing the hostname used with --remote to be re-resolved |
| 717 | (if --resolv-retry is also specified). |
| 718 | |
| 719 | In server mode, --ping-restart, --inactive, or any other type of internally generated signal will always be applied to |
| 720 | individual client instance objects, never to whole server itself. Note also in server mode that any internally gener‐ |
| 721 | ated signal which would normally cause a restart, will cause the deletion of the client instance object instead. |
| 722 | |
| 723 | In client mode, the --ping-restart parameter is set to 120 seconds by default. This default will hold until the client |
| 724 | pulls a replacement value from the server, based on the --keepalive setting in the server configuration. To disable the |
| 725 | 120 second default, set --ping-restart 0 on the client. |
| 726 | |
| 727 | See the signals section below for more information on SIGUSR1. |
| 728 | |
| 729 | Note that the behavior of SIGUSR1 can be modified by the --persist-tun, --persist-key, --persist-local-ip, and --per‐ |
| 730 | sist-remote-ip options. |
| 731 | |
| 732 | Also note that --ping-exit and --ping-restart are mutually exclusive and cannot be used together. |
| 733 | |
| 734 | --keepalive n m |
| 735 | A helper directive designed to simplify the expression of --ping and --ping-restart in server mode configurations. |
| 736 | |
| 737 | For example, --keepalive 10 60 expands as follows: |
| 738 | |
| 739 | if mode server: |
| 740 | ping 10 |
| 741 | ping-restart 120 |
| 742 | push "ping 10" |
| 743 | push "ping-restart 60" |
| 744 | else |
| 745 | ping 10 |
| 746 | ping-restart 60 |
| 747 | |
| 748 | --ping-timer-rem |
| 749 | Run the --ping-exit / --ping-restart timer only if we have a remote address. Use this option if you are starting the |
| 750 | daemon in listen mode (i.e. without an explicit --remote peer), and you don't want to start clocking timeouts until a |
| 751 | remote peer connects. |
| 752 | |
| 753 | --persist-tun |
| 754 | Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 or --ping-restart restarts. |
| 755 | |
| 756 | SIGUSR1 is a restart signal similar to SIGHUP, but which offers finer-grained control over reset options. |
| 757 | |
| 758 | --persist-key |
| 759 | Don't re-read key files across SIGUSR1 or --ping-restart. |
| 760 | |
| 761 | This option can be combined with --user nobody to allow restarts triggered by the SIGUSR1 signal. Normally if you drop |
| 762 | root privileges in OpenVPN, the daemon cannot be restarted since it will now be unable to re-read protected key files. |
| 763 | |
| 764 | This option solves the problem by persisting keys across SIGUSR1 resets, so they don't need to be re-read. |
| 765 | |
| 766 | --persist-local-ip |
| 767 | Preserve initially resolved local IP address and port number across SIGUSR1 or --ping-restart restarts. |
| 768 | |
| 769 | --persist-remote-ip |
| 770 | Preserve most recently authenticated remote IP address and port number across SIGUSR1 or --ping-restart restarts. |
| 771 | |
| 772 | --mlock |
| 773 | Disable paging by calling the POSIX mlockall function. Requires that OpenVPN be initially run as root (though OpenVPN |
| 774 | can subsequently downgrade its UID using the --user option). |
| 775 | |
| 776 | Using this option ensures that key material and tunnel data are never written to disk due to virtual memory paging oper‐ |
| 777 | ations which occur under most modern operating systems. It ensures that even if an attacker was able to crack the box |
| 778 | running OpenVPN, he would not be able to scan the system swap file to recover previously used ephemeral keys, which are |
| 779 | used for a period of time governed by the --reneg options (see below), then are discarded. |
| 780 | |
| 781 | The downside of using --mlock is that it will reduce the amount of physical memory available to other applications. |
| 782 | |
| 783 | --up cmd |
| 784 | Run command cmd after successful TUN/TAP device open (pre --user UID change). |
| 785 | |
| 786 | cmd consists of a path to script (or executable program), optionally followed by arguments. The path and arguments may |
| 787 | be single- or double-quoted and/or escaped using a backslash, and should be separated by one or more spaces. |
| 788 | |
| 789 | The up command is useful for specifying route commands which route IP traffic destined for private subnets which exist |
| 790 | at the other end of the VPN connection into the tunnel. |
| 791 | |
| 792 | For --dev tun execute as: |
| 793 | |
| 794 | cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [ init | restart ] |
| 795 | |
| 796 | For --dev tap execute as: |
| 797 | |
| 798 | cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [ init | restart ] |
| 799 | |
| 800 | See the "Environmental Variables" section below for additional parameters passed as environmental variables. |
| 801 | |
| 802 | Note that if cmd includes arguments, all OpenVPN-generated arguments will be appended to them to build an argument list |
| 803 | with which the executable will be called. |
| 804 | |
| 805 | Typically, cmd will run a script to add routes to the tunnel. |
| 806 | |
| 807 | Normally the up script is called after the TUN/TAP device is opened. In this context, the last command line parameter |
| 808 | passed to the script will be init. If the --up-restart option is also used, the up script will be called for restarts |
| 809 | as well. A restart is considered to be a partial reinitialization of OpenVPN where the TUN/TAP instance is preserved |
| 810 | (the --persist-tun option will enable such preservation). A restart can be generated by a SIGUSR1 signal, a --ping- |
| 811 | restart timeout, or a connection reset when the TCP protocol is enabled with the --proto option. If a restart occurs, |
| 812 | and --up-restart has been specified, the up script will be called with restart as the last parameter. |
| 813 | |
| 814 | The following standalone example shows how the --up script can be called in both an initialization and restart context. |
| 815 | (NOTE: for security reasons, don't run the following example unless UDP port 9999 is blocked by your firewall. Also, |
| 816 | the example will run indefinitely, so you should abort with control-c). |
| 817 | |
| 818 | openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 --up 'echo up' --down 'echo down' --persist-tun --up-restart |
| 819 | |
| 820 | Note that OpenVPN also provides the --ifconfig option to automatically ifconfig the TUN device, eliminating the need to |
| 821 | define an --up script, unless you also want to configure routes in the --up script. |
| 822 | |
| 823 | If --ifconfig is also specified, OpenVPN will pass the ifconfig local and remote endpoints on the command line to the |
| 824 | --up script so that they can be used to configure routes such as: |
| 825 | |
| 826 | route add -net 10.0.0.0 netmask 255.255.255.0 gw $5 |
| 827 | |
| 828 | --up-delay |
| 829 | Delay TUN/TAP open and possible --up script execution until after TCP/UDP connection establishment with peer. |
| 830 | |
| 831 | In --proto udp mode, this option normally requires the use of --ping to allow connection initiation to be sensed in the |
| 832 | absence of tunnel data, since UDP is a "connectionless" protocol. |
| 833 | |
| 834 | On Windows, this option will delay the TAP-Win32 media state transitioning to "connected" until connection establish‐ |
| 835 | ment, i.e. the receipt of the first authenticated packet from the peer. |
| 836 | |
| 837 | --down cmd |
| 838 | Run command cmd after TUN/TAP device close (post --user UID change and/or --chroot ). cmd consists of a path to script |
| 839 | (or executable program), optionally followed by arguments. The path and arguments may be single- or double-quoted and/or |
| 840 | escaped using a backslash, and should be separated by one or more spaces. |
| 841 | |
| 842 | Called with the same parameters and environmental variables as the --up option above. |
| 843 | |
| 844 | Note that if you reduce privileges by using --user and/or --group, your --down script will also run at reduced privi‐ |
| 845 | lege. |
| 846 | |
| 847 | --down-pre |
| 848 | Call --down cmd/script before, rather than after, TUN/TAP close. |
| 849 | |
| 850 | --up-restart |
| 851 | Enable the --up and --down scripts to be called for restarts as well as initial program start. This option is described |
| 852 | more fully above in the --up option documentation. |
| 853 | |
| 854 | --setenv name value |
| 855 | Set a custom environmental variable name=value to pass to script. |
| 856 | |
| 857 | --setenv FORWARD_COMPATIBLE 1 |
| 858 | Relax config file syntax checking so that unknown directives will trigger a warning but not a fatal error, on the |
| 859 | assumption that a given unknown directive might be valid in future OpenVPN versions. |
| 860 | |
| 861 | This option should be used with caution, as there are good security reasons for having OpenVPN fail if it detects prob‐ |
| 862 | lems in a config file. Having said that, there are valid reasons for wanting new software features to gracefully |
| 863 | degrade when encountered by older software versions. |
| 864 | |
| 865 | --setenv-safe name value |
| 866 | Set a custom environmental variable OPENVPN_name=value to pass to script. |
| 867 | |
| 868 | This directive is designed to be pushed by the server to clients, and the prepending of "OPENVPN_" to the environmental |
| 869 | variable is a safety precaution to prevent a LD_PRELOAD style attack from a malicious or compromised server. |
| 870 | |
| 871 | --script-security level [method] |
| 872 | This directive offers policy-level control over OpenVPN's usage of external programs and scripts. Lower level values |
| 873 | are more restrictive, higher values are more permissive. Settings for level: |
| 874 | |
| 875 | 0 -- Strictly no calling of external programs. |
| 876 | 1 -- (Default) Only call built-in executables such as ifconfig, ip, route, or netsh. |
| 877 | 2 -- Allow calling of built-in executables and user-defined scripts. |
| 878 | 3 -- Allow passwords to be passed to scripts via environmental variables (potentially unsafe). |
| 879 | |
| 880 | The method parameter indicates how OpenVPN should call external commands and scripts. Settings for method: |
| 881 | |
| 882 | execve -- (default) Use execve() function on Unix family OSes and CreateProcess() on Windows. |
| 883 | system -- Use system() function (deprecated and less safe since the external program command line is subject to shell |
| 884 | expansion). |
| 885 | |
| 886 | The --script-security option was introduced in OpenVPN 2.1_rc9. For configuration file compatibility with previous |
| 887 | OpenVPN versions, use: --script-security 3 system |
| 888 | |
| 889 | --disable-occ |
| 890 | Don't output a warning message if option inconsistencies are detected between peers. An example of an option inconsis‐ |
| 891 | tency would be where one peer uses --dev tun while the other peer uses --dev tap. |
| 892 | |
| 893 | Use of this option is discouraged, but is provided as a temporary fix in situations where a recent version of OpenVPN |
| 894 | must connect to an old version. |
| 895 | |
| 896 | --user user |
| 897 | Change the user ID of the OpenVPN process to user after initialization, dropping privileges in the process. This option |
| 898 | is useful to protect the system in the event that some hostile party was able to gain control of an OpenVPN session. |
| 899 | Though OpenVPN's security features make this unlikely, it is provided as a second line of defense. |
| 900 | |
| 901 | By setting user to nobody or somebody similarly unprivileged, the hostile party would be limited in what damage they |
| 902 | could cause. Of course once you take away privileges, you cannot return them to an OpenVPN session. This means, for |
| 903 | example, that if you want to reset an OpenVPN daemon with a SIGUSR1 signal (for example in response to a DHCP reset), |
| 904 | you should make use of one or more of the --persist options to ensure that OpenVPN doesn't need to execute any privi‐ |
| 905 | leged operations in order to restart (such as re-reading key files or running ifconfig on the TUN device). |
| 906 | |
| 907 | --group group |
| 908 | Similar to the --user option, this option changes the group ID of the OpenVPN process to group after initialization. |
| 909 | |
| 910 | --cd dir |
| 911 | Change directory to dir prior to reading any files such as configuration files, key files, scripts, etc. dir should be |
| 912 | an absolute path, with a leading "/", and without any references to the current directory such as "." or "..". |
| 913 | |
| 914 | This option is useful when you are running OpenVPN in --daemon mode, and you want to consolidate all of your OpenVPN |
| 915 | control files in one location. |
| 916 | |
| 917 | --chroot dir |
| 918 | Chroot to dir after initialization. --chroot essentially redefines dir as being the top level directory tree (/). |
| 919 | OpenVPN will therefore be unable to access any files outside this tree. This can be desirable from a security stand‐ |
| 920 | point. |
| 921 | |
| 922 | Since the chroot operation is delayed until after initialization, most OpenVPN options that reference files will operate |
| 923 | in a pre-chroot context. |
| 924 | |
| 925 | In many cases, the dir parameter can point to an empty directory, however complications can result when scripts or |
| 926 | restarts are executed after the chroot operation. |
| 927 | |
| 928 | --setcon context |
| 929 | Apply SELinux context after initialization. This essentially provides the ability to restrict OpenVPN's rights to only |
| 930 | network I/O operations, thanks to SELinux. This goes further than --user and --chroot in that those two, while being |
| 931 | great security features, unfortunately do not protect against privilege escalation by exploitation of a vulnerable sys‐ |
| 932 | tem call. You can of course combine all three, but please note that since setcon requires access to /proc you will have |
| 933 | to provide it inside the chroot directory (e.g. with mount --bind). |
| 934 | |
| 935 | Since the setcon operation is delayed until after initialization, OpenVPN can be restricted to just network-related sys‐ |
| 936 | tem calls, whereas by applying the context before startup (such as the OpenVPN one provided in the SELinux Reference |
| 937 | Policies) you will have to allow many things required only during initialization. |
| 938 | |
| 939 | Like with chroot, complications can result when scripts or restarts are executed after the setcon operation, which is |
| 940 | why you should really consider using the --persist-key and --persist-tun options. |
| 941 | |
| 942 | --daemon [progname] |
| 943 | Become a daemon after all initialization functions are completed. This option will cause all message and error output |
| 944 | to be sent to the syslog file (such as /var/log/messages), except for the output of scripts and ifconfig commands, which |
| 945 | will go to /dev/null unless otherwise redirected. The syslog redirection occurs immediately at the point that --daemon |
| 946 | is parsed on the command line even though the daemonization point occurs later. If one of the --log options is present, |
| 947 | it will supercede syslog redirection. |
| 948 | |
| 949 | The optional progname parameter will cause OpenVPN to report its program name to the system logger as progname. This |
| 950 | can be useful in linking OpenVPN messages in the syslog file with specific tunnels. When unspecified, progname defaults |
| 951 | to "openvpn". |
| 952 | |
| 953 | When OpenVPN is run with the --daemon option, it will try to delay daemonization until the majority of initialization |
| 954 | functions which are capable of generating fatal errors are complete. This means that initialization scripts can test |
| 955 | the return status of the openvpn command for a fairly reliable indication of whether the command has correctly initial‐ |
| 956 | ized and entered the packet forwarding event loop. |
| 957 | |
| 958 | In OpenVPN, the vast majority of errors which occur after initialization are non-fatal. |
| 959 | |
| 960 | --syslog [progname] |
| 961 | Direct log output to system logger, but do not become a daemon. See --daemon directive above for description of prog‐ |
| 962 | name parameter. |
| 963 | |
| 964 | --errors-to-stderr |
| 965 | Output errors to stderr instead of stdout unless log output is redirected by one of the --log options. |
| 966 | |
| 967 | --passtos |
| 968 | Set the TOS field of the tunnel packet to what the payload's TOS is. |
| 969 | |
| 970 | --inetd [wait|nowait] [progname] |
| 971 | Use this option when OpenVPN is being run from the inetd or xinetd(8) server. |
| 972 | |
| 973 | The wait/nowait option must match what is specified in the inetd/xinetd config file. The nowait mode can only be used |
| 974 | with --proto tcp-server. The default is wait. The nowait mode can be used to instantiate the OpenVPN daemon as a clas‐ |
| 975 | sic TCP server, where client connection requests are serviced on a single port number. For additional information on |
| 976 | this kind of configuration, see the OpenVPN FAQ: http://openvpn.net/faq.html#oneport |
| 977 | |
| 978 | This option precludes the use of --daemon, --local, or --remote. Note that this option causes message and error output |
| 979 | to be handled in the same way as the --daemon option. The optional progname parameter is also handled exactly as in |
| 980 | --daemon. |
| 981 | |
| 982 | Also note that in wait mode, each OpenVPN tunnel requires a separate TCP/UDP port and a separate inetd or xinetd entry. |
| 983 | See the OpenVPN 1.x HOWTO for an example on using OpenVPN with xinetd: http://openvpn.net/1xhowto.html |
| 984 | |
| 985 | --log file |
| 986 | Output logging messages to file, including output to stdout/stderr which is generated by called scripts. If file |
| 987 | already exists it will be truncated. This option takes effect immediately when it is parsed in the command line and |
| 988 | will supercede syslog output if --daemon or --inetd is also specified. This option is persistent over the entire course |
| 989 | of an OpenVPN instantiation and will not be reset by SIGHUP, SIGUSR1, or --ping-restart. |
| 990 | |
| 991 | Note that on Windows, when OpenVPN is started as a service, logging occurs by default without the need to specify this |
| 992 | option. |
| 993 | |
| 994 | --log-append file |
| 995 | Append logging messages to file. If file does not exist, it will be created. This option behaves exactly like --log |
| 996 | except that it appends to rather than truncating the log file. |
| 997 | |
| 998 | --suppress-timestamps |
| 999 | Avoid writing timestamps to log messages, even when they otherwise would be prepended. In particular, this applies to |
| 1000 | log messages sent to stdout. |
| 1001 | |
| 1002 | --writepid file |
| 1003 | Write OpenVPN's main process ID to file. |
| 1004 | |
| 1005 | --nice n |
| 1006 | Change process priority after initialization ( n greater than 0 is lower priority, n less than zero is higher priority). |
| 1007 | |
| 1008 | --fast-io |
| 1009 | (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to poll/epoll/select prior to the write operation. |
| 1010 | The purpose of such a call would normally be to block until the device or socket is ready to accept the write. Such |
| 1011 | blocking is unnecessary on some platforms which don't support write blocking on UDP sockets or TUN/TAP devices. In such |
| 1012 | cases, one can optimize the event loop by avoiding the poll/epoll/select call, improving CPU efficiency by 5% to 10%. |
| 1013 | |
| 1014 | This option can only be used on non-Windows systems, when --proto udp is specified, and when --shaper is NOT specified. |
| 1015 | |
| 1016 | --multihome |
| 1017 | Configure a multi-homed UDP server. This option can be used when OpenVPN has been configured to listen on all inter‐ |
| 1018 | faces, and will attempt to bind client sessions to the interface on which packets are being received, so that outgoing |
| 1019 | packets will be sent out of the same interface. Note that this option is only relevant for UDP servers and currently is |
| 1020 | only implemented on Linux. |
| 1021 | |
| 1022 | Note: clients connecting to a --multihome server should always use the --nobind option. |
| 1023 | |
| 1024 | --echo [parms...] |
| 1025 | Echo parms to log output. |
| 1026 | |
| 1027 | Designed to be used to send messages to a controlling application which is receiving the OpenVPN log output. |
| 1028 | |
| 1029 | --remap-usr1 signal |
| 1030 | Control whether internally or externally generated SIGUSR1 signals are remapped to SIGHUP (restart without persisting |
| 1031 | state) or SIGTERM (exit). |
| 1032 | |
| 1033 | signal can be set to "SIGHUP" or "SIGTERM". By default, no remapping occurs. |
| 1034 | |
| 1035 | --verb n |
| 1036 | Set output verbosity to n (default=1). Each level shows all info from the previous levels. Level 3 is recommended if |
| 1037 | you want a good summary of what's happening without being swamped by output. |
| 1038 | |
| 1039 | 0 -- No output except fatal errors. |
| 1040 | 1 to 4 -- Normal usage range. |
| 1041 | 5 -- Output R and W characters to the console for each packet read and write, uppercase is used for TCP/UDP packets and |
| 1042 | lowercase is used for TUN/TAP packets. |
| 1043 | 6 to 11 -- Debug info range (see errlevel.h for additional information on debug levels). |
| 1044 | |
| 1045 | --status file [n] |
| 1046 | Write operational status to file every n seconds. |
| 1047 | |
| 1048 | Status can also be written to the syslog by sending a SIGUSR2 signal. |
| 1049 | |
| 1050 | --status-version [n] |
| 1051 | Choose the status file format version number. Currently n can be 1, 2, or 3 and defaults to 1. |
| 1052 | |
| 1053 | --mute n |
| 1054 | Log at most n consecutive messages in the same category. This is useful to limit repetitive logging of similar message |
| 1055 | types. |
| 1056 | |
| 1057 | --comp-lzo [mode] |
| 1058 | Use fast LZO compression -- may add up to 1 byte per packet for incompressible data. mode may be "yes", "no", or "adap‐ |
| 1059 | tive" (default). |
| 1060 | |
| 1061 | In a server mode setup, it is possible to selectively turn compression on or off for individual clients. |
| 1062 | |
| 1063 | First, make sure the client-side config file enables selective compression by having at least one --comp-lzo directive, |
| 1064 | such as --comp-lzo no. This will turn off compression by default, but allow a future directive push from the server to |
| 1065 | dynamically change the on/off/adaptive setting. |
| 1066 | |
| 1067 | Next in a --client-config-dir file, specify the compression setting for the client, for example: |
| 1068 | |
| 1069 | comp-lzo yes |
| 1070 | push "comp-lzo yes" |
| 1071 | |
| 1072 | The first line sets the comp-lzo setting for the server side of the link, the second sets the client side. |
| 1073 | |
| 1074 | --comp-noadapt |
| 1075 | When used in conjunction with --comp-lzo, this option will disable OpenVPN's adaptive compression algorithm. Normally, |
| 1076 | adaptive compression is enabled with --comp-lzo. |
| 1077 | |
| 1078 | Adaptive compression tries to optimize the case where you have compression enabled, but you are sending predominantly |
| 1079 | uncompressible (or pre-compressed) packets over the tunnel, such as an FTP or rsync transfer of a large, compressed |
| 1080 | file. With adaptive compression, OpenVPN will periodically sample the compression process to measure its efficiency. |
| 1081 | If the data being sent over the tunnel is already compressed, the compression efficiency will be very low, triggering |
| 1082 | openvpn to disable compression for a period of time until the next re-sample test. |
| 1083 | |
| 1084 | --management IP port [pw-file] |
| 1085 | Enable a TCP server on IP:port to handle daemon management functions. pw-file, if specified, is a password file (pass‐ |
| 1086 | word on first line) or "stdin" to prompt from standard input. The password provided will set the password which TCP |
| 1087 | clients will need to provide in order to access management functions. |
| 1088 | |
| 1089 | The management interface can also listen on a unix domain socket, for those platforms that support it. To use a unix |
| 1090 | domain socket, specify the unix socket pathname in place of IP and set port to 'unix'. While the default behavior is to |
| 1091 | create a unix domain socket that may be connected to by any process, the --management-client-user and --management- |
| 1092 | client-group directives can be used to restrict access. |
| 1093 | |
| 1094 | The management interface provides a special mode where the TCP management link can operate over the tunnel itself. To |
| 1095 | enable this mode, set IP = "tunnel". Tunnel mode will cause the management interface to listen for a TCP connection on |
| 1096 | the local VPN address of the TUN/TAP interface. |
| 1097 | |
| 1098 | While the management port is designed for programmatic control of OpenVPN by other applications, it is possible to tel‐ |
| 1099 | net to the port, using a telnet client in "raw" mode. Once connected, type "help" for a list of commands. |
| 1100 | |
| 1101 | For detailed documentation on the management interface, see the management-notes.txt file in the management folder of |
| 1102 | the OpenVPN source distribution. |
| 1103 | |
| 1104 | It is strongly recommended that IP be set to 127.0.0.1 (localhost) to restrict accessibility of the management server to |
| 1105 | local clients. |
| 1106 | |
| 1107 | --management-client |
| 1108 | Management interface will connect as a TCP client to IP:port specified by --management rather than listen as a TCP |
| 1109 | server. |
| 1110 | |
| 1111 | --management-query-passwords |
| 1112 | Query management channel for private key password and --auth-user-pass username/password. Only query the management |
| 1113 | channel for inputs which ordinarily would have been queried from the console. |
| 1114 | |
| 1115 | --management-query-remote |
| 1116 | Allow management interface to override --remote directives (client-only). |
| 1117 | |
| 1118 | --management-forget-disconnect |
| 1119 | Make OpenVPN forget passwords when management session disconnects. |
| 1120 | |
| 1121 | This directive does not affect the --http-proxy username/password. It is always cached. |
| 1122 | |
| 1123 | --management-hold |
| 1124 | Start OpenVPN in a hibernating state, until a client of the management interface explicitly starts it with the hold |
| 1125 | release command. |
| 1126 | |
| 1127 | --management-signal |
| 1128 | Send SIGUSR1 signal to OpenVPN if management session disconnects. This is useful when you wish to disconnect an OpenVPN |
| 1129 | session on user logoff. |
| 1130 | |
| 1131 | --management-log-cache n |
| 1132 | Cache the most recent n lines of log file history for usage by the management channel. |
| 1133 | |
| 1134 | --management-up-down |
| 1135 | Report tunnel up/down events to management interface. |
| 1136 | |
| 1137 | --management-client-auth |
| 1138 | Gives management interface client the responsibility to authenticate clients after their client certificate has been |
| 1139 | verified. See management-notes.txt in OpenVPN distribution for detailed notes. |
| 1140 | |
| 1141 | --management-client-pf |
| 1142 | Management interface clients must specify a packet filter file for each connecting client. See management-notes.txt in |
| 1143 | OpenVPN distribution for detailed notes. |
| 1144 | |
| 1145 | --management-client-user u |
| 1146 | When the management interface is listening on a unix domain socket, only allow connections from user u. |
| 1147 | |
| 1148 | --management-client-group g |
| 1149 | When the management interface is listening on a unix domain socket, only allow connections from group g. |
| 1150 | |
| 1151 | --plugin module-pathname [init-string] |
| 1152 | Load plug-in module from the file module-pathname, passing init-string as an argument to the module initialization func‐ |
| 1153 | tion. Multiple plugin modules may be loaded into one OpenVPN process. |
| 1154 | |
| 1155 | For more information and examples on how to build OpenVPN plug-in modules, see the README file in the plugin folder of |
| 1156 | the OpenVPN source distribution. |
| 1157 | |
| 1158 | If you are using an RPM install of OpenVPN, see /usr/share/openvpn/plugin. The documentation is in doc and the actual |
| 1159 | plugin modules are in lib. |
| 1160 | |
| 1161 | Multiple plugin modules can be cascaded, and modules can be used in tandem with scripts. The modules will be called by |
| 1162 | OpenVPN in the order that they are declared in the config file. If both a plugin and script are configured for the same |
| 1163 | callback, the script will be called last. If the return code of the module/script controls an authentication function |
| 1164 | (such as tls-verify, auth-user-pass-verify, or client-connect), then every module and script must return success (0) in |
| 1165 | order for the connection to be authenticated. |
| 1166 | |
| 1167 | Server Mode |
| 1168 | Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is supported, and can be enabled with the --mode server option. |
| 1169 | In server mode, OpenVPN will listen on a single port for incoming client connections. All client connections will be routed |
| 1170 | through a single tun or tap interface. This mode is designed for scalability and should be able to support hundreds or even |
| 1171 | thousands of clients on sufficiently fast hardware. SSL/TLS authentication must be used in this mode. |
| 1172 | |
| 1173 | --server network netmask |
| 1174 | A helper directive designed to simplify the configuration of OpenVPN's server mode. This directive will set up an Open‐ |
| 1175 | VPN server which will allocate addresses to clients out of the given network/netmask. The server itself will take the |
| 1176 | ".1" address of the given network for use as the server-side endpoint of the local TUN/TAP interface. |
| 1177 | |
| 1178 | For example, --server 10.8.0.0 255.255.255.0 expands as follows: |
| 1179 | |
| 1180 | mode server |
| 1181 | tls-server |
| 1182 | push "topology [topology]" |
| 1183 | |
| 1184 | if dev tun AND (topology == net30 OR topology == p2p): |
| 1185 | ifconfig 10.8.0.1 10.8.0.2 |
| 1186 | if !nopool: |
| 1187 | ifconfig-pool 10.8.0.4 10.8.0.251 |
| 1188 | route 10.8.0.0 255.255.255.0 |
| 1189 | if client-to-client: |
| 1190 | push "route 10.8.0.0 255.255.255.0" |
| 1191 | else if topology == net30: |
| 1192 | push "route 10.8.0.1" |
| 1193 | |
| 1194 | if dev tap OR (dev tun AND topology == subnet): |
| 1195 | ifconfig 10.8.0.1 255.255.255.0 |
| 1196 | if !nopool: |
| 1197 | ifconfig-pool 10.8.0.2 10.8.0.254 255.255.255.0 |
| 1198 | push "route-gateway 10.8.0.1" |
| 1199 | |
| 1200 | Don't use --server if you are ethernet bridging. Use --server-bridge instead. |
| 1201 | |
| 1202 | --server-bridge gateway netmask pool-start-IP pool-end-IP |
| 1203 | |
| 1204 | --server-bridge ['nogw'] |
| 1205 | |
| 1206 | A helper directive similar to --server which is designed to simplify the configuration of OpenVPN's server mode in eth‐ |
| 1207 | ernet bridging configurations. |
| 1208 | |
| 1209 | If --server-bridge is used without any parameters, it will enable a DHCP-proxy mode, where connecting OpenVPN clients |
| 1210 | will receive an IP address for their TAP adapter from the DHCP server running on the OpenVPN server-side LAN. Note that |
| 1211 | only clients that support the binding of a DHCP client with the TAP adapter (such as Windows) can support this mode. |
| 1212 | The optional nogw flag (advanced) indicates that gateway information should not be pushed to the client. |
| 1213 | |
| 1214 | To configure ethernet bridging, you must first use your OS's bridging capability to bridge the TAP interface with the |
| 1215 | ethernet NIC interface. For example, on Linux this is done with the brctl tool, and with Windows XP it is done in the |
| 1216 | Network Connections Panel by selecting the ethernet and TAP adapters and right-clicking on "Bridge Connections". |
| 1217 | |
| 1218 | Next you you must manually set the IP/netmask on the bridge interface. The gateway and netmask parameters to --server- |
| 1219 | bridge can be set to either the IP/netmask of the bridge interface, or the IP/netmask of the default gateway/router on |
| 1220 | the bridged subnet. |
| 1221 | |
| 1222 | Finally, set aside a IP range in the bridged subnet, denoted by pool-start-IP and pool-end-IP, for OpenVPN to allocate |
| 1223 | to connecting clients. |
| 1224 | |
| 1225 | For example, server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 10.8.0.254 expands as follows: |
| 1226 | |
| 1227 | mode server |
| 1228 | tls-server |
| 1229 | |
| 1230 | ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0 |
| 1231 | push "route-gateway 10.8.0.4" |
| 1232 | |
| 1233 | In another example, --server-bridge (without parameters) expands as follows: |
| 1234 | |
| 1235 | mode server |
| 1236 | tls-server |
| 1237 | |
| 1238 | push "route-gateway dhcp" |
| 1239 | |
| 1240 | Or --server-bridge nogw expands as follows: |
| 1241 | |
| 1242 | mode server |
| 1243 | tls-server |
| 1244 | |
| 1245 | --push option |
| 1246 | Push a config file option back to the client for remote execution. Note that option must be enclosed in double quotes |
| 1247 | (""). The client must specify --pull in its config file. The set of options which can be pushed is limited by both |
| 1248 | feasibility and security. Some options such as those which would execute scripts are banned, since they would effec‐ |
| 1249 | tively allow a compromised server to execute arbitrary code on the client. Other options such as TLS or MTU parameters |
| 1250 | cannot be pushed because the client needs to know them before the connection to the server can be initiated. |
| 1251 | |
| 1252 | This is a partial list of options which can currently be pushed: --route, --route-gateway, --route-delay, --redirect- |
| 1253 | gateway, --ip-win32, --dhcp-option, --inactive, --ping, --ping-exit, --ping-restart, --setenv, --persist-key, --persist- |
| 1254 | tun, --echo, --comp-lzo, --socket-flags, --sndbuf, --rcvbuf |
| 1255 | |
| 1256 | --push-reset |
| 1257 | Don't inherit the global push list for a specific client instance. Specify this option in a client-specific context |
| 1258 | such as with a --client-config-dir configuration file. This option will ignore --push options at the global config file |
| 1259 | level. |
| 1260 | |
| 1261 | --push-peer-info |
| 1262 | Push additional information about the client to server. The additional information consists of the following data: |
| 1263 | |
| 1264 | IV_VER=<version> -- the client OpenVPN version |
| 1265 | |
| 1266 | IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win] -- the client OS platform |
| 1267 | |
| 1268 | IV_HWADDR=<mac address> -- the MAC address of clients default gateway |
| 1269 | |
| 1270 | IV_LZO_STUB=1 -- if client was built with LZO stub capability |
| 1271 | |
| 1272 | UV_<name>=<value> -- client environment variables whose names start with "UV_" |
| 1273 | |
| 1274 | --disable |
| 1275 | Disable a particular client (based on the common name) from connecting. Don't use this option to disable a client due |
| 1276 | to key or password compromise. Use a CRL (certificate revocation list) instead (see the --crl-verify option). |
| 1277 | |
| 1278 | This option must be associated with a specific client instance, which means that it must be specified either in a client |
| 1279 | instance config file using --client-config-dir or dynamically generated using a --client-connect script. |
| 1280 | |
| 1281 | --ifconfig-pool start-IP end-IP [netmask] |
| 1282 | Set aside a pool of subnets to be dynamically allocated to connecting clients, similar to a DHCP server. For tun-style |
| 1283 | tunnels, each client will be given a /30 subnet (for interoperability with Windows clients). For tap-style tunnels, |
| 1284 | individual addresses will be allocated, and the optional netmask parameter will also be pushed to clients. |
| 1285 | |
| 1286 | |
| 1287 | --ifconfig-pool-persist file [seconds] |
| 1288 | Persist/unpersist ifconfig-pool data to file, at seconds intervals (default=600), as well as on program startup and |
| 1289 | shutdown. |
| 1290 | |
| 1291 | The goal of this option is to provide a long-term association between clients (denoted by their common name) and the |
| 1292 | virtual IP address assigned to them from the ifconfig-pool. Maintaining a long-term association is good for clients |
| 1293 | because it allows them to effectively use the --persist-tun option. |
| 1294 | |
| 1295 | file is a comma-delimited ASCII file, formatted as <Common-Name>,<IP-address>. |
| 1296 | |
| 1297 | If seconds = 0, file will be treated as read-only. This is useful if you would like to treat file as a configuration |
| 1298 | file. |
| 1299 | |
| 1300 | Note that the entries in this file are treated by OpenVPN as suggestions only, based on past associations between a com‐ |
| 1301 | mon name and IP address. They do not guarantee that the given common name will always receive the given IP address. If |
| 1302 | you want guaranteed assignment, use --ifconfig-push |
| 1303 | |
| 1304 | --ifconfig-pool-linear |
| 1305 | Modifies the --ifconfig-pool directive to allocate individual TUN interface addresses for clients rather than /30 sub‐ |
| 1306 | nets. NOTE: This option is incompatible with Windows clients. |
| 1307 | |
| 1308 | This option is deprecated, and should be replaced with --topology p2p which is functionally equivalent. |
| 1309 | |
| 1310 | --ifconfig-push local remote-netmask [alias] |
| 1311 | Push virtual IP endpoints for client tunnel, overriding the --ifconfig-pool dynamic allocation. |
| 1312 | |
| 1313 | The parameters local and remote-netmask are set according to the --ifconfig directive which you want to execute on the |
| 1314 | client machine to configure the remote end of the tunnel. Note that the parameters local and remote-netmask are from |
| 1315 | the perspective of the client, not the server. They may be DNS names rather than IP addresses, in which case they will |
| 1316 | be resolved on the server at the time of client connection. |
| 1317 | |
| 1318 | The optional alias parameter may be used in cases where NAT causes the client view of its local endpoint to differ from |
| 1319 | the server view. In this case local/remote-netmask will refer to the server view while alias/remote-netmask will refer |
| 1320 | to the client view. |
| 1321 | |
| 1322 | This option must be associated with a specific client instance, which means that it must be specified either in a client |
| 1323 | instance config file using --client-config-dir or dynamically generated using a --client-connect script. |
| 1324 | |
| 1325 | Remember also to include a --route directive in the main OpenVPN config file which encloses local, so that the kernel |
| 1326 | will know to route it to the server's TUN/TAP interface. |
| 1327 | |
| 1328 | OpenVPN's internal client IP address selection algorithm works as follows: |
| 1329 | |
| 1330 | 1 -- Use --client-connect script generated file for static IP (first choice). |
| 1331 | 2 -- Use --client-config-dir file for static IP (next choice). |
| 1332 | 3 -- Use --ifconfig-pool allocation for dynamic IP (last choice). |
| 1333 | |
| 1334 | --iroute network [netmask] |
| 1335 | Generate an internal route to a specific client. The netmask parameter, if omitted, defaults to 255.255.255.255. |
| 1336 | |
| 1337 | This directive can be used to route a fixed subnet from the server to a particular client, regardless of where the |
| 1338 | client is connecting from. Remember that you must also add the route to the system routing table as well (such as by |
| 1339 | using the --route directive). The reason why two routes are needed is that the --route directive routes the packet from |
| 1340 | the kernel to OpenVPN. Once in OpenVPN, the --iroute directive routes to the specific client. |
| 1341 | |
| 1342 | This option must be specified either in a client instance config file using --client-config-dir or dynamically generated |
| 1343 | using a --client-connect script. |
| 1344 | |
| 1345 | The --iroute directive also has an important interaction with --push "route ...". --iroute essentially defines a subnet |
| 1346 | which is owned by a particular client (we will call this client A). If you would like other clients to be able to reach |
| 1347 | A's subnet, you can use --push "route ..." together with --client-to-client to effect this. In order for all clients |
| 1348 | to see A's subnet, OpenVPN must push this route to all clients EXCEPT for A, since the subnet is already owned by A. |
| 1349 | OpenVPN accomplishes this by not not pushing a route to a client if it matches one of the client's iroutes. |
| 1350 | |
| 1351 | --client-to-client |
| 1352 | Because the OpenVPN server mode handles multiple clients through a single tun or tap interface, it is effectively a |
| 1353 | router. The --client-to-client flag tells OpenVPN to internally route client-to-client traffic rather than pushing all |
| 1354 | client-originating traffic to the TUN/TAP interface. |
| 1355 | |
| 1356 | When this option is used, each client will "see" the other clients which are currently connected. Otherwise, each |
| 1357 | client will only see the server. Don't use this option if you want to firewall tunnel traffic using custom, per-client |
| 1358 | rules. |
| 1359 | |
| 1360 | --duplicate-cn |
| 1361 | Allow multiple clients with the same common name to concurrently connect. In the absence of this option, OpenVPN will |
| 1362 | disconnect a client instance upon connection of a new client having the same common name. |
| 1363 | |
| 1364 | --client-connect cmd |
| 1365 | Run command cmd on client connection. |
| 1366 | |
| 1367 | cmd consists of a path to script (or executable program), optionally followed by arguments. The path and arguments may |
| 1368 | be single- or double-quoted and/or escaped using a backslash, and should be separated by one or more spaces. |
| 1369 | |
| 1370 | The command is passed the common name and IP address of the just-authenticated client as environmental variables (see |
| 1371 | environmental variable section below). The command is also passed the pathname of a freshly created temporary file as |
| 1372 | the last argument (after any arguments specified in cmd ), to be used by the command to pass dynamically generated con‐ |
| 1373 | fig file directives back to OpenVPN. |
| 1374 | |
| 1375 | If the script wants to generate a dynamic config file to be applied on the server when the client connects, it should |
| 1376 | write it to the file named by the last argument. |
| 1377 | |
| 1378 | See the --client-config-dir option below for options which can be legally used in a dynamically generated config file. |
| 1379 | |
| 1380 | Note that the return value of script is significant. If script returns a non-zero error status, it will cause the |
| 1381 | client to be disconnected. |
| 1382 | |
| 1383 | --client-disconnect cmd |
| 1384 | Like --client-connect but called on client instance shutdown. Will not be called unless the --client-connect script and |
| 1385 | plugins (if defined) were previously called on this instance with successful (0) status returns. |
| 1386 | |
| 1387 | The exception to this rule is if the --client-disconnect command or plugins are cascaded, and at least one client-con‐ |
| 1388 | nect function succeeded, then ALL of the client-disconnect functions for scripts and plugins will be called on client |
| 1389 | instance object deletion, even in cases where some of the related client-connect functions returned an error status. |
| 1390 | |
| 1391 | The --client-disconnect command is passed the same pathname as the corresponding --client-connect command as its last |
| 1392 | argument. (after any arguments specified in cmd ). |
| 1393 | |
| 1394 | --client-config-dir dir |
| 1395 | Specify a directory dir for custom client config files. After a connecting client has been authenticated, OpenVPN will |
| 1396 | look in this directory for a file having the same name as the client's X509 common name. If a matching file exists, it |
| 1397 | will be opened and parsed for client-specific configuration options. If no matching file is found, OpenVPN will instead |
| 1398 | try to open and parse a default file called "DEFAULT", which may be provided but is not required. Note that the configu‐ |
| 1399 | ration files must be readable by the OpenVPN process after it has dropped it's root privileges. |
| 1400 | |
| 1401 | This file can specify a fixed IP address for a given client using --ifconfig-push, as well as fixed subnets owned by the |
| 1402 | client using --iroute. |
| 1403 | |
| 1404 | One of the useful properties of this option is that it allows client configuration files to be conveniently created, |
| 1405 | edited, or removed while the server is live, without needing to restart the server. |
| 1406 | |
| 1407 | The following options are legal in a client-specific context: --push, --push-reset, --iroute, --ifconfig-push, and |
| 1408 | --config. |
| 1409 | |
| 1410 | --ccd-exclusive |
| 1411 | Require, as a condition of authentication, that a connecting client has a --client-config-dir file. |
| 1412 | |
| 1413 | --tmp-dir dir |
| 1414 | Specify a directory dir for temporary files. This directory will be used by openvpn processes and script to communicate |
| 1415 | temporary data with openvpn main process. Note that the directory must be writable by the OpenVPN process after it has |
| 1416 | dropped it's root privileges. |
| 1417 | |
| 1418 | This directory will be used by in the following cases: |
| 1419 | |
| 1420 | * --client-connect scripts to dynamically generate client-specific configuration files. |
| 1421 | |
| 1422 | * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin hook to return success/failure via auth_control_file when using deferred |
| 1423 | auth method |
| 1424 | |
| 1425 | * OPENVPN_PLUGIN_ENABLE_PF plugin hook to pass filtering rules via pf_file |
| 1426 | |
| 1427 | --hash-size r v |
| 1428 | Set the size of the real address hash table to r and the virtual address table to v. By default, both tables are sized |
| 1429 | at 256 buckets. |
| 1430 | |
| 1431 | --bcast-buffers n |
| 1432 | Allocate n buffers for broadcast datagrams (default=256). |
| 1433 | |
| 1434 | --tcp-queue-limit n |
| 1435 | Maximum number of output packets queued before TCP (default=64). |
| 1436 | |
| 1437 | When OpenVPN is tunneling data from a TUN/TAP device to a remote client over a TCP connection, it is possible that the |
| 1438 | TUN/TAP device might produce data at a faster rate than the TCP connection can support. When the number of output pack‐ |
| 1439 | ets queued before sending to the TCP socket reaches this limit for a given client connection, OpenVPN will start to drop |
| 1440 | outgoing packets directed at this client. |
| 1441 | |
| 1442 | --tcp-nodelay |
| 1443 | This macro sets the TCP_NODELAY socket flag on the server as well as pushes it to connecting clients. The TCP_NODELAY |
| 1444 | flag disables the Nagle algorithm on TCP sockets causing packets to be transmitted immediately with low latency, rather |
| 1445 | than waiting a short period of time in order to aggregate several packets into a larger containing packet. In VPN |
| 1446 | applications over TCP, TCP_NODELAY is generally a good latency optimization. |
| 1447 | |
| 1448 | The macro expands as follows: |
| 1449 | |
| 1450 | if mode server: |
| 1451 | socket-flags TCP_NODELAY |
| 1452 | push "socket-flags TCP_NODELAY" |
| 1453 | |
| 1454 | --max-clients n |
| 1455 | Limit server to a maximum of n concurrent clients. |
| 1456 | |
| 1457 | --max-routes-per-client n |
| 1458 | Allow a maximum of n internal routes per client (default=256). This is designed to help contain DoS attacks where an |
| 1459 | authenticated client floods the server with packets appearing to come from many unique MAC addresses, forcing the server |
| 1460 | to deplete virtual memory as its internal routing table expands. This directive can be used in a --client-config-dir |
| 1461 | file or auto-generated by a --client-connect script to override the global value for a particular client. |
| 1462 | |
| 1463 | Note that this directive affects OpenVPN's internal routing table, not the kernel routing table. |
| 1464 | |
| 1465 | --stale-routes-check n [t] |
| 1466 | Remove routes haven't had activity for n seconds (i.e. the ageing time). |
| 1467 | |
| 1468 | This check is ran every t seconds (i.e. check interval). |
| 1469 | |
| 1470 | If t is not present it defaults to n |
| 1471 | |
| 1472 | This option helps to keep the dynamic routing table small. See also --max-routes-per-client |
| 1473 | |
| 1474 | --connect-freq n sec |
| 1475 | Allow a maximum of n new connections per sec seconds from clients. This is designed to contain DoS attacks which flood |
| 1476 | the server with connection requests using certificates which will ultimately fail to authenticate. |
| 1477 | |
| 1478 | This is an imperfect solution however, because in a real DoS scenario, legitimate connections might also be refused. |
| 1479 | |
| 1480 | For the best protection against DoS attacks in server mode, use --proto udp and --tls-auth. |
| 1481 | |
| 1482 | --learn-address cmd |
| 1483 | Run command cmd to validate client virtual addresses or routes. |
| 1484 | |
| 1485 | cmd consists of a path to script (or executable program), optionally followed by arguments. The path and arguments may |
| 1486 | be single- or double-quoted and/or escaped using a backslash, and should be separated by one or more spaces. |
| 1487 | |
| 1488 | Three arguments will be appended to any arguments in cmd as follows: |
| 1489 | |
| 1490 | [1] operation -- "add", "update", or "delete" based on whether or not the address is being added to, modified, or |
| 1491 | deleted from OpenVPN's internal routing table. |
| 1492 | [2] address -- The address being learned or unlearned. This can be an IPv4 address such as "198.162.10.14", an IPv4 |
| 1493 | subnet such as "198.162.10.0/24", or an ethernet MAC address (when --dev tap is being used) such as "00:FF:01:02:03:04". |
| 1494 | [3] common name -- The common name on the certificate associated with the client linked to this address. Only present |
| 1495 | for "add" or "update" operations, not "delete". |
| 1496 | |
| 1497 | On "add" or "update" methods, if the script returns a failure code (non-zero), OpenVPN will reject the address and will |
| 1498 | not modify its internal routing table. |
| 1499 | |
| 1500 | Normally, the cmd script will use the information provided above to set appropriate firewall entries on the VPN TUN/TAP |
| 1501 | interface. Since OpenVPN provides the association between virtual IP or MAC address and the client's authenticated com‐ |
| 1502 | mon name, it allows a user-defined script to configure firewall access policies with regard to the client's high-level |
| 1503 | common name, rather than the low level client virtual addresses. |
| 1504 | |
| 1505 | --auth-user-pass-verify cmd method |
| 1506 | Require the client to provide a username/password (possibly in addition to a client certificate) for authentication. |
| 1507 | |
| 1508 | OpenVPN will run command cmd to validate the username/password provided by the client. |
| 1509 | |
| 1510 | cmd consists of a path to script (or executable program), optionally followed by arguments. The path and arguments may |
| 1511 | be single- or double-quoted and/or escaped using a backslash, and should be separated by one or more spaces. |
| 1512 | |
| 1513 | If method is set to "via-env", OpenVPN will call script with the environmental variables username and password set to |
| 1514 | the username/password strings provided by the client. Be aware that this method is insecure on some platforms which |
| 1515 | make the environment of a process publicly visible to other unprivileged processes. |
| 1516 | |
| 1517 | If method is set to "via-file", OpenVPN will write the username and password to the first two lines of a temporary file. |
| 1518 | The filename will be passed as an argument to script, and the file will be automatically deleted by OpenVPN after the |
| 1519 | script returns. The location of the temporary file is controlled by the --tmp-dir option, and will default to the cur‐ |
| 1520 | rent directory if unspecified. For security, consider setting --tmp-dir to a volatile storage medium such as /dev/shm |
| 1521 | (if available) to prevent the username/password file from touching the hard drive. |
| 1522 | |
| 1523 | The script should examine the username and password, returning a success exit code (0) if the client's authentication |
| 1524 | request is to be accepted, or a failure code (1) to reject the client. |
| 1525 | |
| 1526 | This directive is designed to enable a plugin-style interface for extending OpenVPN's authentication capabilities. |
| 1527 | |
| 1528 | To protect against a client passing a maliciously formed username or password string, the username string must consist |
| 1529 | only of these characters: alphanumeric, underbar ('_'), dash ('-'), dot ('.'), or at ('@'). The password string can |
| 1530 | consist of any printable characters except for CR or LF. Any illegal characters in either the username or password |
| 1531 | string will be converted to underbar ('_'). |
| 1532 | |
| 1533 | Care must be taken by any user-defined scripts to avoid creating a security vulnerability in the way that these strings |
| 1534 | are handled. Never use these strings in such a way that they might be escaped or evaluated by a shell interpreter. |
| 1535 | |
| 1536 | For a sample script that performs PAM authentication, see sample-scripts/auth-pam.pl in the OpenVPN source distribution. |
| 1537 | |
| 1538 | --opt-verify |
| 1539 | Clients that connect with options that are incompatible with those of the server will be disconnected. |
| 1540 | |
| 1541 | Options that will be compared for compatibility include dev-type, link-mtu, tun-mtu, proto, tun-ipv6, ifconfig, comp- |
| 1542 | lzo, fragment, keydir, cipher, auth, keysize, secret, no-replay, no-iv, tls-auth, key-method, tls-server, and tls- |
| 1543 | client. |
| 1544 | |
| 1545 | This option requires that --disable-occ NOT be used. |
| 1546 | |
| 1547 | --auth-user-pass-optional |
| 1548 | Allow connections by clients that do not specify a username/password. Normally, when --auth-user-pass-verify or --man‐ |
| 1549 | agement-client-auth is specified (or an authentication plugin module), the OpenVPN server daemon will require connecting |
| 1550 | clients to specify a username and password. This option makes the submission of a username/password by clients |
| 1551 | optional, passing the responsibility to the user-defined authentication module/script to accept or deny the client based |
| 1552 | on other factors (such as the setting of X509 certificate fields). When this option is used, and a connecting client |
| 1553 | does not submit a username/password, the user-defined authentication module/script will see the username and password as |
| 1554 | being set to empty strings (""). The authentication module/script MUST have logic to detect this condition and respond |
| 1555 | accordingly. |
| 1556 | |
| 1557 | --client-cert-not-required |
| 1558 | Don't require client certificate, client will authenticate using username/password only. Be aware that using this |
| 1559 | directive is less secure than requiring certificates from all clients. |
| 1560 | |
| 1561 | If you use this directive, the entire responsibility of authentication will rest on your --auth-user-pass-verify script, |
| 1562 | so keep in mind that bugs in your script could potentially compromise the security of your VPN. |
| 1563 | |
| 1564 | If you don't use this directive, but you also specify an --auth-user-pass-verify script, then OpenVPN will perform dou‐ |
| 1565 | ble authentication. The client certificate verification AND the --auth-user-pass-verify script will need to succeed in |
| 1566 | order for a client to be authenticated and accepted onto the VPN. |
| 1567 | |
| 1568 | --username-as-common-name |
| 1569 | For --auth-user-pass-verify authentication, use the authenticated username as the common name, rather than the common |
| 1570 | name from the client cert. |
| 1571 | |
| 1572 | --port-share host port [dir] |
| 1573 | When run in TCP server mode, share the OpenVPN port with another application, such as an HTTPS server. If OpenVPN |
| 1574 | senses a connection to its port which is using a non-OpenVPN protocol, it will proxy the connection to the server at |
| 1575 | host:port. Currently only designed to work with HTTP/HTTPS, though it would be theoretically possible to extend to |
| 1576 | other protocols such as ssh. |
| 1577 | |
| 1578 | dir specifies an optional directory where a temporary file with name N containing content C will be dynamically gener‐ |
| 1579 | ated for each proxy connection, where N is the source IP:port of the client connection and C is the source IP:port of |
| 1580 | the connection to the proxy receiver. This directory can be used as a dictionary by the proxy receiver to determine the |
| 1581 | origin of the connection. Each generated file will be automatically deleted when the proxied connection is torn down. |
| 1582 | |
| 1583 | Not implemented on Windows. |
| 1584 | |
| 1585 | Client Mode |
| 1586 | Use client mode when connecting to an OpenVPN server which has --server, --server-bridge, or --mode server in it's configura‐ |
| 1587 | tion. |
| 1588 | |
| 1589 | --client |
| 1590 | A helper directive designed to simplify the configuration of OpenVPN's client mode. This directive is equivalent to: |
| 1591 | |
| 1592 | pull |
| 1593 | tls-client |
| 1594 | |
| 1595 | --pull This option must be used on a client which is connecting to a multi-client server. It indicates to OpenVPN that it |
| 1596 | should accept options pushed by the server, provided they are part of the legal set of pushable options (note that the |
| 1597 | --pull option is implied by --client ). |
| 1598 | |
| 1599 | In particular, --pull allows the server to push routes to the client, so you should not use --pull or --client in situa‐ |
| 1600 | tions where you don't trust the server to have control over the client's routing table. |
| 1601 | |
| 1602 | --auth-user-pass [up] |
| 1603 | Authenticate with server using username/password. up is a file containing username/password on 2 lines (Note: OpenVPN |
| 1604 | will only read passwords from a file if it has been built with the --enable-password-save configure option, or on Win‐ |
| 1605 | dows by defining ENABLE_PASSWORD_SAVE in win/settings.in). |
| 1606 | |
| 1607 | If up is omitted, username/password will be prompted from the console. |
| 1608 | |
| 1609 | The server configuration must specify an --auth-user-pass-verify script to verify the username/password provided by the |
| 1610 | client. |
| 1611 | |
| 1612 | --auth-retry type |
| 1613 | Controls how OpenVPN responds to username/password verification errors such as the client-side response to an |
| 1614 | AUTH_FAILED message from the server or verification failure of the private key password. |
| 1615 | |
| 1616 | Normally used to prevent auth errors from being fatal on the client side, and to permit username/password requeries in |
| 1617 | case of error. |
| 1618 | |
| 1619 | An AUTH_FAILED message is generated by the server if the client fails --auth-user-pass authentication, or if the server- |
| 1620 | side --client-connect script returns an error status when the client tries to connect. |
| 1621 | |
| 1622 | type can be one of: |
| 1623 | |
| 1624 | none -- Client will exit with a fatal error (this is the default). |
| 1625 | nointeract -- Client will retry the connection without requerying for an --auth-user-pass username/password. Use this |
| 1626 | option for unattended clients. |
| 1627 | interact -- Client will requery for an --auth-user-pass username/password and/or private key password before attempting |
| 1628 | a reconnection. |
| 1629 | |
| 1630 | Note that while this option cannot be pushed, it can be controlled from the management interface. |
| 1631 | |
| 1632 | --static-challenge t e |
| 1633 | Enable static challenge/response protocol using challenge text t, with echo flag given by e (0|1). |
| 1634 | |
| 1635 | The echo flag indicates whether or not the user's response to the challenge should be echoed. |
| 1636 | |
| 1637 | See management-notes.txt in the OpenVPN distribution for a description of the OpenVPN challenge/response protocol. |
| 1638 | |
| 1639 | --server-poll-timeout n |
| 1640 | when polling possible remote servers to connect to in a round-robin fashion, spend no more than n seconds waiting for a |
| 1641 | response before trying the next server. |
| 1642 | |
| 1643 | --explicit-exit-notify [n] |
| 1644 | In UDP client mode or point-to-point mode, send server/peer an exit notification if tunnel is restarted or OpenVPN |
| 1645 | process is exited. In client mode, on exit/restart, this option will tell the server to immediately close its client |
| 1646 | instance object rather than waiting for a timeout. The n parameter (default=1) controls the maximum number of attempts |
| 1647 | that the client will try to resend the exit notification message. OpenVPN will not send any exit notifications unless |
| 1648 | this option is enabled. |
| 1649 | |
| 1650 | Data Channel Encryption Options: |
| 1651 | These options are meaningful for both Static & TLS-negotiated key modes (must be compatible between peers). |
| 1652 | |
| 1653 | --secret file [direction] |
| 1654 | Enable Static Key encryption mode (non-TLS). Use pre-shared secret file which was generated with --genkey. |
| 1655 | |
| 1656 | The optional direction parameter enables the use of 4 distinct keys (HMAC-send, cipher-encrypt, HMAC-receive, cipher- |
| 1657 | decrypt), so that each data flow direction has a different set of HMAC and cipher keys. This has a number of desirable |
| 1658 | security properties including eliminating certain kinds of DoS and message replay attacks. |
| 1659 | |
| 1660 | When the direction parameter is omitted, 2 keys are used bidirectionally, one for HMAC and the other for encryp‐ |
| 1661 | tion/decryption. |
| 1662 | |
| 1663 | The direction parameter should always be complementary on either side of the connection, i.e. one side should use "0" |
| 1664 | and the other should use "1", or both sides should omit it altogether. |
| 1665 | |
| 1666 | The direction parameter requires that file contains a 2048 bit key. While pre-1.5 versions of OpenVPN generate 1024 bit |
| 1667 | key files, any version of OpenVPN which supports the direction parameter, will also support 2048 bit key file generation |
| 1668 | using the --genkey option. |
| 1669 | |
| 1670 | Static key encryption mode has certain advantages, the primary being ease of configuration. |
| 1671 | |
| 1672 | There are no certificates or certificate authorities or complicated negotiation handshakes and protocols. The only |
| 1673 | requirement is that you have a pre-existing secure channel with your peer (such as ssh ) to initially copy the key. |
| 1674 | This requirement, along with the fact that your key never changes unless you manually generate a new one, makes it some‐ |
| 1675 | what less secure than TLS mode (see below). If an attacker manages to steal your key, everything that was ever |
| 1676 | encrypted with it is compromised. Contrast that to the perfect forward secrecy features of TLS mode (using Diffie Hell‐ |
| 1677 | man key exchange), where even if an attacker was able to steal your private key, he would gain no information to help |
| 1678 | him decrypt past sessions. |
| 1679 | |
| 1680 | Another advantageous aspect of Static Key encryption mode is that it is a handshake-free protocol without any distin‐ |
| 1681 | guishing signature or feature (such as a header or protocol handshake sequence) that would mark the ciphertext packets |
| 1682 | as being generated by OpenVPN. Anyone eavesdropping on the wire would see nothing but random-looking data. |
| 1683 | |
| 1684 | --auth alg |
| 1685 | Authenticate packets with HMAC using message digest algorithm alg. (The default is SHA1 ). HMAC is a commonly used |
| 1686 | message authentication algorithm (MAC) that uses a data string, a secure hash algorithm, and a key, to produce a digital |
| 1687 | signature. |
| 1688 | |
| 1689 | OpenVPN's usage of HMAC is to first encrypt a packet, then HMAC the resulting ciphertext. |
| 1690 | |
| 1691 | In static-key encryption mode, the HMAC key is included in the key file generated by --genkey. In TLS mode, the HMAC |
| 1692 | key is dynamically generated and shared between peers via the TLS control channel. If OpenVPN receives a packet with a |
| 1693 | bad HMAC it will drop the packet. HMAC usually adds 16 or 20 bytes per packet. Set alg=none to disable authentication. |
| 1694 | |
| 1695 | For more information on HMAC see http://www.cs.ucsd.edu/users/mihir/papers/hmac.html |
| 1696 | |
| 1697 | --cipher alg |
| 1698 | Encrypt packets with cipher algorithm alg. The default is BF-CBC, an abbreviation for Blowfish in Cipher Block Chaining |
| 1699 | mode. Blowfish has the advantages of being fast, very secure, and allowing key sizes of up to 448 bits. Blowfish is |
| 1700 | designed to be used in situations where keys are changed infrequently. |
| 1701 | |
| 1702 | For more information on blowfish, see http://www.counterpane.com/blowfish.html |
| 1703 | |
| 1704 | To see other ciphers that are available with OpenVPN, use the --show-ciphers option. |
| 1705 | |
| 1706 | OpenVPN supports the CBC, CFB, and OFB cipher modes, however CBC is recommended and CFB and OFB should be considered |
| 1707 | advanced modes. |
| 1708 | |
| 1709 | Set alg=none to disable encryption. |
| 1710 | |
| 1711 | --keysize n |
| 1712 | Size of cipher key in bits (optional). If unspecified, defaults to cipher-specific default. The --show-ciphers option |
| 1713 | (see below) shows all available OpenSSL ciphers, their default key sizes, and whether the key size can be changed. Use |
| 1714 | care in changing a cipher's default key size. Many ciphers have not been extensively cryptanalyzed with non-standard |
| 1715 | key lengths, and a larger key may offer no real guarantee of greater security, or may even reduce security. |
| 1716 | |
| 1717 | --prng alg [nsl] |
| 1718 | (Advanced) For PRNG (Pseudo-random number generator), use digest algorithm alg (default=sha1), and set nsl (default=16) |
| 1719 | to the size in bytes of the nonce secret length (between 16 and 64). |
| 1720 | |
| 1721 | Set alg=none to disable the PRNG and use the OpenSSL RAND_bytes function instead for all of OpenVPN's pseudo-random num‐ |
| 1722 | ber needs. |
| 1723 | |
| 1724 | --engine [engine-name] |
| 1725 | Enable OpenSSL hardware-based crypto engine functionality. |
| 1726 | |
| 1727 | If engine-name is specified, use a specific crypto engine. Use the --show-engines standalone option to list the crypto |
| 1728 | engines which are supported by OpenSSL. |
| 1729 | |
| 1730 | --no-replay |
| 1731 | (Advanced) Disable OpenVPN's protection against replay attacks. Don't use this option unless you are prepared to make a |
| 1732 | tradeoff of greater efficiency in exchange for less security. |
| 1733 | |
| 1734 | OpenVPN provides datagram replay protection by default. |
| 1735 | |
| 1736 | Replay protection is accomplished by tagging each outgoing datagram with an identifier that is guaranteed to be unique |
| 1737 | for the key being used. The peer that receives the datagram will check for the uniqueness of the identifier. If the |
| 1738 | identifier was already received in a previous datagram, OpenVPN will drop the packet. Replay protection is important to |
| 1739 | defeat attacks such as a SYN flood attack, where the attacker listens in the wire, intercepts a TCP SYN packet (identi‐ |
| 1740 | fying it by the context in which it occurs in relation to other packets), then floods the receiving peer with copies of |
| 1741 | this packet. |
| 1742 | |
| 1743 | OpenVPN's replay protection is implemented in slightly different ways, depending on the key management mode you have |
| 1744 | selected. |
| 1745 | |
| 1746 | In Static Key mode or when using an CFB or OFB mode cipher, OpenVPN uses a 64 bit unique identifier that combines a time |
| 1747 | stamp with an incrementing sequence number. |
| 1748 | |
| 1749 | When using TLS mode for key exchange and a CBC cipher mode, OpenVPN uses only a 32 bit sequence number without a time |
| 1750 | stamp, since OpenVPN can guarantee the uniqueness of this value for each key. As in IPSec, if the sequence number is |
| 1751 | close to wrapping back to zero, OpenVPN will trigger a new key exchange. |
| 1752 | |
| 1753 | To check for replays, OpenVPN uses the sliding window algorithm used by IPSec. |
| 1754 | |
| 1755 | --replay-window n [t] |
| 1756 | Use a replay protection sliding-window of size n and a time window of t seconds. |
| 1757 | |
| 1758 | By default n is 64 (the IPSec default) and t is 15 seconds. |
| 1759 | |
| 1760 | This option is only relevant in UDP mode, i.e. when either --proto udp is specifed, or no --proto option is specified. |
| 1761 | |
| 1762 | When OpenVPN tunnels IP packets over UDP, there is the possibility that packets might be dropped or delivered out of |
| 1763 | order. Because OpenVPN, like IPSec, is emulating the physical network layer, it will accept an out-of-order packet |
| 1764 | sequence, and will deliver such packets in the same order they were received to the TCP/IP protocol stack, provided they |
| 1765 | satisfy several constraints. |
| 1766 | |
| 1767 | (a) The packet cannot be a replay (unless --no-replay is specified, which disables replay protection altogether). |
| 1768 | |
| 1769 | (b) If a packet arrives out of order, it will only be accepted if the difference between its sequence number and the |
| 1770 | highest sequence number received so far is less than n. |
| 1771 | |
| 1772 | (c) If a packet arrives out of order, it will only be accepted if it arrives no later than t seconds after any packet |
| 1773 | containing a higher sequence number. |
| 1774 | |
| 1775 | If you are using a network link with a large pipeline (meaning that the product of bandwidth and latency is high), you |
| 1776 | may want to use a larger value for n. Satellite links in particular often require this. |
| 1777 | |
| 1778 | If you run OpenVPN at --verb 4, you will see the message "Replay-window backtrack occurred [x]" every time the maximum |
| 1779 | sequence number backtrack seen thus far increases. This can be used to calibrate n. |
| 1780 | |
| 1781 | There is some controversy on the appropriate method of handling packet reordering at the security layer. |
| 1782 | |
| 1783 | Namely, to what extent should the security layer protect the encapsulated protocol from attacks which masquerade as the |
| 1784 | kinds of normal packet loss and reordering that occur over IP networks? |
| 1785 | |
| 1786 | The IPSec and OpenVPN approach is to allow packet reordering within a certain fixed sequence number window. |
| 1787 | |
| 1788 | OpenVPN adds to the IPSec model by limiting the window size in time as well as sequence space. |
| 1789 | |
| 1790 | OpenVPN also adds TCP transport as an option (not offered by IPSec) in which case OpenVPN can adopt a very strict atti‐ |
| 1791 | tude towards message deletion and reordering: Don't allow it. Since TCP guarantees reliability, any packet loss or |
| 1792 | reordering event can be assumed to be an attack. |
| 1793 | |
| 1794 | In this sense, it could be argued that TCP tunnel transport is preferred when tunneling non-IP or UDP application proto‐ |
| 1795 | cols which might be vulnerable to a message deletion or reordering attack which falls within the normal operational |
| 1796 | parameters of IP networks. |
| 1797 | |
| 1798 | So I would make the statement that one should never tunnel a non-IP protocol or UDP application protocol over UDP, if |
| 1799 | the protocol might be vulnerable to a message deletion or reordering attack that falls within the normal operating |
| 1800 | parameters of what is to be expected from the physical IP layer. The problem is easily fixed by simply using TCP as the |
| 1801 | VPN transport layer. |
| 1802 | |
| 1803 | --mute-replay-warnings |
| 1804 | Silence the output of replay warnings, which are a common false alarm on WiFi networks. This option preserves the secu‐ |
| 1805 | rity of the replay protection code without the verbosity associated with warnings about duplicate packets. |
| 1806 | |
| 1807 | --replay-persist file |
| 1808 | Persist replay-protection state across sessions using file to save and reload the state. |
| 1809 | |
| 1810 | This option will strengthen protection against replay attacks, especially when you are using OpenVPN in a dynamic con‐ |
| 1811 | text (such as with --inetd) when OpenVPN sessions are frequently started and stopped. |
| 1812 | |
| 1813 | This option will keep a disk copy of the current replay protection state (i.e. the most recent packet timestamp and |
| 1814 | sequence number received from the remote peer), so that if an OpenVPN session is stopped and restarted, it will reject |
| 1815 | any replays of packets which were already received by the prior session. |
| 1816 | |
| 1817 | This option only makes sense when replay protection is enabled (the default) and you are using either --secret (shared- |
| 1818 | secret key mode) or TLS mode with --tls-auth. |
| 1819 | |
| 1820 | --no-iv |
| 1821 | (Advanced) Disable OpenVPN's use of IV (cipher initialization vector). Don't use this option unless you are prepared to |
| 1822 | make a tradeoff of greater efficiency in exchange for less security. |
| 1823 | |
| 1824 | OpenVPN uses an IV by default, and requires it for CFB and OFB cipher modes (which are totally insecure without it). |
| 1825 | Using an IV is important for security when multiple messages are being encrypted/decrypted with the same key. |
| 1826 | |
| 1827 | IV is implemented differently depending on the cipher mode used. |
| 1828 | |
| 1829 | In CBC mode, OpenVPN uses a pseudo-random IV for each packet. |
| 1830 | |
| 1831 | In CFB/OFB mode, OpenVPN uses a unique sequence number and time stamp as the IV. In fact, in CFB/OFB mode, OpenVPN uses |
| 1832 | a datagram space-saving optimization that uses the unique identifier for datagram replay protection as the IV. |
| 1833 | |
| 1834 | --use-prediction-resistance |
| 1835 | Enable prediction resistance on PolarSSL's RNG. |
| 1836 | |
| 1837 | Enabling prediction resistance causes the RNG to reseed in each call for random. Reseeding this often can quickly |
| 1838 | deplete the kernel entropy pool. |
| 1839 | |
| 1840 | If you need this option, please consider running a daemon that adds entropy to the kernel pool. |
| 1841 | |
| 1842 | Note that this option only works with PolarSSL versions greater than 1.1. |
| 1843 | |
| 1844 | --test-crypto |
| 1845 | Do a self-test of OpenVPN's crypto options by encrypting and decrypting test packets using the data channel encryption |
| 1846 | options specified above. This option does not require a peer to function, and therefore can be specified without --dev |
| 1847 | or --remote. |
| 1848 | |
| 1849 | The typical usage of --test-crypto would be something like this: |
| 1850 | |
| 1851 | openvpn --test-crypto --secret key |
| 1852 | |
| 1853 | or |
| 1854 | |
| 1855 | openvpn --test-crypto --secret key --verb 9 |
| 1856 | |
| 1857 | This option is very useful to test OpenVPN after it has been ported to a new platform, or to isolate problems in the |
| 1858 | compiler, OpenSSL crypto library, or OpenVPN's crypto code. Since it is a self-test mode, problems with encryption and |
| 1859 | authentication can be debugged independently of network and tunnel issues. |
| 1860 | |
| 1861 | TLS Mode Options: |
| 1862 | TLS mode is the most powerful crypto mode of OpenVPN in both security and flexibility. TLS mode works by establishing control |
| 1863 | and data channels which are multiplexed over a single TCP/UDP port. OpenVPN initiates a TLS session over the control channel |
| 1864 | and uses it to exchange cipher and HMAC keys to protect the data channel. TLS mode uses a robust reliability layer over the |
| 1865 | UDP connection for all control channel communication, while the data channel, over which encrypted tunnel data passes, is for‐ |
| 1866 | warded without any mediation. The result is the best of both worlds: a fast data channel that forwards over UDP with only the |
| 1867 | overhead of encrypt, decrypt, and HMAC functions, and a control channel that provides all of the security features of TLS, |
| 1868 | including certificate-based authentication and Diffie Hellman forward secrecy. |
| 1869 | |
| 1870 | To use TLS mode, each peer that runs OpenVPN should have its own local certificate/key pair ( --cert and --key ), signed by the |
| 1871 | root certificate which is specified in --ca. |
| 1872 | |
| 1873 | When two OpenVPN peers connect, each presents its local certificate to the other. Each peer will then check that its partner |
| 1874 | peer presented a certificate which was signed by the master root certificate as specified in --ca. |
| 1875 | |
| 1876 | If that check on both peers succeeds, then the TLS negotiation will succeed, both OpenVPN peers will exchange temporary session |
| 1877 | keys, and the tunnel will begin passing data. |
| 1878 | |
| 1879 | The OpenVPN distribution contains a set of scripts for managing RSA certificates & keys, located in the easy-rsa subdirectory. |
| 1880 | |
| 1881 | The easy-rsa package is also rendered in web form here: http://openvpn.net/easyrsa.html |
| 1882 | |
| 1883 | --tls-server |
| 1884 | Enable TLS and assume server role during TLS handshake. Note that OpenVPN is designed as a peer-to-peer application. |
| 1885 | The designation of client or server is only for the purpose of negotiating the TLS control channel. |
| 1886 | |
| 1887 | --tls-client |
| 1888 | Enable TLS and assume client role during TLS handshake. |
| 1889 | |
| 1890 | --ca file |
| 1891 | Certificate authority (CA) file in .pem format, also referred to as the root certificate. This file can have multiple |
| 1892 | certificates in .pem format, concatenated together. You can construct your own certificate authority certificate and |
| 1893 | private key by using a command such as: |
| 1894 | |
| 1895 | openssl req -nodes -new -x509 -keyout ca.key -out ca.crt |
| 1896 | |
| 1897 | Then edit your openssl.cnf file and edit the certificate variable to point to your new root certificate ca.crt. |
| 1898 | |
| 1899 | For testing purposes only, the OpenVPN distribution includes a sample CA certificate (ca.crt). Of course you should |
| 1900 | never use the test certificates and test keys distributed with OpenVPN in a production environment, since by virtue of |
| 1901 | the fact that they are distributed with OpenVPN, they are totally insecure. |
| 1902 | |
| 1903 | --capath dir |
| 1904 | Directory containing trusted certificates (CAs and CRLs). Available with OpenSSL version >= 0.9.7 dev. Not available |
| 1905 | with PolarSSL. |
| 1906 | |
| 1907 | --dh file |
| 1908 | File containing Diffie Hellman parameters in .pem format (required for --tls-server only). Use |
| 1909 | |
| 1910 | openssl dhparam -out dh1024.pem 1024 |
| 1911 | |
| 1912 | to generate your own, or use the existing dh1024.pem file included with the OpenVPN distribution. Diffie Hellman param‐ |
| 1913 | eters may be considered public. |
| 1914 | |
| 1915 | --cert file |
| 1916 | Local peer's signed certificate in .pem format -- must be signed by a certificate authority whose certificate is in --ca |
| 1917 | file. Each peer in an OpenVPN link running in TLS mode should have its own certificate and private key file. In addi‐ |
| 1918 | tion, each certificate should have been signed by the key of a certificate authority whose public key resides in the |
| 1919 | --ca certificate authority file. You can easily make your own certificate authority (see above) or pay money to use a |
| 1920 | commercial service such as thawte.com (in which case you will be helping to finance the world's second space tourist :). |
| 1921 | To generate a certificate, you can use a command such as: |
| 1922 | |
| 1923 | openssl req -nodes -new -keyout mycert.key -out mycert.csr |
| 1924 | |
| 1925 | If your certificate authority private key lives on another machine, copy the certificate signing request (mycert.csr) to |
| 1926 | this other machine (this can be done over an insecure channel such as email). Now sign the certificate with a command |
| 1927 | such as: |
| 1928 | |
| 1929 | openssl ca -out mycert.crt -in mycert.csr |
| 1930 | |
| 1931 | Now copy the certificate (mycert.crt) back to the peer which initially generated the .csr file (this can be over a pub‐ |
| 1932 | lic medium). Note that the openssl ca command reads the location of the certificate authority key from its configura‐ |
| 1933 | tion file such as /usr/share/ssl/openssl.cnf -- note also that for certificate authority functions, you must set up the |
| 1934 | files index.txt (may be empty) and serial (initialize to 01 ). |
| 1935 | |
| 1936 | --extra-certs file |
| 1937 | Specify a file containing one or more PEM certs (concatenated together) that complete the local certificate chain. |
| 1938 | |
| 1939 | This option is useful for "split" CAs, where the CA for server certs is different than the CA for client certs. Putting |
| 1940 | certs in this file allows them to be used to complete the local certificate chain without trusting them to verify the |
| 1941 | peer-submitted certificate, as would be the case if the certs were placed in the ca file. |
| 1942 | |
| 1943 | --key file |
| 1944 | Local peer's private key in .pem format. Use the private key which was generated when you built your peer's certificate |
| 1945 | (see -cert file above). |
| 1946 | |
| 1947 | --pkcs12 file |
| 1948 | Specify a PKCS #12 file containing local private key, local certificate, and root CA certificate. This option can be |
| 1949 | used instead of --ca, --cert, and --key. Not available with PolarSSL. |
| 1950 | |
| 1951 | --verify-hash hash |
| 1952 | Specify SHA1 fingerprint for level-1 cert. The level-1 cert is the CA (or intermediate cert) that signs the leaf cer‐ |
| 1953 | tificate, and is one removed from the leaf certificate in the direction of the root. When accepting a connection from a |
| 1954 | peer, the level-1 cert fingerprint must match hash or certificate verification will fail. Hash is specified as |
| 1955 | XX:XX:... For example: AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16 |
| 1956 | |
| 1957 | --pkcs11-cert-private [0|1]... |
| 1958 | Set if access to certificate object should be performed after login. Every provider has its own setting. |
| 1959 | |
| 1960 | --pkcs11-id name |
| 1961 | Specify the serialized certificate id to be used. The id can be gotten by the standalone --show-pkcs11-ids option. |
| 1962 | |
| 1963 | --pkcs11-id-management |
| 1964 | Acquire PKCS#11 id from management interface. In this case a NEED-STR 'pkcs11-id-request' real-time message will be |
| 1965 | triggered, application may use pkcs11-id-count command to retrieve available number of certificates, and pkcs11-id-get |
| 1966 | command to retrieve certificate id and certificate body. |
| 1967 | |
| 1968 | --pkcs11-pin-cache seconds |
| 1969 | Specify how many seconds the PIN can be cached, the default is until the token is removed. |
| 1970 | |
| 1971 | --pkcs11-protected-authentication [0|1]... |
| 1972 | Use PKCS#11 protected authentication path, useful for biometric and external keypad devices. Every provider has its own |
| 1973 | setting. |
| 1974 | |
| 1975 | --pkcs11-providers provider... |
| 1976 | Specify a RSA Security Inc. PKCS #11 Cryptographic Token Interface (Cryptoki) providers to load. This option can be |
| 1977 | used instead of --cert, --key, and --pkcs12. |
| 1978 | |
| 1979 | --pkcs11-private-mode mode... |
| 1980 | Specify which method to use in order to perform private key operations. A different mode can be specified for each |
| 1981 | provider. Mode is encoded as hex number, and can be a mask one of the following: |
| 1982 | |
| 1983 | 0 (default) -- Try to determind automatically. |
| 1984 | 1 -- Use sign. |
| 1985 | 2 -- Use sign recover. |
| 1986 | 4 -- Use decrypt. |
| 1987 | 8 -- Use unwrap. |
| 1988 | |
| 1989 | --cryptoapicert select-string |
| 1990 | Load the certificate and private key from the Windows Certificate System Store (Windows/OpenSSL Only). |
| 1991 | |
| 1992 | Use this option instead of --cert and --key. |
| 1993 | |
| 1994 | This makes it possible to use any smart card, supported by Windows, but also any kind of certificate, residing in the |
| 1995 | Cert Store, where you have access to the private key. This option has been tested with a couple of different smart |
| 1996 | cards (GemSAFE, Cryptoflex, and Swedish Post Office eID) on the client side, and also an imported PKCS12 software cer‐ |
| 1997 | tificate on the server side. |
| 1998 | |
| 1999 | To select a certificate, based on a substring search in the certificate's subject: |
| 2000 | |
| 2001 | cryptoapicert "SUBJ:Peter Runestig" |
| 2002 | |
| 2003 | To select a certificate, based on certificate's thumbprint: |
| 2004 | |
| 2005 | cryptoapicert "THUMB:f6 49 24 41 01 b4 ..." |
| 2006 | |
| 2007 | The thumbprint hex string can easily be copy-and-pasted from the Windows Certificate Store GUI. |
| 2008 | |
| 2009 | |
| 2010 | --key-method m |
| 2011 | Use data channel key negotiation method m. The key method must match on both sides of the connection. |
| 2012 | |
| 2013 | After OpenVPN negotiates a TLS session, a new set of keys for protecting the tunnel data channel is generated and |
| 2014 | exchanged over the TLS session. |
| 2015 | |
| 2016 | In method 1 (the default for OpenVPN 1.x), both sides generate random encrypt and HMAC-send keys which are forwarded to |
| 2017 | the other host over the TLS channel. |
| 2018 | |
| 2019 | In method 2, (the default for OpenVPN 2.0) the client generates a random key. Both client and server also generate some |
| 2020 | random seed material. All key source material is exchanged over the TLS channel. The actual keys are generated using |
| 2021 | the TLS PRF function, taking source entropy from both client and server. Method 2 is designed to closely parallel the |
| 2022 | key generation process used by TLS 1.0. |
| 2023 | |
| 2024 | Note that in TLS mode, two separate levels of keying occur: |
| 2025 | |
| 2026 | (1) The TLS connection is initially negotiated, with both sides of the connection producing certificates and verifying |
| 2027 | the certificate (or other authentication info provided) of the other side. The --key-method parameter has no effect on |
| 2028 | this process. |
| 2029 | |
| 2030 | (2) After the TLS connection is established, the tunnel session keys are separately negotiated over the existing secure |
| 2031 | TLS channel. Here, --key-method determines the derivation of the tunnel session keys. |
| 2032 | |
| 2033 | --tls-cipher l |
| 2034 | A list l of allowable TLS ciphers delimited by a colon (":"). If you require a high level of security, you may want to |
| 2035 | set this parameter manually, to prevent a version rollback attack where a man-in-the-middle attacker tries to force two |
| 2036 | peers to negotiate to the lowest level of security they both support. Use --show-tls to see a list of supported TLS |
| 2037 | ciphers. |
| 2038 | |
| 2039 | --tls-timeout n |
| 2040 | Packet retransmit timeout on TLS control channel if no acknowledgment from remote within n seconds (default=2). When |
| 2041 | OpenVPN sends a control packet to its peer, it will expect to receive an acknowledgement within n seconds or it will |
| 2042 | retransmit the packet, subject to a TCP-like exponential backoff algorithm. This parameter only applies to control |
| 2043 | channel packets. Data channel packets (which carry encrypted tunnel data) are never acknowledged, sequenced, or |
| 2044 | retransmitted by OpenVPN because the higher level network protocols running on top of the tunnel such as TCP expect this |
| 2045 | role to be left to them. |
| 2046 | |
| 2047 | --reneg-bytes n |
| 2048 | Renegotiate data channel key after n bytes sent or received (disabled by default). OpenVPN allows the lifetime of a key |
| 2049 | to be expressed as a number of bytes encrypted/decrypted, a number of packets, or a number of seconds. A key renegotia‐ |
| 2050 | tion will be forced if any of these three criteria are met by either peer. |
| 2051 | |
| 2052 | --reneg-pkts n |
| 2053 | Renegotiate data channel key after n packets sent and received (disabled by default). |
| 2054 | |
| 2055 | --reneg-sec n |
| 2056 | Renegotiate data channel key after n seconds (default=3600). |
| 2057 | |
| 2058 | When using dual-factor authentication, note that this default value may cause the end user to be challenged to reautho‐ |
| 2059 | rize once per hour. |
| 2060 | |
| 2061 | Also, keep in mind that this option can be used on both the client and server, and whichever uses the lower value will |
| 2062 | be the one to trigger the renegotiation. A common mistake is to set --reneg-sec to a higher value on either the client |
| 2063 | or server, while the other side of the connection is still using the default value of 3600 seconds, meaning that the |
| 2064 | renegotiation will still occur once per 3600 seconds. The solution is to increase --reneg-sec on both the client and |
| 2065 | server, or set it to 0 on one side of the connection (to disable), and to your chosen value on the other side. |
| 2066 | |
| 2067 | --hand-window n |
| 2068 | Handshake Window -- the TLS-based key exchange must finalize within n seconds of handshake initiation by any peer |
| 2069 | (default = 60 seconds). If the handshake fails we will attempt to reset our connection with our peer and try again. |
| 2070 | Even in the event of handshake failure we will still use our expiring key for up to --tran-window seconds to maintain |
| 2071 | continuity of transmission of tunnel data. |
| 2072 | |
| 2073 | --tran-window n |
| 2074 | Transition window -- our old key can live this many seconds after a new a key renegotiation begins (default = 3600 sec‐ |
| 2075 | onds). This feature allows for a graceful transition from old to new key, and removes the key renegotiation sequence |
| 2076 | from the critical path of tunnel data forwarding. |
| 2077 | |
| 2078 | --single-session |
| 2079 | After initially connecting to a remote peer, disallow any new connections. Using this option means that a remote peer |
| 2080 | cannot connect, disconnect, and then reconnect. |
| 2081 | |
| 2082 | If the daemon is reset by a signal or --ping-restart, it will allow one new connection. |
| 2083 | |
| 2084 | --single-session can be used with --ping-exit or --inactive to create a single dynamic session that will exit when fin‐ |
| 2085 | ished. |
| 2086 | |
| 2087 | --tls-exit |
| 2088 | Exit on TLS negotiation failure. |
| 2089 | |
| 2090 | --tls-auth file [direction] |
| 2091 | Add an additional layer of HMAC authentication on top of the TLS control channel to protect against DoS attacks. |
| 2092 | |
| 2093 | In a nutshell, --tls-auth enables a kind of "HMAC firewall" on OpenVPN's TCP/UDP port, where TLS control channel packets |
| 2094 | bearing an incorrect HMAC signature can be dropped immediately without response. |
| 2095 | |
| 2096 | file (required) is a key file which can be in one of two formats: |
| 2097 | |
| 2098 | (1) An OpenVPN static key file generated by --genkey (required if direction parameter is used). |
| 2099 | |
| 2100 | (2) A freeform passphrase file. In this case the HMAC key will be derived by taking a secure hash of this file, similar |
| 2101 | to the md5sum(1) or sha1sum(1) commands. |
| 2102 | |
| 2103 | OpenVPN will first try format (1), and if the file fails to parse as a static key file, format (2) will be used. |
| 2104 | |
| 2105 | See the --secret option for more information on the optional direction parameter. |
| 2106 | |
| 2107 | --tls-auth is recommended when you are running OpenVPN in a mode where it is listening for packets from any IP address, |
| 2108 | such as when --remote is not specified, or --remote is specified with --float. |
| 2109 | |
| 2110 | The rationale for this feature is as follows. TLS requires a multi-packet exchange before it is able to authenticate a |
| 2111 | peer. During this time before authentication, OpenVPN is allocating resources (memory and CPU) to this potential peer. |
| 2112 | The potential peer is also exposing many parts of OpenVPN and the OpenSSL library to the packets it is sending. Most |
| 2113 | successful network attacks today seek to either exploit bugs in programs (such as buffer overflow attacks) or force a |
| 2114 | program to consume so many resources that it becomes unusable. Of course the first line of defense is always to produce |
| 2115 | clean, well-audited code. OpenVPN has been written with buffer overflow attack prevention as a top priority. But as |
| 2116 | history has shown, many of the most widely used network applications have, from time to time, fallen to buffer overflow |
| 2117 | attacks. |
| 2118 | |
| 2119 | So as a second line of defense, OpenVPN offers this special layer of authentication on top of the TLS control channel so |
| 2120 | that every packet on the control channel is authenticated by an HMAC signature and a unique ID for replay protection. |
| 2121 | This signature will also help protect against DoS (Denial of Service) attacks. An important rule of thumb in reducing |
| 2122 | vulnerability to DoS attacks is to minimize the amount of resources a potential, but as yet unauthenticated, client is |
| 2123 | able to consume. |
| 2124 | |
| 2125 | --tls-auth does this by signing every TLS control channel packet with an HMAC signature, including packets which are |
| 2126 | sent before the TLS level has had a chance to authenticate the peer. The result is that packets without the correct |
| 2127 | signature can be dropped immediately upon reception, before they have a chance to consume additional system resources |
| 2128 | such as by initiating a TLS handshake. --tls-auth can be strengthened by adding the --replay-persist option which will |
| 2129 | keep OpenVPN's replay protection state in a file so that it is not lost across restarts. |
| 2130 | |
| 2131 | It should be emphasized that this feature is optional and that the passphrase/key file used with --tls-auth gives a peer |
| 2132 | nothing more than the power to initiate a TLS handshake. It is not used to encrypt or authenticate any tunnel data. |
| 2133 | |
| 2134 | --askpass [file] |
| 2135 | Get certificate password from console or file before we daemonize. |
| 2136 | |
| 2137 | For the extremely security conscious, it is possible to protect your private key with a password. Of course this means |
| 2138 | that every time the OpenVPN daemon is started you must be there to type the password. The --askpass option allows you |
| 2139 | to start OpenVPN from the command line. It will query you for a password before it daemonizes. To protect a private |
| 2140 | key with a password you should omit the -nodes option when you use the openssl command line tool to manage certificates |
| 2141 | and private keys. |
| 2142 | |
| 2143 | If file is specified, read the password from the first line of file. Keep in mind that storing your password in a file |
| 2144 | to a certain extent invalidates the extra security provided by using an encrypted key (Note: OpenVPN will only read |
| 2145 | passwords from a file if it has been built with the --enable-password-save configure option, or on Windows by defining |
| 2146 | ENABLE_PASSWORD_SAVE in win/settings.in). |
| 2147 | |
| 2148 | --auth-nocache |
| 2149 | Don't cache --askpass or --auth-user-pass username/passwords in virtual memory. |
| 2150 | |
| 2151 | If specified, this directive will cause OpenVPN to immediately forget username/password inputs after they are used. As |
| 2152 | a result, when OpenVPN needs a username/password, it will prompt for input from stdin, which may be multiple times dur‐ |
| 2153 | ing the duration of an OpenVPN session. |
| 2154 | |
| 2155 | This directive does not affect the --http-proxy username/password. It is always cached. |
| 2156 | |
| 2157 | --tls-verify cmd |
| 2158 | Run command cmd to verify the X509 name of a pending TLS connection that has otherwise passed all other tests of certi‐ |
| 2159 | fication (except for revocation via --crl-verify directive; the revocation test occurs after the --tls-verify test). |
| 2160 | |
| 2161 | cmd should return 0 to allow the TLS handshake to proceed, or 1 to fail. |
| 2162 | |
| 2163 | cmd consists of a path to script (or executable program), optionally followed by arguments. The path and arguments may |
| 2164 | be single- or double-quoted and/or escaped using a backslash, and should be separated by one or more spaces. |
| 2165 | |
| 2166 | When cmd is executed two arguments are appended after any arguments specified in cmd , as follows: |
| 2167 | |
| 2168 | cmd certificate_depth subject |
| 2169 | |
| 2170 | These arguments are, respectively, the current certificate depth and the X509 common name (cn) of the peer. |
| 2171 | |
| 2172 | This feature is useful if the peer you want to trust has a certificate which was signed by a certificate authority who |
| 2173 | also signed many other certificates, where you don't necessarily want to trust all of them, but rather be selective |
| 2174 | about which peer certificate you will accept. This feature allows you to write a script which will test the X509 name |
| 2175 | on a certificate and decide whether or not it should be accepted. For a simple perl script which will test the common |
| 2176 | name field on the certificate, see the file verify-cn in the OpenVPN distribution. |
| 2177 | |
| 2178 | See the "Environmental Variables" section below for additional parameters passed as environmental variables. |
| 2179 | |
| 2180 | --tls-export-cert directory |
| 2181 | Store the certificates the clients uses upon connection to this directory. This will be done before --tls-verify is |
| 2182 | called. The certificates will use a temporary name and will be deleted when the tls-verify script returns. The file |
| 2183 | name used for the certificate is available via the peer_cert environment variable. |
| 2184 | |
| 2185 | --x509-username-field fieldname |
| 2186 | Field in x509 certificate subject to be used as username (default=CN). Fieldname will be uppercased before matching. |
| 2187 | When this option is used, the --tls-remote option will match against the chosen fieldname instead of the CN. |
| 2188 | |
| 2189 | --tls-remote name |
| 2190 | Accept connections only from a host with X509 name or common name equal to name. The remote host must also pass all |
| 2191 | other tests of verification. |
| 2192 | |
| 2193 | NOTE: Because tls-remote may test against a common name prefix, only use this option when you are using OpenVPN with a |
| 2194 | custom CA certificate that is under your control. Never use this option when your client certificates are signed by a |
| 2195 | third party, such as a commercial web CA. |
| 2196 | |
| 2197 | Name can also be a common name prefix, for example if you want a client to only accept connections to "Server-1", |
| 2198 | "Server-2", etc., you can simply use --tls-remote Server |
| 2199 | |
| 2200 | Using a common name prefix is a useful alternative to managing a CRL (Certificate Revocation List) on the client, since |
| 2201 | it allows the client to refuse all certificates except for those associated with designated servers. |
| 2202 | |
| 2203 | --tls-remote is a useful replacement for the --tls-verify option to verify the remote host, because --tls-remote works |
| 2204 | in a --chroot environment too. |
| 2205 | |
| 2206 | --x509-track attribute |
| 2207 | Save peer X509 attribute value in environment for use by plugins and management interface. Prepend a '+' to attribute |
| 2208 | to save values from full cert chain. Values will be encoded as X509_<depth>_<attribute>=<value>. Multiple --x509-track |
| 2209 | options can be defined to track multiple attributes. Not available with PolarSSL. |
| 2210 | |
| 2211 | --ns-cert-type client|server |
| 2212 | Require that peer certificate was signed with an explicit nsCertType designation of "client" or "server". |
| 2213 | |
| 2214 | This is a useful security option for clients, to ensure that the host they connect with is a designated server. |
| 2215 | |
| 2216 | See the easy-rsa/build-key-server script for an example of how to generate a certificate with the nsCertType field set |
| 2217 | to "server". |
| 2218 | |
| 2219 | If the server certificate's nsCertType field is set to "server", then the clients can verify this with --ns-cert-type |
| 2220 | server. |
| 2221 | |
| 2222 | This is an important security precaution to protect against a man-in-the-middle attack where an authorized client |
| 2223 | attempts to connect to another client by impersonating the server. The attack is easily prevented by having clients |
| 2224 | verify the server certificate using any one of --ns-cert-type, --tls-remote, or --tls-verify. |
| 2225 | |
| 2226 | --remote-cert-ku v... |
| 2227 | Require that peer certificate was signed with an explicit key usage. |
| 2228 | |
| 2229 | This is a useful security option for clients, to ensure that the host they connect to is a designated server. |
| 2230 | |
| 2231 | The key usage should be encoded in hex, more than one key usage can be specified. |
| 2232 | |
| 2233 | --remote-cert-eku oid |
| 2234 | Require that peer certificate was signed with an explicit extended key usage. |
| 2235 | |
| 2236 | This is a useful security option for clients, to ensure that the host they connect to is a designated server. |
| 2237 | |
| 2238 | The extended key usage should be encoded in oid notation, or OpenSSL symbolic representation. |
| 2239 | |
| 2240 | --remote-cert-tls client|server |
| 2241 | Require that peer certificate was signed with an explicit key usage and extended key usage based on RFC3280 TLS rules. |
| 2242 | |
| 2243 | This is a useful security option for clients, to ensure that the host they connect to is a designated server. |
| 2244 | |
| 2245 | The --remote-cert-tls client option is equivalent to --remote-cert-ku 80 08 88 --remote-cert-eku "TLS Web Client Authen‐ |
| 2246 | tication" |
| 2247 | |
| 2248 | The key usage is digitalSignature and/or keyAgreement. |
| 2249 | |
| 2250 | The --remote-cert-tls server option is equivalent to --remote-cert-ku a0 88 --remote-cert-eku "TLS Web Server Authenti‐ |
| 2251 | cation" |
| 2252 | |
| 2253 | The key usage is digitalSignature and ( keyEncipherment or keyAgreement ). |
| 2254 | |
| 2255 | This is an important security precaution to protect against a man-in-the-middle attack where an authorized client |
| 2256 | attempts to connect to another client by impersonating the server. The attack is easily prevented by having clients |
| 2257 | verify the server certificate using any one of --remote-cert-tls, --tls-remote, or --tls-verify. |
| 2258 | |
| 2259 | --crl-verify crl ['dir'] |
| 2260 | Check peer certificate against the file crl in PEM format. |
| 2261 | |
| 2262 | A CRL (certificate revocation list) is used when a particular key is compromised but when the overall PKI is still |
| 2263 | intact. |
| 2264 | |
| 2265 | Suppose you had a PKI consisting of a CA, root certificate, and a number of client certificates. Suppose a laptop com‐ |
| 2266 | puter containing a client key and certificate was stolen. By adding the stolen certificate to the CRL file, you could |
| 2267 | reject any connection which attempts to use it, while preserving the overall integrity of the PKI. |
| 2268 | |
| 2269 | The only time when it would be necessary to rebuild the entire PKI from scratch would be if the root certificate key |
| 2270 | itself was compromised. |
| 2271 | |
| 2272 | If the optional dir flag is specified, enable a different mode where crl is a directory containing files named as |
| 2273 | revoked serial numbers (the files may be empty, the contents are never read). If a client requests a connection, where |
| 2274 | the client certificate serial number (decimal string) is the name of a file present in the directory, it will be |
| 2275 | rejected. |
| 2276 | |
| 2277 | SSL Library information: |
| 2278 | --show-ciphers |
| 2279 | (Standalone) Show all cipher algorithms to use with the --cipher option. |
| 2280 | |
| 2281 | --show-digests |
| 2282 | (Standalone) Show all message digest algorithms to use with the --auth option. |
| 2283 | |
| 2284 | --show-tls |
| 2285 | (Standalone) Show all TLS ciphers (TLS used only as a control channel). The TLS ciphers will be sorted from highest |
| 2286 | preference (most secure) to lowest. |
| 2287 | |
| 2288 | --show-engines |
| 2289 | (Standalone) Show currently available hardware-based crypto acceleration engines supported by the OpenSSL library. |
| 2290 | |
| 2291 | Generate a random key: |
| 2292 | Used only for non-TLS static key encryption mode. |
| 2293 | |
| 2294 | --genkey |
| 2295 | (Standalone) Generate a random key to be used as a shared secret, for use with the --secret option. This file must be |
| 2296 | shared with the peer over a pre-existing secure channel such as scp(1) |
| 2297 | |
| 2298 | --secret file |
| 2299 | Write key to file. |
| 2300 | |
| 2301 | TUN/TAP persistent tunnel config mode: |
| 2302 | Available with linux 2.4.7+. These options comprise a standalone mode of OpenVPN which can be used to create and delete per‐ |
| 2303 | sistent tunnels. |
| 2304 | |
| 2305 | --mktun |
| 2306 | (Standalone) Create a persistent tunnel on platforms which support them such as Linux. Normally TUN/TAP tunnels exist |
| 2307 | only for the period of time that an application has them open. This option takes advantage of the TUN/TAP driver's |
| 2308 | ability to build persistent tunnels that live through multiple instantiations of OpenVPN and die only when they are |
| 2309 | deleted or the machine is rebooted. |
| 2310 | |
| 2311 | One of the advantages of persistent tunnels is that they eliminate the need for separate --up and --down scripts to run |
| 2312 | the appropriate ifconfig(8) and route(8) commands. These commands can be placed in the the same shell script which |
| 2313 | starts or terminates an OpenVPN session. |
| 2314 | |
| 2315 | Another advantage is that open connections through the TUN/TAP-based tunnel will not be reset if the OpenVPN peer |
| 2316 | restarts. This can be useful to provide uninterrupted connectivity through the tunnel in the event of a DHCP reset of |
| 2317 | the peer's public IP address (see the --ipchange option above). |
| 2318 | |
| 2319 | One disadvantage of persistent tunnels is that it is harder to automatically configure their MTU value (see --link-mtu |
| 2320 | and --tun-mtu above). |
| 2321 | |
| 2322 | On some platforms such as Windows, TAP-Win32 tunnels are persistent by default. |
| 2323 | |
| 2324 | --rmtun |
| 2325 | (Standalone) Remove a persistent tunnel. |
| 2326 | |
| 2327 | --dev tunX | tapX |
| 2328 | TUN/TAP device |
| 2329 | |
| 2330 | --user user |
| 2331 | Optional user to be owner of this tunnel. |
| 2332 | |
| 2333 | --group group |
| 2334 | Optional group to be owner of this tunnel. |
| 2335 | |
| 2336 | Windows-Specific Options: |
| 2337 | --win-sys path |
| 2338 | Set the Windows system directory pathname to use when looking for system executables such as route.exe and netsh.exe. |
| 2339 | By default, if this directive is not specified, OpenVPN will use the SystemRoot environment variable. |
| 2340 | |
| 2341 | This option have changed behaviour in OpenVPN 2.3. Earlier you had to define --win-sys env to use the SystemRoot envi‐ |
| 2342 | ronment variable, otherwise it defaulted to C:\WINDOWS. It is not needed to use the env keyword any more, and it will |
| 2343 | just be ignored. A warning is logged when this is found in the configuration file. |
| 2344 | |
| 2345 | --ip-win32 method |
| 2346 | When using --ifconfig on Windows, set the TAP-Win32 adapter IP address and netmask using method. Don't use this option |
| 2347 | unless you are also using --ifconfig. |
| 2348 | |
| 2349 | manual -- Don't set the IP address or netmask automatically. Instead output a message to the console telling the user |
| 2350 | to configure the adapter manually and indicating the IP/netmask which OpenVPN expects the adapter to be set to. |
| 2351 | |
| 2352 | dynamic [offset] [lease-time] -- Automatically set the IP address and netmask by replying to DHCP query messages gener‐ |
| 2353 | ated by the kernel. This mode is probably the "cleanest" solution for setting the TCP/IP properties since it uses the |
| 2354 | well-known DHCP protocol. There are, however, two prerequisites for using this mode: (1) The TCP/IP properties for the |
| 2355 | TAP-Win32 adapter must be set to "Obtain an IP address automatically," and (2) OpenVPN needs to claim an IP address in |
| 2356 | the subnet for use as the virtual DHCP server address. By default in --dev tap mode, OpenVPN will take the normally |
| 2357 | unused first address in the subnet. For example, if your subnet is 192.168.4.0 netmask 255.255.255.0, then OpenVPN will |
| 2358 | take the IP address 192.168.4.0 to use as the virtual DHCP server address. In --dev tun mode, OpenVPN will cause the |
| 2359 | DHCP server to masquerade as if it were coming from the remote endpoint. The optional offset parameter is an integer |
| 2360 | which is > -256 and < 256 and which defaults to 0. If offset is positive, the DHCP server will masquerade as the IP |
| 2361 | address at network address + offset. If offset is negative, the DHCP server will masquerade as the IP address at broad‐ |
| 2362 | cast address + offset. The Windows ipconfig /all command can be used to show what Windows thinks the DHCP server |
| 2363 | address is. OpenVPN will "claim" this address, so make sure to use a free address. Having said that, different OpenVPN |
| 2364 | instantiations, including different ends of the same connection, can share the same virtual DHCP server address. The |
| 2365 | lease-time parameter controls the lease time of the DHCP assignment given to the TAP-Win32 adapter, and is denoted in |
| 2366 | seconds. Normally a very long lease time is preferred because it prevents routes involving the TAP-Win32 adapter from |
| 2367 | being lost when the system goes to sleep. The default lease time is one year. |
| 2368 | |
| 2369 | netsh -- Automatically set the IP address and netmask using the Windows command-line "netsh" command. This method |
| 2370 | appears to work correctly on Windows XP but not Windows 2000. |
| 2371 | |
| 2372 | ipapi -- Automatically set the IP address and netmask using the Windows IP Helper API. This approach does not have |
| 2373 | ideal semantics, though testing has indicated that it works okay in practice. If you use this option, it is best to |
| 2374 | leave the TCP/IP properties for the TAP-Win32 adapter in their default state, i.e. "Obtain an IP address automatically." |
| 2375 | |
| 2376 | adaptive -- (Default) Try dynamic method initially and fail over to netsh if the DHCP negotiation with the TAP-Win32 |
| 2377 | adapter does not succeed in 20 seconds. Such failures have been known to occur when certain third-party firewall pack‐ |
| 2378 | ages installed on the client machine block the DHCP negotiation used by the TAP-Win32 adapter. Note that if the netsh |
| 2379 | failover occurs, the TAP-Win32 adapter TCP/IP properties will be reset from DHCP to static, and this will cause future |
| 2380 | OpenVPN startups using the adaptive mode to use netsh immediately, rather than trying dynamic first. To "unstick" the |
| 2381 | adaptive mode from using netsh, run OpenVPN at least once using the dynamic mode to restore the TAP-Win32 adapter TCP/IP |
| 2382 | properties to a DHCP configuration. |
| 2383 | |
| 2384 | --route-method m |
| 2385 | Which method m to use for adding routes on Windows? |
| 2386 | |
| 2387 | adaptive (default) -- Try IP helper API first. If that fails, fall back to the route.exe shell command. |
| 2388 | ipapi -- Use IP helper API. |
| 2389 | exe -- Call the route.exe shell command. |
| 2390 | |
| 2391 | --dhcp-option type [parm] |
| 2392 | Set extended TAP-Win32 TCP/IP properties, must be used with --ip-win32 dynamic or --ip-win32 adaptive. This option can |
| 2393 | be used to set additional TCP/IP properties on the TAP-Win32 adapter, and is particularly useful for configuring an |
| 2394 | OpenVPN client to access a Samba server across the VPN. |
| 2395 | |
| 2396 | DOMAIN name -- Set Connection-specific DNS Suffix. |
| 2397 | |
| 2398 | DNS addr -- Set primary domain name server address. Repeat this option to set secondary DNS server addresses. |
| 2399 | |
| 2400 | WINS addr -- Set primary WINS server address (NetBIOS over TCP/IP Name Server). Repeat this option to set secondary |
| 2401 | WINS server addresses. |
| 2402 | |
| 2403 | NBDD addr -- Set primary NBDD server address (NetBIOS over TCP/IP Datagram Distribution Server) Repeat this option to |
| 2404 | set secondary NBDD server addresses. |
| 2405 | |
| 2406 | NTP addr -- Set primary NTP server address (Network Time Protocol). Repeat this option to set secondary NTP server |
| 2407 | addresses. |
| 2408 | |
| 2409 | NBT type -- Set NetBIOS over TCP/IP Node type. Possible options: 1 = b-node (broadcasts), 2 = p-node (point-to-point |
| 2410 | name queries to a WINS server), 4 = m-node (broadcast then query name server), and 8 = h-node (query name server, then |
| 2411 | broadcast). |
| 2412 | |
| 2413 | NBS scope-id -- Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID provides an extended naming service for the NetBIOS |
| 2414 | over TCP/IP (Known as NBT) module. The primary purpose of a NetBIOS scope ID is to isolate NetBIOS traffic on a single |
| 2415 | network to only those nodes with the same NetBIOS scope ID. The NetBIOS scope ID is a character string that is appended |
| 2416 | to the NetBIOS name. The NetBIOS scope ID on two hosts must match, or the two hosts will not be able to communicate. The |
| 2417 | NetBIOS Scope ID also allows computers to use the same computer name, as they have different scope IDs. The Scope ID |
| 2418 | becomes a part of the NetBIOS name, making the name unique. (This description of NetBIOS scopes courtesy of Neon‐ |
| 2419 | Surge@abyss.com) |
| 2420 | |
| 2421 | DISABLE-NBT -- Disable Netbios-over-TCP/IP. |
| 2422 | |
| 2423 | Note that if --dhcp-option is pushed via --push to a non-windows client, the option will be saved in the client's envi‐ |
| 2424 | ronment before the up script is called, under the name "foreign_option_{n}". |
| 2425 | |
| 2426 | --tap-sleep n |
| 2427 | Cause OpenVPN to sleep for n seconds immediately after the TAP-Win32 adapter state is set to "connected". |
| 2428 | |
| 2429 | This option is intended to be used to troubleshoot problems with the --ifconfig and --ip-win32 options, and is used to |
| 2430 | give the TAP-Win32 adapter time to come up before Windows IP Helper API operations are applied to it. |
| 2431 | |
| 2432 | --show-net-up |
| 2433 | Output OpenVPN's view of the system routing table and network adapter list to the syslog or log file after the TUN/TAP |
| 2434 | adapter has been brought up and any routes have been added. |
| 2435 | |
| 2436 | --dhcp-renew |
| 2437 | Ask Windows to renew the TAP adapter lease on startup. This option is normally unnecessary, as Windows automatically |
| 2438 | triggers a DHCP renegotiation on the TAP adapter when it comes up, however if you set the TAP-Win32 adapter Media Status |
| 2439 | property to "Always Connected", you may need this flag. |
| 2440 | |
| 2441 | --dhcp-release |
| 2442 | Ask Windows to release the TAP adapter lease on shutdown. This option has the same caveats as --dhcp-renew above. |
| 2443 | |
| 2444 | --register-dns |
| 2445 | Run net stop dnscache, net start dnscache, ipconfig /flushdns and ipconfig /registerdns on connection initiation. This |
| 2446 | is known to kick Windows into recognizing pushed DNS servers. |
| 2447 | |
| 2448 | --pause-exit |
| 2449 | Put up a "press any key to continue" message on the console prior to OpenVPN program exit. This option is automatically |
| 2450 | used by the Windows explorer when OpenVPN is run on a configuration file using the right-click explorer menu. |
| 2451 | |
| 2452 | --service exit-event [0|1] |
| 2453 | Should be used when OpenVPN is being automatically executed by another program in such a context that no interaction |
| 2454 | with the user via display or keyboard is possible. In general, end-users should never need to explicitly use this |
| 2455 | option, as it is automatically added by the OpenVPN service wrapper when a given OpenVPN configuration is being run as a |
| 2456 | service. |
| 2457 | |
| 2458 | exit-event is the name of a Windows global event object, and OpenVPN will continuously monitor the state of this event |
| 2459 | object and exit when it becomes signaled. |
| 2460 | |
| 2461 | The second parameter indicates the initial state of exit-event and normally defaults to 0. |
| 2462 | |
| 2463 | Multiple OpenVPN processes can be simultaneously executed with the same exit-event parameter. In any case, the control‐ |
| 2464 | ling process can signal exit-event, causing all such OpenVPN processes to exit. |
| 2465 | |
| 2466 | When executing an OpenVPN process using the --service directive, OpenVPN will probably not have a console window to out‐ |
| 2467 | put status/error messages, therefore it is useful to use --log or --log-append to write these messages to a file. |
| 2468 | |
| 2469 | --show-adapters |
| 2470 | (Standalone) Show available TAP-Win32 adapters which can be selected using the --dev-node option. On non-Windows sys‐ |
| 2471 | tems, the ifconfig(8) command provides similar functionality. |
| 2472 | |
| 2473 | --allow-nonadmin [TAP-adapter] |
| 2474 | (Standalone) Set TAP-adapter to allow access from non-administrative accounts. If TAP-adapter is omitted, all TAP |
| 2475 | adapters on the system will be configured to allow non-admin access. The non-admin access setting will only persist for |
| 2476 | the length of time that the TAP-Win32 device object and driver remain loaded, and will need to be re-enabled after a |
| 2477 | reboot, or if the driver is unloaded and reloaded. This directive can only be used by an administrator. |
| 2478 | |
| 2479 | --show-valid-subnets |
| 2480 | (Standalone) Show valid subnets for --dev tun emulation. Since the TAP-Win32 driver exports an ethernet interface to |
| 2481 | Windows, and since TUN devices are point-to-point in nature, it is necessary for the TAP-Win32 driver to impose certain |
| 2482 | constraints on TUN endpoint address selection. |
| 2483 | |
| 2484 | Namely, the point-to-point endpoints used in TUN device emulation must be the middle two addresses of a /30 subnet (net‐ |
| 2485 | mask 255.255.255.252). |
| 2486 | |
| 2487 | --show-net |
| 2488 | (Standalone) Show OpenVPN's view of the system routing table and network adapter list. |
| 2489 | |
| 2490 | PKCS#11 Standalone Options: |
| 2491 | --show-pkcs11-ids provider [cert_private] |
| 2492 | (Standalone) Show PKCS#11 token object list. Specify cert_private as 1 if certificates are stored as private objects. |
| 2493 | |
| 2494 | --verb option can be used BEFORE this option to produce debugging information. |
| 2495 | |
| 2496 | IPv6 Related Options |
| 2497 | The following options exist to support IPv6 tunneling in peer-to-peer and client-server mode. As of now, this is just very |
| 2498 | basic documentation of the IPv6-related options. More documentation can be found on http://www.greenie.net/ipv6/openvpn.html. |
| 2499 | |
| 2500 | --ifconfig-ipv6 ipv6addr/bits ipv6remote |
| 2501 | configure IPv6 address ipv6addr/bits on the ``tun'' device. The second parameter is used as route target for --route- |
| 2502 | ipv6 if no gateway is specified. |
| 2503 | |
| 2504 | --route-ipv6 ipv6addr/bits [gateway] [metric] |
| 2505 | setup IPv6 routing in the system to send the specified IPv6 network into OpenVPN's ``tun'' device |
| 2506 | |
| 2507 | --server-ipv6 ipv6addr/bits |
| 2508 | convenience-function to enable a number of IPv6 related options at once, namely --ifconfig-ipv6, --ifconfig-ipv6-pool, |
| 2509 | --tun-ipv6 and --push tun-ipv6 Is only accepted if ``--mode server'' or ``--server'' is set. |
| 2510 | |
| 2511 | --ifconfig-ipv6-pool ipv6addr/bits |
| 2512 | Specify an IPv6 address pool for dynamic assignment to clients. The pool starts at ipv6addr and increments by +1 for |
| 2513 | every new client (linear mode). The /bits setting controls the size of the pool. |
| 2514 | |
| 2515 | --ifconfig-ipv6-push ipv6addr/bits ipv6remote |
| 2516 | for ccd/ per-client static IPv6 interface configuration, see --client-config-dir and --ifconfig-push for more details. |
| 2517 | |
| 2518 | --iroute-ipv6 ipv6addr/bits |
| 2519 | for ccd/ per-client static IPv6 route configuration, see --iroute for more details how to setup and use this, and how |
| 2520 | --iroute and --route interact. |
| 2521 | |
| 2522 | |
| 2523 | SCRIPTING AND ENVIRONMENTAL VARIABLES |
| 2524 | OpenVPN exports a series of environmental variables for use by user-defined scripts. |
| 2525 | |
| 2526 | Script Order of Execution |
| 2527 | --up Executed after TCP/UDP socket bind and TUN/TAP open. |
| 2528 | |
| 2529 | --tls-verify |
| 2530 | Executed when we have a still untrusted remote peer. |
| 2531 | |
| 2532 | --ipchange |
| 2533 | Executed after connection authentication, or remote IP address change. |
| 2534 | |
| 2535 | --client-connect |
| 2536 | Executed in --mode server mode immediately after client authentication. |
| 2537 | |
| 2538 | --route-up |
| 2539 | Executed after connection authentication, either immediately after, or some number of seconds after as defined by the |
| 2540 | --route-delay option. |
| 2541 | |
| 2542 | --route-pre-down |
| 2543 | Executed right before the routes are removed. |
| 2544 | |
| 2545 | --client-disconnect |
| 2546 | Executed in --mode server mode on client instance shutdown. |
| 2547 | |
| 2548 | --down Executed after TCP/UDP and TUN/TAP close. |
| 2549 | |
| 2550 | --learn-address |
| 2551 | Executed in --mode server mode whenever an IPv4 address/route or MAC address is added to OpenVPN's internal routing ta‐ |
| 2552 | ble. |
| 2553 | |
| 2554 | --auth-user-pass-verify |
| 2555 | Executed in --mode server mode on new client connections, when the client is still untrusted. |
| 2556 | |
| 2557 | String Types and Remapping |
| 2558 | In certain cases, OpenVPN will perform remapping of characters in strings. Essentially, any characters outside the set of per‐ |
| 2559 | mitted characters for each string type will be converted to underbar ('_'). |
| 2560 | |
| 2561 | Q: Why is string remapping necessary? |
| 2562 | |
| 2563 | A: It's an important security feature to prevent the malicious coding of strings from untrusted sources to be passed as parame‐ |
| 2564 | ters to scripts, saved in the environment, used as a common name, translated to a filename, etc. |
| 2565 | |
| 2566 | Q: Can string remapping be disabled? |
| 2567 | |
| 2568 | A: Yes, by using the --no-name-remapping option, however this should be considered an advanced option. |
| 2569 | |
| 2570 | Here is a brief rundown of OpenVPN's current string types and the permitted character class for each string: |
| 2571 | |
| 2572 | X509 Names: Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), at ('@'), colon (':'), slash ('/'), and equal ('='). Alphanu‐ |
| 2573 | meric is defined as a character which will cause the C library isalnum() function to return true. |
| 2574 | |
| 2575 | Common Names: Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), and at ('@'). |
| 2576 | |
| 2577 | --auth-user-pass username: Same as Common Name, with one exception: starting with OpenVPN 2.0.1, the username is passed to the |
| 2578 | OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin in its raw form, without string remapping. |
| 2579 | |
| 2580 | --auth-user-pass password: Any "printable" character except CR or LF. Printable is defined to be a character which will cause |
| 2581 | the C library isprint() function to return true. |
| 2582 | |
| 2583 | --client-config-dir filename as derived from common name or username: Alphanumeric, underbar ('_'), dash ('-'), and dot ('.') |
| 2584 | except for "." or ".." as standalone strings. As of 2.0.1-rc6, the at ('@') character has been added as well for compatibility |
| 2585 | with the common name character class. |
| 2586 | |
| 2587 | Environmental variable names: Alphanumeric or underbar ('_'). |
| 2588 | |
| 2589 | Environmental variable values: Any printable character. |
| 2590 | |
| 2591 | For all cases, characters in a string which are not members of the legal character class for that string type will be remapped |
| 2592 | to underbar ('_'). |
| 2593 | |
| 2594 | Environmental Variables |
| 2595 | Once set, a variable is persisted indefinitely until it is reset by a new value or a restart, |
| 2596 | |
| 2597 | As of OpenVPN 2.0-beta12, in server mode, environmental variables set by OpenVPN are scoped according to the client objects |
| 2598 | they are associated with, so there should not be any issues with scripts having access to stale, previously set variables which |
| 2599 | refer to different client instances. |
| 2600 | |
| 2601 | bytes_received |
| 2602 | Total number of bytes received from client during VPN session. Set prior to execution of the --client-disconnect |
| 2603 | script. |
| 2604 | |
| 2605 | bytes_sent |
| 2606 | Total number of bytes sent to client during VPN session. Set prior to execution of the --client-disconnect script. |
| 2607 | |
| 2608 | common_name |
| 2609 | The X509 common name of an authenticated client. Set prior to execution of --client-connect, --client-disconnect, and |
| 2610 | --auth-user-pass-verify scripts. |
| 2611 | |
| 2612 | config Name of first --config file. Set on program initiation and reset on SIGHUP. |
| 2613 | |
| 2614 | daemon Set to "1" if the --daemon directive is specified, or "0" otherwise. Set on program initiation and reset on SIGHUP. |
| 2615 | |
| 2616 | daemon_log_redirect |
| 2617 | Set to "1" if the --log or --log-append directives are specified, or "0" otherwise. Set on program initiation and reset |
| 2618 | on SIGHUP. |
| 2619 | |
| 2620 | dev The actual name of the TUN/TAP device, including a unit number if it exists. Set prior to --up or --down script execu‐ |
| 2621 | tion. |
| 2622 | |
| 2623 | foreign_option_{n} |
| 2624 | An option pushed via --push to a client which does not natively support it, such as --dhcp-option on a non-Windows sys‐ |
| 2625 | tem, will be recorded to this environmental variable sequence prior to --up script execution. |
| 2626 | |
| 2627 | ifconfig_broadcast |
| 2628 | The broadcast address for the virtual ethernet segment which is derived from the --ifconfig option when --dev tap is |
| 2629 | used. Set prior to OpenVPN calling the ifconfig or netsh (windows version of ifconfig) commands which normally occurs |
| 2630 | prior to --up script execution. |
| 2631 | |
| 2632 | ifconfig_ipv6_local |
| 2633 | The local VPN endpoint IPv6 address specified in the --ifconfig-ipv6 option (first parameter). Set prior to OpenVPN |
| 2634 | calling the ifconfig or netsh (windows version of ifconfig) commands which normally occurs prior to --up script execu‐ |
| 2635 | tion. |
| 2636 | |
| 2637 | ifconfig_ipv6_netbits |
| 2638 | The prefix length of the IPv6 network on the VPN interface. Derived from the /nnn parameter of the IPv6 address in the |
| 2639 | --ifconfig-ipv6 option (first parameter). Set prior to OpenVPN calling the ifconfig or netsh (windows version of ifcon‐ |
| 2640 | fig) commands which normally occurs prior to --up script execution. |
| 2641 | |
| 2642 | ifconfig_ipv6_remote |
| 2643 | The remote VPN endpoint IPv6 address specified in the --ifconfig-ipv6 option (second parameter). Set prior to OpenVPN |
| 2644 | calling the ifconfig or netsh (windows version of ifconfig) commands which normally occurs prior to --up script execu‐ |
| 2645 | tion. |
| 2646 | |
| 2647 | ifconfig_local |
| 2648 | The local VPN endpoint IP address specified in the --ifconfig option (first parameter). Set prior to OpenVPN calling |
| 2649 | the ifconfig or netsh (windows version of ifconfig) commands which normally occurs prior to --up script execution. |
| 2650 | |
| 2651 | ifconfig_remote |
| 2652 | The remote VPN endpoint IP address specified in the --ifconfig option (second parameter) when --dev tun is used. Set |
| 2653 | prior to OpenVPN calling the ifconfig or netsh (windows version of ifconfig) commands which normally occurs prior to |
| 2654 | --up script execution. |
| 2655 | |
| 2656 | ifconfig_netmask |
| 2657 | The subnet mask of the virtual ethernet segment that is specified as the second parameter to --ifconfig when --dev tap |
| 2658 | is being used. Set prior to OpenVPN calling the ifconfig or netsh (windows version of ifconfig) commands which normally |
| 2659 | occurs prior to --up script execution. |
| 2660 | |
| 2661 | ifconfig_pool_local_ip |
| 2662 | The local virtual IP address for the TUN/TAP tunnel taken from an --ifconfig-push directive if specified, or otherwise |
| 2663 | from the ifconfig pool (controlled by the --ifconfig-pool config file directive). Only set for --dev tun tunnels. This |
| 2664 | option is set on the server prior to execution of the --client-connect and --client-disconnect scripts. |
| 2665 | |
| 2666 | ifconfig_pool_netmask |
| 2667 | The virtual IP netmask for the TUN/TAP tunnel taken from an --ifconfig-push directive if specified, or otherwise from |
| 2668 | the ifconfig pool (controlled by the --ifconfig-pool config file directive). Only set for --dev tap tunnels. This |
| 2669 | option is set on the server prior to execution of the --client-connect and --client-disconnect scripts. |
| 2670 | |
| 2671 | ifconfig_pool_remote_ip |
| 2672 | The remote virtual IP address for the TUN/TAP tunnel taken from an --ifconfig-push directive if specified, or otherwise |
| 2673 | from the ifconfig pool (controlled by the --ifconfig-pool config file directive). This option is set on the server |
| 2674 | prior to execution of the --client-connect and --client-disconnect scripts. |
| 2675 | |
| 2676 | link_mtu |
| 2677 | The maximum packet size (not including the IP header) of tunnel data in UDP tunnel transport mode. Set prior to --up or |
| 2678 | --down script execution. |
| 2679 | |
| 2680 | local The --local parameter. Set on program initiation and reset on SIGHUP. |
| 2681 | |
| 2682 | local_port |
| 2683 | The local port number, specified by --port or --lport. Set on program initiation and reset on SIGHUP. |
| 2684 | |
| 2685 | password |
| 2686 | The password provided by a connecting client. Set prior to --auth-user-pass-verify script execution only when the via- |
| 2687 | env modifier is specified, and deleted from the environment after the script returns. |
| 2688 | |
| 2689 | proto The --proto parameter. Set on program initiation and reset on SIGHUP. |
| 2690 | |
| 2691 | remote_{n} |
| 2692 | The --remote parameter. Set on program initiation and reset on SIGHUP. |
| 2693 | |
| 2694 | remote_port_{n} |
| 2695 | The remote port number, specified by --port or --rport. Set on program initiation and reset on SIGHUP. |
| 2696 | |
| 2697 | route_net_gateway |
| 2698 | The pre-existing default IP gateway in the system routing table. Set prior to --up script execution. |
| 2699 | |
| 2700 | route_vpn_gateway |
| 2701 | The default gateway used by --route options, as specified in either the --route-gateway option or the second parameter |
| 2702 | to --ifconfig when --dev tun is specified. Set prior to --up script execution. |
| 2703 | |
| 2704 | route_{parm}_{n} |
| 2705 | A set of variables which define each route to be added, and are set prior to --up script execution. |
| 2706 | |
| 2707 | parm will be one of "network", "netmask", "gateway", or "metric". |
| 2708 | |
| 2709 | n is the OpenVPN route number, starting from 1. |
| 2710 | |
| 2711 | If the network or gateway are resolvable DNS names, their IP address translations will be recorded rather than their |
| 2712 | names as denoted on the command line or configuration file. |
| 2713 | |
| 2714 | route_ipv6_{parm}_{n} |
| 2715 | A set of variables which define each IPv6 route to be added, and are set prior to --up script execution. |
| 2716 | |
| 2717 | parm will be one of "network" or "gateway" ("netmask" is contained as "/nnn" in the route_ipv6_network_{n}, unlike IPv4 |
| 2718 | where it is passed in a separate environment variable). |
| 2719 | |
| 2720 | n is the OpenVPN route number, starting from 1. |
| 2721 | |
| 2722 | If the network or gateway are resolvable DNS names, their IP address translations will be recorded rather than their |
| 2723 | names as denoted on the command line or configuration file. |
| 2724 | |
| 2725 | peer_cert |
| 2726 | Temporary file name containing the client certificate upon connection. Useful in conjunction with --tls-verify |
| 2727 | |
| 2728 | script_context |
| 2729 | Set to "init" or "restart" prior to up/down script execution. For more information, see documentation for --up. |
| 2730 | |
| 2731 | script_type |
| 2732 | Prior to execution of any script, this variable is set to the type of script being run. It can be one of the following: |
| 2733 | up, down, ipchange, route-up, tls-verify, auth-user-pass-verify, client-connect, client-disconnect, or learn-address. |
| 2734 | Set prior to execution of any script. |
| 2735 | |
| 2736 | signal The reason for exit or restart. Can be one of sigusr1, sighup, sigterm, sigint, inactive (controlled by --inactive |
| 2737 | option), ping-exit (controlled by --ping-exit option), ping-restart (controlled by --ping-restart option), connection- |
| 2738 | reset (triggered on TCP connection reset), error, or unknown (unknown signal). This variable is set just prior to down |
| 2739 | script execution. |
| 2740 | |
| 2741 | time_ascii |
| 2742 | Client connection timestamp, formatted as a human-readable time string. Set prior to execution of the --client-connect |
| 2743 | script. |
| 2744 | |
| 2745 | time_duration |
| 2746 | The duration (in seconds) of the client session which is now disconnecting. Set prior to execution of the --client-dis‐ |
| 2747 | connect script. |
| 2748 | |
| 2749 | time_unix |
| 2750 | Client connection timestamp, formatted as a unix integer date/time value. Set prior to execution of the --client-con‐ |
| 2751 | nect script. |
| 2752 | |
| 2753 | tls_id_{n} |
| 2754 | A series of certificate fields from the remote peer, where n is the verification level. Only set for TLS connections. |
| 2755 | Set prior to execution of --tls-verify script. |
| 2756 | |
| 2757 | tls_serial_{n} |
| 2758 | The serial number of the certificate from the remote peer, where n is the verification level. Only set for TLS connec‐ |
| 2759 | tions. Set prior to execution of --tls-verify script. This is in the form of a hex string like "37AB46E0", which is |
| 2760 | suitable for doing serial-based OCSP queries (with OpenSSL, you have to prepend "0x" to the string). If something goes |
| 2761 | wrong while reading the value from the certificate it will be an empty string, so your code should check that. See the |
| 2762 | contrib/OCSP_check/OCSP_check.sh script for an example. |
| 2763 | |
| 2764 | tun_mtu |
| 2765 | The MTU of the TUN/TAP device. Set prior to --up or --down script execution. |
| 2766 | |
| 2767 | trusted_ip (or trusted_ip6) |
| 2768 | Actual IP address of connecting client or peer which has been authenticated. Set prior to execution of --ipchange, |
| 2769 | --client-connect, and --client-disconnect scripts. If using ipv6 endpoints (udp6, tcp6), trusted_ip6 will be set |
| 2770 | instead. |
| 2771 | |
| 2772 | trusted_port |
| 2773 | Actual port number of connecting client or peer which has been authenticated. Set prior to execution of --ipchange, |
| 2774 | --client-connect, and --client-disconnect scripts. |
| 2775 | |
| 2776 | untrusted_ip (or untrusted_ip6) |
| 2777 | Actual IP address of connecting client or peer which has not been authenticated yet. Sometimes used to nmap the con‐ |
| 2778 | necting host in a --tls-verify script to ensure it is firewalled properly. Set prior to execution of --tls-verify and |
| 2779 | --auth-user-pass-verify scripts. If using ipv6 endpoints (udp6, tcp6), untrusted_ip6 will be set instead. |
| 2780 | |
| 2781 | untrusted_port |
| 2782 | Actual port number of connecting client or peer which has not been authenticated yet. Set prior to execution of --tls- |
| 2783 | verify and --auth-user-pass-verify scripts. |
| 2784 | |
| 2785 | username |
| 2786 | The username provided by a connecting client. Set prior to --auth-user-pass-verify script execution only when the via- |
| 2787 | env modifier is specified. |
| 2788 | |
| 2789 | X509_{n}_{subject_field} |
| 2790 | An X509 subject field from the remote peer certificate, where n is the verification level. Only set for TLS connec‐ |
| 2791 | tions. Set prior to execution of --tls-verify script. This variable is similar to tls_id_{n} except the component X509 |
| 2792 | subject fields are broken out, and no string remapping occurs on these field values (except for remapping of control |
| 2793 | characters to "_"). For example, the following variables would be set on the OpenVPN server using the sample client |
| 2794 | certificate in sample-keys (client.crt). Note that the verification level is 0 for the client certificate and 1 for the |
| 2795 | CA certificate. |
| 2796 | |
| 2797 | X509_0_emailAddress=me@myhost.mydomain |
| 2798 | X509_0_CN=Test-Client |
| 2799 | X509_0_O=OpenVPN-TEST |
| 2800 | X509_0_ST=NA |
| 2801 | X509_0_C=KG |
| 2802 | X509_1_emailAddress=me@myhost.mydomain |
| 2803 | X509_1_O=OpenVPN-TEST |
| 2804 | X509_1_L=BISHKEK |
| 2805 | X509_1_ST=NA |
| 2806 | X509_1_C=KG |
| 2807 | |
| 2808 | SIGNALS |
| 2809 | SIGHUP Cause OpenVPN to close all TUN/TAP and network connections, restart, re-read the configuration file (if any), and reopen |
| 2810 | TUN/TAP and network connections. |
| 2811 | |
| 2812 | SIGUSR1 |
| 2813 | Like SIGHUP, except don't re-read configuration file, and possibly don't close and reopen TUN/TAP device, re-read key |
| 2814 | files, preserve local IP address/port, or preserve most recently authenticated remote IP address/port based on --per‐ |
| 2815 | sist-tun, --persist-key, --persist-local-ip, and --persist-remote-ip options respectively (see above). |
| 2816 | |
| 2817 | This signal may also be internally generated by a timeout condition, governed by the --ping-restart option. |
| 2818 | |
| 2819 | This signal, when combined with --persist-remote-ip, may be sent when the underlying parameters of the host's network |
| 2820 | interface change such as when the host is a DHCP client and is assigned a new IP address. See --ipchange above for more |
| 2821 | information. |
| 2822 | |
| 2823 | SIGUSR2 |
| 2824 | Causes OpenVPN to display its current statistics (to the syslog file if --daemon is used, or stdout otherwise). |
| 2825 | |
| 2826 | SIGINT, SIGTERM |
| 2827 | Causes OpenVPN to exit gracefully. |
| 2828 | |
| 2829 | TUN/TAP DRIVER SETUP |
| 2830 | If you are running Linux 2.4.7 or higher, you probably have the TUN/TAP driver already installed. If so, there are still a few |
| 2831 | things you need to do: |
| 2832 | |
| 2833 | Make device: mknod /dev/net/tun c 10 200 |
| 2834 | |
| 2835 | Load driver: modprobe tun |
| 2836 | |
| 2837 | EXAMPLES |
| 2838 | Prior to running these examples, you should have OpenVPN installed on two machines with network connectivity between them. If |
| 2839 | you have not yet installed OpenVPN, consult the INSTALL file included in the OpenVPN distribution. |
| 2840 | |
| 2841 | TUN/TAP Setup: |
| 2842 | If you are using Linux 2.4 or higher, make the tun device node and load the tun module: |
| 2843 | |
| 2844 | mknod /dev/net/tun c 10 200 |
| 2845 | |
| 2846 | modprobe tun |
| 2847 | |
| 2848 | If you installed from RPM, the mknod step may be omitted, because the RPM install does that for you. |
| 2849 | |
| 2850 | Only Linux 2.4 and newer are supported. |
| 2851 | |
| 2852 | For other platforms, consult the INSTALL file at http://openvpn.net/install.html for more information. |
| 2853 | |
| 2854 | Firewall Setup: |
| 2855 | If firewalls exist between the two machines, they should be set to forward UDP port 1194 in both directions. If you do not |
| 2856 | have control over the firewalls between the two machines, you may still be able to use OpenVPN by adding --ping 15 to each of |
| 2857 | the openvpn commands used below in the examples (this will cause each peer to send out a UDP ping to its remote peer once every |
| 2858 | 15 seconds which will cause many stateful firewalls to forward packets in both directions without an explicit firewall rule). |
| 2859 | |
| 2860 | If you are using a Linux iptables-based firewall, you may need to enter the following command to allow incoming packets on the |
| 2861 | TUN device: |
| 2862 | |
| 2863 | iptables -A INPUT -i tun+ -j ACCEPT |
| 2864 | |
| 2865 | See the firewalls section below for more information on configuring firewalls for use with OpenVPN. |
| 2866 | |
| 2867 | VPN Address Setup: |
| 2868 | For purposes of our example, our two machines will be called may.kg and june.kg. If you are constructing a VPN over the inter‐ |
| 2869 | net, then replace may.kg and june.kg with the internet hostname or IP address that each machine will use to contact the other |
| 2870 | over the internet. |
| 2871 | |
| 2872 | Now we will choose the tunnel endpoints. Tunnel endpoints are private IP addresses that only have meaning in the context of |
| 2873 | the VPN. Each machine will use the tunnel endpoint of the other machine to access it over the VPN. In our example, the tunnel |
| 2874 | endpoint for may.kg will be 10.4.0.1 and for june.kg, 10.4.0.2. |
| 2875 | |
| 2876 | Once the VPN is established, you have essentially created a secure alternate path between the two hosts which is addressed by |
| 2877 | using the tunnel endpoints. You can control which network traffic passes between the hosts (a) over the VPN or (b) indepen‐ |
| 2878 | dently of the VPN, by choosing whether to use (a) the VPN endpoint address or (b) the public internet address, to access the |
| 2879 | remote host. For example if you are on may.kg and you wish to connect to june.kg via ssh without using the VPN (since ssh has |
| 2880 | its own built-in security) you would use the command ssh june.kg. However in the same scenario, you could also use the command |
| 2881 | telnet 10.4.0.2 to create a telnet session with june.kg over the VPN, that would use the VPN to secure the session rather than |
| 2882 | ssh. |
| 2883 | |
| 2884 | You can use any address you wish for the tunnel endpoints but make sure that they are private addresses (such as those that |
| 2885 | begin with 10 or 192.168) and that they are not part of any existing subnet on the networks of either peer, unless you are |
| 2886 | bridging. If you use an address that is part of your local subnet for either of the tunnel endpoints, you will get a weird |
| 2887 | feedback loop. |
| 2888 | |
| 2889 | Example 1: A simple tunnel without security |
| 2890 | On may: |
| 2891 | |
| 2892 | openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 --verb 9 |
| 2893 | |
| 2894 | On june: |
| 2895 | |
| 2896 | openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 --verb 9 |
| 2897 | |
| 2898 | Now verify the tunnel is working by pinging across the tunnel. |
| 2899 | |
| 2900 | On may: |
| 2901 | |
| 2902 | ping 10.4.0.2 |
| 2903 | |
| 2904 | On june: |
| 2905 | |
| 2906 | ping 10.4.0.1 |
| 2907 | |
| 2908 | The --verb 9 option will produce verbose output, similar to the tcpdump(8) program. Omit the --verb 9 option to have OpenVPN |
| 2909 | run quietly. |
| 2910 | |
| 2911 | Example 2: A tunnel with static-key security (i.e. using a pre-shared secret) |
| 2912 | First build a static key on may. |
| 2913 | |
| 2914 | openvpn --genkey --secret key |
| 2915 | |
| 2916 | This command will build a random key file called key (in ascii format). Now copy key to june over a secure medium such as by |
| 2917 | using the scp(1) program. |
| 2918 | |
| 2919 | On may: |
| 2920 | |
| 2921 | openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 --verb 5 --secret key |
| 2922 | |
| 2923 | On june: |
| 2924 | |
| 2925 | openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 --verb 5 --secret key |
| 2926 | |
| 2927 | Now verify the tunnel is working by pinging across the tunnel. |
| 2928 | |
| 2929 | On may: |
| 2930 | |
| 2931 | ping 10.4.0.2 |
| 2932 | |
| 2933 | On june: |
| 2934 | |
| 2935 | ping 10.4.0.1 |
| 2936 | |
| 2937 | Example 3: A tunnel with full TLS-based security |
| 2938 | For this test, we will designate may as the TLS client and june as the TLS server. Note that client or server designation only |
| 2939 | has meaning for the TLS subsystem. It has no bearing on OpenVPN's peer-to-peer, UDP-based communication model. |
| 2940 | |
| 2941 | First, build a separate certificate/key pair for both may and june (see above where --cert is discussed for more info). Then |
| 2942 | construct Diffie Hellman parameters (see above where --dh is discussed for more info). You can also use the included test |
| 2943 | files client.crt, client.key, server.crt, server.key and ca.crt. The .crt files are certificates/public-keys, the .key files |
| 2944 | are private keys, and ca.crt is a certification authority who has signed both client.crt and server.crt. For Diffie Hellman |
| 2945 | parameters you can use the included file dh1024.pem. Note that all client, server, and certificate authority certificates and |
| 2946 | keys included in the OpenVPN distribution are totally insecure and should be used for testing only. |
| 2947 | |
| 2948 | On may: |
| 2949 | |
| 2950 | openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 --tls-client --ca ca.crt --cert client.crt --key |
| 2951 | client.key --reneg-sec 60 --verb 5 |
| 2952 | |
| 2953 | On june: |
| 2954 | |
| 2955 | openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 --tls-server --dh dh1024.pem --ca ca.crt --cert |
| 2956 | server.crt --key server.key --reneg-sec 60 --verb 5 |
| 2957 | |
| 2958 | Now verify the tunnel is working by pinging across the tunnel. |
| 2959 | |
| 2960 | On may: |
| 2961 | |
| 2962 | ping 10.4.0.2 |
| 2963 | |
| 2964 | On june: |
| 2965 | |
| 2966 | ping 10.4.0.1 |
| 2967 | |
| 2968 | Notice the --reneg-sec 60 option we used above. That tells OpenVPN to renegotiate the data channel keys every minute. Since |
| 2969 | we used --verb 5 above, you will see status information on each new key negotiation. |
| 2970 | |
| 2971 | For production operations, a key renegotiation interval of 60 seconds is probably too frequent. Omit the --reneg-sec 60 option |
| 2972 | to use OpenVPN's default key renegotiation interval of one hour. |
| 2973 | |
| 2974 | Routing: |
| 2975 | Assuming you can ping across the tunnel, the next step is to route a real subnet over the secure tunnel. Suppose that may and |
| 2976 | june have two network interfaces each, one connected to the internet, and the other to a private network. Our goal is to |
| 2977 | securely connect both private networks. We will assume that may's private subnet is 10.0.0.0/24 and june's is 10.0.1.0/24. |
| 2978 | |
| 2979 | First, ensure that IP forwarding is enabled on both peers. On Linux, enable routing: |
| 2980 | |
| 2981 | echo 1 > /proc/sys/net/ipv4/ip_forward |
| 2982 | |
| 2983 | and enable TUN packet forwarding through the firewall: |
| 2984 | |
| 2985 | iptables -A FORWARD -i tun+ -j ACCEPT |
| 2986 | |
| 2987 | On may: |
| 2988 | |
| 2989 | route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2 |
| 2990 | |
| 2991 | On june: |
| 2992 | |
| 2993 | route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1 |
| 2994 | |
| 2995 | Now any machine on the 10.0.0.0/24 subnet can access any machine on the 10.0.1.0/24 subnet over the secure tunnel (or vice |
| 2996 | versa). |
| 2997 | |
| 2998 | In a production environment, you could put the route command(s) in a script and execute with the --up option. |
| 2999 | |
| 3000 | FIREWALLS |
| 3001 | OpenVPN's usage of a single UDP port makes it fairly firewall-friendly. You should add an entry to your firewall rules to |
| 3002 | allow incoming OpenVPN packets. On Linux 2.4+: |
| 3003 | |
| 3004 | iptables -A INPUT -p udp -s 1.2.3.4 --dport 1194 -j ACCEPT |
| 3005 | |
| 3006 | This will allow incoming packets on UDP port 1194 (OpenVPN's default UDP port) from an OpenVPN peer at 1.2.3.4. |
| 3007 | |
| 3008 | If you are using HMAC-based packet authentication (the default in any of OpenVPN's secure modes), having the firewall filter on |
| 3009 | source address can be considered optional, since HMAC packet authentication is a much more secure method of verifying the |
| 3010 | authenticity of a packet source. In that case: |
| 3011 | |
| 3012 | iptables -A INPUT -p udp --dport 1194 -j ACCEPT |
| 3013 | |
| 3014 | would be adequate and would not render the host inflexible with respect to its peer having a dynamic IP address. |
| 3015 | |
| 3016 | OpenVPN also works well on stateful firewalls. In some cases, you may not need to add any static rules to the firewall list if |
| 3017 | you are using a stateful firewall that knows how to track UDP connections. If you specify --ping n, OpenVPN will be guaranteed |
| 3018 | to send a packet to its peer at least once every n seconds. If n is less than the stateful firewall connection timeout, you |
| 3019 | can maintain an OpenVPN connection indefinitely without explicit firewall rules. |
| 3020 | |
| 3021 | You should also add firewall rules to allow incoming IP traffic on TUN or TAP devices such as: |
| 3022 | |
| 3023 | iptables -A INPUT -i tun+ -j ACCEPT |
| 3024 | |
| 3025 | to allow input packets from tun devices, |
| 3026 | |
| 3027 | iptables -A FORWARD -i tun+ -j ACCEPT |
| 3028 | |
| 3029 | to allow input packets from tun devices to be forwarded to other hosts on the local network, |
| 3030 | |
| 3031 | iptables -A INPUT -i tap+ -j ACCEPT |
| 3032 | |
| 3033 | to allow input packets from tap devices, and |
| 3034 | |
| 3035 | iptables -A FORWARD -i tap+ -j ACCEPT |
| 3036 | |
| 3037 | to allow input packets from tap devices to be forwarded to other hosts on the local network. |
| 3038 | |
| 3039 | These rules are secure if you use packet authentication, since no incoming packets will arrive on a TUN or TAP virtual device |
| 3040 | unless they first pass an HMAC authentication test. |
| 3041 | |
| 3042 | FAQ |
| 3043 | http://openvpn.net/faq.html |
| 3044 | |
| 3045 | HOWTO |
| 3046 | For a more comprehensive guide to setting up OpenVPN in a production setting, see the OpenVPN HOWTO at http://open‐ |
| 3047 | vpn.net/howto.html |
| 3048 | |
| 3049 | PROTOCOL |
| 3050 | For a description of OpenVPN's underlying protocol, see http://openvpn.net/security.html |
| 3051 | |
| 3052 | WEB |
| 3053 | OpenVPN's web site is at http://openvpn.net/ |
| 3054 | |
| 3055 | Go here to download the latest version of OpenVPN, subscribe to the mailing lists, read the mailing list archives, or browse |
| 3056 | the SVN repository. |
| 3057 | |
| 3058 | BUGS |
| 3059 | Report all bugs to the OpenVPN team <info@openvpn.net>. |
| 3060 | |
| 3061 | SEE ALSO |
| 3062 | dhcpcd(8), ifconfig(8), openssl(1), route(8), scp(1) ssh(1) |
| 3063 | |
| 3064 | NOTES |
| 3065 | This product includes software developed by the OpenSSL Project ( http://www.openssl.org/ ) |
| 3066 | |
| 3067 | For more information on the TLS protocol, see http://www.ietf.org/rfc/rfc2246.txt |
| 3068 | |
| 3069 | For more information on the LZO real-time compression library see http://www.oberhumer.com/opensource/lzo/ |
| 3070 | |
| 3071 | COPYRIGHT |
| 3072 | Copyright (C) 2002-2010 OpenVPN Technologies, Inc. This program is free software; you can redistribute it and/or modify it |
| 3073 | under the terms of the GNU General Public License version 2 as published by the Free Software Foundation. |
| 3074 | |
| 3075 | AUTHORS |
| 3076 | James Yonan <jim@yonan.net> |
| 3077 | |
| 3078 | |
| 3079 | |
| 3080 | 17 November 2008 openvpn(8) |
| 3081 | }}} |