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