| 15 | | OpenVPN is an open source VPN daemon by James Yonan. Because OpenVPN |
| 16 | | tries to be a universal VPN tool offering a great deal of flexibility, |
| 17 | | there are a lot of options on this manual page. If you're new to Open‐ |
| 18 | | VPN, you might want to skip ahead to the examples section where you |
| 19 | | will see how to construct simple VPNs on the command line without even |
| 20 | | needing a configuration file. |
| 21 | | |
| 22 | | Also note that there's more documentation and examples on the OpenVPN |
| 23 | | web site: http://openvpn.net/ |
| 24 | | |
| 25 | | And if you would like to see a shorter version of this manual, see the |
| 26 | | openvpn usage message which can be obtained by running openvpn without |
| 27 | | any parameters. |
| | 15 | OpenVPN is an open source VPN daemon by James Yonan. Because OpenVPN |
| | 16 | tries to be a universal VPN tool offering a great deal of flexibility, |
| | 17 | there are a lot of options on this manual page. If you're new to OpenVPN, |
| | 18 | you might want to skip ahead to the examples section where you will see |
| | 19 | how to construct simple VPNs on the command line without even needing a |
| | 20 | configuration file. |
| | 21 | |
| | 22 | Also note that there's more documentation and examples on the OpenVPN web |
| | 23 | site: http://openvpn.net/ |
| | 24 | |
| | 25 | And if you would like to see a shorter version of this manual, see the |
| | 26 | openvpn usage message which can be obtained by running openvpn without any |
| | 27 | parameters. |
| 30 | | OpenVPN is a robust and highly flexible VPN daemon. OpenVPN supports |
| 31 | | SSL/TLS security, ethernet bridging, TCP or UDP tunnel transport |
| 32 | | through proxies or NAT, support for dynamic IP addresses and DHCP, |
| 33 | | scalability to hundreds or thousands of users, and portability to most |
| 34 | | major OS platforms. |
| 35 | | |
| 36 | | OpenVPN is tightly bound to the OpenSSL library, and derives much of |
| 37 | | its crypto capabilities from it. |
| 38 | | |
| 39 | | OpenVPN supports conventional encryption using a pre-shared secret key |
| 40 | | (Static Key mode) or public key security (SSL/TLS mode) using client & |
| 41 | | server certificates. OpenVPN also supports non-encrypted TCP/UDP tun‐ |
| 42 | | nels. |
| 43 | | |
| 44 | | OpenVPN is designed to work with the TUN/TAP virtual networking inter‐ |
| 45 | | face that exists on most platforms. |
| 46 | | |
| 47 | | Overall, OpenVPN aims to offer many of the key features of IPSec but |
| 48 | | with a relatively lightweight footprint. |
| | 30 | OpenVPN is a robust and highly flexible VPN daemon. OpenVPN supports |
| | 31 | SSL/TLS security, ethernet bridging, TCP or UDP tunnel transport through |
| | 32 | proxies or NAT, support for dynamic IP addresses and DHCP, scalability to |
| | 33 | hundreds or thousands of users, and portability to most major OS plat‐ |
| | 34 | forms. |
| | 35 | |
| | 36 | OpenVPN is tightly bound to the OpenSSL library, and derives much of its |
| | 37 | crypto capabilities from it. |
| | 38 | |
| | 39 | OpenVPN supports conventional encryption using a pre-shared secret key |
| | 40 | (Static Key mode) or public key security (SSL/TLS mode) using client & |
| | 41 | server certificates. OpenVPN also supports non-encrypted TCP/UDP tunnels. |
| | 42 | |
| | 43 | OpenVPN is designed to work with the TUN/TAP virtual networking interface |
| | 44 | that exists on most platforms. |
| | 45 | |
| | 46 | Overall, OpenVPN aims to offer many of the key features of IPSec but with |
| | 47 | a relatively lightweight footprint. |
| 126 | | Remote host name or IP address. On the client, multiple |
| 127 | | --remote options may be specified for redundancy, each referring |
| 128 | | to a different OpenVPN server. Specifying multiple --remote |
| 129 | | options for this purpose is a special case of the more general |
| 130 | | connection-profile feature. See the <connection> documentation |
| 131 | | below. |
| 132 | | |
| 133 | | The OpenVPN client will try to connect to a server at host:port |
| 134 | | in the order specified by the list of --remote options. |
| 135 | | |
| 136 | | proto indicates the protocol to use when connecting with the |
| | 123 | Remote host name or IP address. On the client, multiple --remote |
| | 124 | options may be specified for redundancy, each referring to a dif‐ |
| | 125 | ferent OpenVPN server. Specifying multiple --remote options for |
| | 126 | this purpose is a special case of the more general connection-pro‐ |
| | 127 | file feature. See the <connection> documentation below. |
| | 128 | |
| | 129 | The OpenVPN client will try to connect to a server at host:port in |
| | 130 | the order specified by the list of --remote options. |
| | 131 | |
| | 132 | proto indicates the protocol to use when connecting with the |
| 146 | | Note the following corner case: If you use multiple --remote |
| 147 | | options, AND you are dropping root privileges on the client with |
| 148 | | --user and/or --group, AND the client is running a non-Windows |
| 149 | | OS, if the client needs to switch to a different server, and |
| 150 | | that server pushes back different TUN/TAP or route settings, the |
| 151 | | client may lack the necessary privileges to close and reopen the |
| 152 | | TUN/TAP interface. This could cause the client to exit with a |
| 153 | | fatal error. |
| 154 | | |
| 155 | | If --remote is unspecified, OpenVPN will listen for packets from |
| 156 | | any IP address, but will not act on those packets unless they |
| 157 | | pass all authentication tests. This requirement for authentica‐ |
| 158 | | tion is binding on all potential peers, even those from known |
| 159 | | and supposedly trusted IP addresses (it is very easy to forge a |
| 160 | | source IP address on a UDP packet). |
| 161 | | |
| 162 | | When used in TCP mode, --remote will act as a filter, rejecting |
| | 142 | Note the following corner case: If you use multiple --remote |
| | 143 | options, AND you are dropping root privileges on the client with |
| | 144 | --user and/or --group, AND the client is running a non-Windows OS, |
| | 145 | if the client needs to switch to a different server, and that |
| | 146 | server pushes back different TUN/TAP or route settings, the client |
| | 147 | may lack the necessary privileges to close and reopen the TUN/TAP |
| | 148 | interface. This could cause the client to exit with a fatal error. |
| | 149 | |
| | 150 | If --remote is unspecified, OpenVPN will listen for packets from |
| | 151 | any IP address, but will not act on those packets unless they pass |
| | 152 | all authentication tests. This requirement for authentication is |
| | 153 | binding on all potential peers, even those from known and suppos‐ |
| | 154 | edly trusted IP addresses (it is very easy to forge a source IP |
| | 155 | address on a UDP packet). |
| | 156 | |
| | 157 | When used in TCP mode, --remote will act as a filter, rejecting |
| 218 | | First we try to connect to a server at 198.19.34.56:1194 using |
| 219 | | UDP. If that fails, we then try to connect to 198.19.34.56:443 |
| 220 | | using TCP. If that also fails, then try connecting through an |
| 221 | | HTTP proxy at 192.168.0.8:8080 to 198.19.34.56:443 using TCP. |
| 222 | | Finally, try to connect through the same proxy to a server at |
| 223 | | 198.19.36.99:443 using TCP. |
| 224 | | |
| 225 | | The following OpenVPN options may be used inside of a <connec‐ |
| 226 | | tion> block: |
| 227 | | |
| 228 | | bind, connect-retry, connect-retry-max, connect-timeout, float, |
| 229 | | http-proxy, http-proxy-option, http-proxy-retry, http-proxy- |
| 230 | | timeout, local, lport, nobind, port, proto, remote, rport, |
| 231 | | socks-proxy, and socks-proxy-retry. |
| 232 | | |
| 233 | | A defaulting mechanism exists for specifying options to apply to |
| 234 | | all <connection> profiles. If any of the above options (with |
| 235 | | the exception of remote ) appear outside of a <connection> |
| 236 | | block, but in a configuration file which has one or more <con‐ |
| 237 | | nection> blocks, the option setting will be used as a default |
| 238 | | for <connection> blocks which follow it in the configuration |
| 239 | | |
| 240 | | |
| 241 | | For example, suppose the nobind option were placed in the sample |
| 242 | | configuration file above, near the top of the file, before the |
| 243 | | first <connection> block. The effect would be as if nobind were |
| | 213 | First we try to connect to a server at 198.19.34.56:1194 using UDP. |
| | 214 | If that fails, we then try to connect to 198.19.34.56:443 using |
| | 215 | TCP. If that also fails, then try connecting through an HTTP proxy |
| | 216 | at 192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to |
| | 217 | connect through the same proxy to a server at 198.19.36.99:443 |
| | 218 | using TCP. |
| | 219 | |
| | 220 | The following OpenVPN options may be used inside of a <connection> |
| | 221 | block: |
| | 222 | |
| | 223 | bind, connect-retry, connect-retry-max, connect-timeout, explicit- |
| | 224 | exit-notify, float, fragment, http-proxy, http-proxy-option, http- |
| | 225 | proxy-retry, http-proxy-timeout, link-mtu, local, lport, mssfix, |
| | 226 | mtu-disc, nobind, port, proto, remote, rport, socks-proxy, socks- |
| | 227 | proxy-retry, tun-mtu and tun-mtu-extra. |
| | 228 | |
| | 229 | A defaulting mechanism exists for specifying options to apply to |
| | 230 | all <connection> profiles. If any of the above options (with the |
| | 231 | exception of remote ) appear outside of a <connection> block, but |
| | 232 | in a configuration file which has one or more <connection> blocks, |
| | 233 | the option setting will be used as a default for <connection> |
| | 234 | blocks which follow it in the configuration file. |
| | 235 | |
| | 236 | For example, suppose the nobind option were placed in the sample |
| | 237 | configuration file above, near the top of the file, before the |
| | 238 | first <connection> block. The effect would be as if nobind were |
| 261 | | For UDP operation, --proto udp should be specified on both |
| 262 | | peers. |
| 263 | | |
| 264 | | For TCP operation, one peer must use --proto tcp-server and the |
| 265 | | other must use --proto tcp-client. A peer started with tcp- |
| 266 | | server will wait indefinitely for an incoming connection. A |
| 267 | | peer started with tcp-client will attempt to connect, and if |
| 268 | | that fails, will sleep for 5 seconds (adjustable via the --con‐ |
| 269 | | nect-retry option) and try again infinite or up to N retries |
| 270 | | (adjustable via the --connect-retry-max option). Both TCP |
| 271 | | client and server will simulate a SIGUSR1 restart signal if |
| 272 | | either side resets the connection. |
| 273 | | |
| 274 | | OpenVPN is designed to operate optimally over UDP, but TCP capa‐ |
| 275 | | bility is provided for situations where UDP cannot be used. In |
| 276 | | comparison with UDP, TCP will usually be somewhat less efficient |
| 277 | | and less robust when used over unreliable or congested networks. |
| 278 | | |
| 279 | | This article outlines some of problems with tunneling IP over |
| 280 | | TCP: |
| | 256 | For UDP operation, --proto udp should be specified on both peers. |
| | 257 | |
| | 258 | For TCP operation, one peer must use --proto tcp-server and the |
| | 259 | other must use --proto tcp-client. A peer started with tcp-server |
| | 260 | will wait indefinitely for an incoming connection. A peer started |
| | 261 | with tcp-client will attempt to connect, and if that fails, will |
| | 262 | sleep for 5 seconds (adjustable via the --connect-retry option) and |
| | 263 | try again infinite or up to N retries (adjustable via the --con‐ |
| | 264 | nect-retry-max option). Both TCP client and server will simulate a |
| | 265 | SIGUSR1 restart signal if either side resets the connection. |
| | 266 | |
| | 267 | OpenVPN is designed to operate optimally over UDP, but TCP capabil‐ |
| | 268 | ity is provided for situations where UDP cannot be used. In com‐ |
| | 269 | parison with UDP, TCP will usually be somewhat less efficient and |
| | 270 | less robust when used over unreliable or congested networks. |
| | 271 | |
| | 272 | This article outlines some of problems with tunneling IP over TCP: |
| 313 | | HTTP Digest authentication is supported as well, but only via |
| 314 | | the auto or auto-nct flags (below). |
| 315 | | |
| 316 | | The auto flag causes OpenVPN to automatically determine the |
| 317 | | auth-method and query stdin or the management interface for |
| 318 | | username/password credentials, if required. This flag exists on |
| 319 | | OpenVPN 2.1 or higher. |
| 320 | | |
| 321 | | The auto-nct flag (no clear-text auth) instructs OpenVPN to |
| 322 | | automatically determine the authentication method, but to reject |
| 323 | | weak authentication protocols such as HTTP Basic Authentication. |
| | 305 | HTTP Digest authentication is supported as well, but only via the |
| | 306 | auto or auto-nct flags (below). |
| | 307 | |
| | 308 | The auto flag causes OpenVPN to automatically determine the auth- |
| | 309 | method and query stdin or the management interface for user‐ |
| | 310 | name/password credentials, if required. This flag exists on Open‐ |
| | 311 | VPN 2.1 or higher. |
| | 312 | |
| | 313 | The auto-nct flag (no clear-text auth) instructs OpenVPN to auto‐ |
| | 314 | matically determine the authentication method, but to reject weak |
| | 315 | authentication protocols such as HTTP Basic Authentication. |
| 359 | | Allow remote peer to change its IP address and/or port number, |
| 360 | | such as due to DHCP (this is the default if --remote is not |
| 361 | | used). --float when specified with --remote allows an OpenVPN |
| 362 | | session to initially connect to a peer at a known address, how‐ |
| 363 | | ever if packets arrive from a new address and pass all authenti‐ |
| 364 | | cation tests, the new address will take control of the session. |
| 365 | | This is useful when you are connecting to a peer which holds a |
| 366 | | dynamic address such as a dial-in user or DHCP client. |
| 367 | | |
| 368 | | Essentially, --float tells OpenVPN to accept authenticated pack‐ |
| 369 | | ets from any address, not only the address which was specified |
| 370 | | in the --remote option. |
| | 350 | Allow remote peer to change its IP address and/or port number, such |
| | 351 | as due to DHCP (this is the default if --remote is not used). |
| | 352 | --float when specified with --remote allows an OpenVPN session to |
| | 353 | initially connect to a peer at a known address, however if packets |
| | 354 | arrive from a new address and pass all authentication tests, the |
| | 355 | new address will take control of the session. This is useful when |
| | 356 | you are connecting to a peer which holds a dynamic address such as |
| | 357 | a dial-in user or DHCP client. |
| | 358 | |
| | 359 | Essentially, --float tells OpenVPN to accept authenticated packets |
| | 360 | from any address, not only the address which was specified in the |
| | 361 | --remote option. |
| 392 | | If you are running in a dynamic IP address environment where the |
| 393 | | IP addresses of either peer could change without notice, you can |
| 394 | | use this script, for example, to edit the /etc/hosts file with |
| 395 | | the current address of the peer. The script will be run every |
| 396 | | time the remote peer changes its IP address. |
| 397 | | |
| 398 | | Similarly if our IP address changes due to DHCP, we should con‐ |
| 399 | | figure our IP address change script (see man page for dhcpcd(8) |
| 400 | | ) to deliver a SIGHUP or SIGUSR1 signal to OpenVPN. OpenVPN |
| 401 | | will then reestablish a connection with its most recently |
| 402 | | authenticated peer on its new IP address. |
| | 383 | If you are running in a dynamic IP address environment where the IP |
| | 384 | addresses of either peer could change without notice, you can use |
| | 385 | this script, for example, to edit the /etc/hosts file with the cur‐ |
| | 386 | rent address of the peer. The script will be run every time the |
| | 387 | remote peer changes its IP address. |
| | 388 | |
| | 389 | Similarly if our IP address changes due to DHCP, we should config‐ |
| | 390 | ure our IP address change script (see man page for dhcpcd(8) ) to |
| | 391 | deliver a SIGHUP or SIGUSR1 signal to OpenVPN. OpenVPN will then |
| | 392 | reestablish a connection with its most recently authenticated peer |
| | 393 | on its new IP address. |
| 458 | | net30 -- Use a point-to-point topology, by allocating one /30 |
| 459 | | subnet per client. This is designed to allow point-to-point |
| 460 | | semantics when some or all of the connecting clients might be |
| 461 | | Windows systems. This is the default on OpenVPN 2.0. |
| 462 | | |
| 463 | | p2p -- Use a point-to-point topology where the remote endpoint |
| 464 | | of the client's tun interface always points to the local end‐ |
| 465 | | point of the server's tun interface. This mode allocates a sin‐ |
| 466 | | gle IP address per connecting client. Only use when none of the |
| 467 | | connecting clients are Windows systems. This mode is function‐ |
| 468 | | ally equivalent to the --ifconfig-pool-linear directive which is |
| 469 | | available in OpenVPN 2.0 and is now deprecated. |
| 470 | | |
| 471 | | subnet -- Use a subnet rather than a point-to-point topology by |
| 472 | | configuring the tun interface with a local IP address and subnet |
| 473 | | mask, similar to the topology used in --dev tap and ethernet |
| 474 | | bridging mode. This mode allocates a single IP address per con‐ |
| 475 | | necting client and works on Windows as well. Only available |
| 476 | | when server and clients are OpenVPN 2.1 or higher, or OpenVPN |
| 477 | | 2.0.x which has been manually patched with the --topology direc‐ |
| 478 | | tive code. When used on Windows, requires version 8.2 or higher |
| 479 | | of the TAP-Win32 driver. When used on *nix, requires that the |
| 480 | | tun driver supports an ifconfig(8) command which sets a subnet |
| 481 | | instead of a remote endpoint IP address. |
| | 449 | net30 -- Use a point-to-point topology, by allocating one /30 sub‐ |
| | 450 | net per client. This is designed to allow point-to-point semantics |
| | 451 | when some or all of the connecting clients might be Windows sys‐ |
| | 452 | tems. This is the default on OpenVPN 2.0. |
| | 453 | |
| | 454 | p2p -- Use a point-to-point topology where the remote endpoint of |
| | 455 | the client's tun interface always points to the local endpoint of |
| | 456 | the server's tun interface. This mode allocates a single IP |
| | 457 | address per connecting client. Only use when none of the connect‐ |
| | 458 | ing clients are Windows systems. This mode is functionally equiva‐ |
| | 459 | lent to the --ifconfig-pool-linear directive which is available in |
| | 460 | OpenVPN 2.0 and is now deprecated. |
| | 461 | |
| | 462 | subnet -- Use a subnet rather than a point-to-point topology by |
| | 463 | configuring the tun interface with a local IP address and subnet |
| | 464 | mask, similar to the topology used in --dev tap and ethernet bridg‐ |
| | 465 | ing mode. This mode allocates a single IP address per connecting |
| | 466 | client and works on Windows as well. Only available when server |
| | 467 | and clients are OpenVPN 2.1 or higher, or OpenVPN 2.0.x which has |
| | 468 | been manually patched with the --topology directive code. When |
| | 469 | used on Windows, requires version 8.2 or higher of the TAP-Win32 |
| | 470 | driver. When used on *nix, requires that the tun driver supports |
| | 471 | an ifconfig(8) command which sets a subnet instead of a remote end‐ |
| | 472 | point IP address. |
| 494 | | Explicitly set the device node rather than using /dev/net/tun, |
| 495 | | /dev/tun, /dev/tap, etc. If OpenVPN cannot figure out whether |
| 496 | | node is a TUN or TAP device based on the name, you should also |
| 497 | | specify --dev-type tun or --dev-type tap. |
| 498 | | |
| 499 | | On Windows systems, select the TAP-Win32 adapter which is named |
| 500 | | node in the Network Connections Control Panel or the raw GUID of |
| 501 | | the adapter enclosed by braces. The --show-adapters option |
| 502 | | under Windows can also be used to enumerate all available TAP- |
| 503 | | Win32 adapters and will show both the network connections con‐ |
| 504 | | trol panel name and the GUID for each TAP-Win32 adapter. |
| | 485 | Explicitly set the device node rather than using /dev/net/tun, |
| | 486 | /dev/tun, /dev/tap, etc. If OpenVPN cannot figure out whether node |
| | 487 | is a TUN or TAP device based on the name, you should also specify |
| | 488 | --dev-type tun or --dev-type tap. |
| | 489 | |
| | 490 | On Windows systems, select the TAP-Win32 adapter which is named |
| | 491 | node in the Network Connections Control Panel or the raw GUID of |
| | 492 | the adapter enclosed by braces. The --show-adapters option under |
| | 493 | Windows can also be used to enumerate all available TAP-Win32 |
| | 494 | adapters and will show both the network connections control panel |
| | 495 | name and the GUID for each TAP-Win32 adapter. |
| 516 | | Set TUN/TAP adapter parameters. l is the IP address of the |
| 517 | | local VPN endpoint. For TUN devices, rn is the IP address of |
| 518 | | the remote VPN endpoint. For TAP devices, rn is the subnet mask |
| 519 | | of the virtual ethernet segment which is being created or con‐ |
| 520 | | nected to. |
| 521 | | |
| 522 | | For TUN devices, which facilitate virtual point-to-point IP con‐ |
| 523 | | nections, the proper usage of --ifconfig is to use two private |
| 524 | | IP addresses which are not a member of any existing subnet which |
| 525 | | is in use. The IP addresses may be consecutive and should have |
| 526 | | their order reversed on the remote peer. After the VPN is |
| 527 | | established, by pinging rn, you will be pinging across the VPN. |
| 528 | | |
| 529 | | For TAP devices, which provide the ability to create virtual |
| 530 | | ethernet segments, --ifconfig is used to set an IP address and |
| 531 | | subnet mask just as a physical ethernet adapter would be simi‐ |
| 532 | | larly configured. If you are attempting to connect to a remote |
| 533 | | ethernet bridge, the IP address and subnet should be set to val‐ |
| 534 | | ues which would be valid on the the bridged ethernet segment |
| 535 | | (note also that DHCP can be used for the same purpose). |
| 536 | | |
| 537 | | This option, while primarily a proxy for the ifconfig(8) com‐ |
| 538 | | mand, is designed to simplify TUN/TAP tunnel configuration by |
| 539 | | providing a standard interface to the different ifconfig imple‐ |
| 540 | | mentations on different platforms. |
| 541 | | |
| 542 | | --ifconfig parameters which are IP addresses can also be speci‐ |
| 543 | | fied as a DNS or /etc/hosts file resolvable name. |
| 544 | | |
| 545 | | For TAP devices, --ifconfig should not be used if the TAP inter‐ |
| 546 | | face will be getting an IP address lease from a DHCP server. |
| | 507 | Set TUN/TAP adapter parameters. l is the IP address of the local |
| | 508 | VPN endpoint. For TUN devices, rn is the IP address of the remote |
| | 509 | VPN endpoint. For TAP devices, rn is the subnet mask of the vir‐ |
| | 510 | tual ethernet segment which is being created or connected to. |
| | 511 | |
| | 512 | For TUN devices, which facilitate virtual point-to-point IP connec‐ |
| | 513 | tions, the proper usage of --ifconfig is to use two private IP |
| | 514 | addresses which are not a member of any existing subnet which is in |
| | 515 | use. The IP addresses may be consecutive and should have their |
| | 516 | order reversed on the remote peer. After the VPN is established, |
| | 517 | by pinging rn, you will be pinging across the VPN. |
| | 518 | |
| | 519 | For TAP devices, which provide the ability to create virtual ether‐ |
| | 520 | net segments, --ifconfig is used to set an IP address and subnet |
| | 521 | mask just as a physical ethernet adapter would be similarly config‐ |
| | 522 | ured. If you are attempting to connect to a remote ethernet |
| | 523 | bridge, the IP address and subnet should be set to values which |
| | 524 | would be valid on the the bridged ethernet segment (note also that |
| | 525 | DHCP can be used for the same purpose). |
| | 526 | |
| | 527 | This option, while primarily a proxy for the ifconfig(8) command, |
| | 528 | is designed to simplify TUN/TAP tunnel configuration by providing a |
| | 529 | standard interface to the different ifconfig implementations on |
| | 530 | different platforms. |
| | 531 | |
| | 532 | --ifconfig parameters which are IP addresses can also be specified |
| | 533 | as a DNS or /etc/hosts file resolvable name. |
| | 534 | |
| | 535 | For TAP devices, --ifconfig should not be used if the TAP interface |
| | 536 | will be getting an IP address lease from a DHCP server. |
| 553 | | Don't output an options consistency check warning if the |
| 554 | | --ifconfig option on this side of the connection doesn't match |
| 555 | | the remote side. This is useful when you want to retain the |
| 556 | | overall benefits of the options consistency check (also see |
| 557 | | --disable-occ option) while only disabling the ifconfig compo‐ |
| 558 | | nent of the check. |
| 559 | | |
| 560 | | For example, if you have a configuration where the local host |
| 561 | | uses --ifconfig but the remote host does not, use --ifconfig- |
| 562 | | nowarn on the local host. |
| 563 | | |
| 564 | | This option will also silence warnings about potential address |
| 565 | | conflicts which occasionally annoy more experienced users by |
| 566 | | triggering "false positive" warnings. |
| | 543 | Don't output an options consistency check warning if the --ifconfig |
| | 544 | option on this side of the connection doesn't match the remote |
| | 545 | side. This is useful when you want to retain the overall benefits |
| | 546 | of the options consistency check (also see --disable-occ option) |
| | 547 | while only disabling the ifconfig component of the check. |
| | 548 | |
| | 549 | For example, if you have a configuration where the local host uses |
| | 550 | --ifconfig but the remote host does not, use --ifconfig-nowarn on |
| | 551 | the local host. |
| | 552 | |
| | 553 | This option will also silence warnings about potential address con‐ |
| | 554 | flicts which occasionally annoy more experienced users by trigger‐ |
| | 555 | ing "false positive" warnings. |
| 584 | | The default can be specified by leaving an option blank or set‐ |
| 585 | | ting it to "default". |
| 586 | | |
| 587 | | The network and gateway parameters can also be specified as a |
| 588 | | DNS or /etc/hosts file resolvable name, or as one of three spe‐ |
| 589 | | cial keywords: |
| 590 | | |
| 591 | | vpn_gateway -- The remote VPN endpoint address (derived either |
| 592 | | from --route-gateway or the second parameter to --ifconfig when |
| 593 | | --dev tun is specified). |
| 594 | | |
| 595 | | net_gateway -- The pre-existing IP default gateway, read from |
| 596 | | the routing table (not supported on all OSes). |
| 597 | | |
| 598 | | remote_host -- The --remote address if OpenVPN is being run in |
| | 573 | The default can be specified by leaving an option blank or setting |
| | 574 | it to "default". |
| | 575 | |
| | 576 | The network and gateway parameters can also be specified as a DNS |
| | 577 | or /etc/hosts file resolvable name, or as one of three special key‐ |
| | 578 | words: |
| | 579 | |
| | 580 | vpn_gateway -- The remote VPN endpoint address (derived either from |
| | 581 | --route-gateway or the second parameter to --ifconfig when --dev |
| | 582 | tun is specified). |
| | 583 | |
| | 584 | net_gateway -- The pre-existing IP default gateway, read from the |
| | 585 | routing table (not supported on all OSes). |
| | 586 | |
| | 587 | remote_host -- The --remote address if OpenVPN is being run in |
| 617 | | Delay n seconds (default=0) after connection establishment, |
| 618 | | before adding routes. If n is 0, routes will be added immedi‐ |
| 619 | | ately upon connection establishment. If --route-delay is omit‐ |
| 620 | | ted, routes will be added immediately after TUN/TAP device open |
| 621 | | and --up script execution, before any --user or --group privi‐ |
| 622 | | lege downgrade (or --chroot execution.) |
| 623 | | |
| 624 | | This option is designed to be useful in scenarios where DHCP is |
| 625 | | used to set tap adapter addresses. The delay will give the DHCP |
| | 605 | Delay n seconds (default=0) after connection establishment, before |
| | 606 | adding routes. If n is 0, routes will be added immediately upon |
| | 607 | connection establishment. If --route-delay is omitted, routes will |
| | 608 | be added immediately after TUN/TAP device open and --up script exe‐ |
| | 609 | cution, before any --user or --group privilege downgrade (or |
| | 610 | --chroot execution.) |
| | 611 | |
| | 612 | This option is designed to be useful in scenarios where DHCP is |
| | 613 | used to set tap adapter addresses. The delay will give the DHCP |
| 716 | | autolocal -- Try to automatically determine whether to enable |
| 717 | | local flag above. |
| 718 | | |
| 719 | | def1 -- Use this flag to override the default gateway by using |
| 720 | | 0.0.0.0/1 and 128.0.0.0/1 rather than 0.0.0.0/0. This has the |
| 721 | | benefit of overriding but not wiping out the original default |
| 722 | | gateway. |
| 723 | | |
| 724 | | bypass-dhcp -- Add a direct route to the DHCP server (if it is |
| 725 | | non-local) which bypasses the tunnel (Available on Windows |
| 726 | | clients, may not be available on non-Windows clients). |
| 727 | | |
| 728 | | bypass-dns -- Add a direct route to the DNS server(s) (if they |
| 729 | | are non-local) which bypasses the tunnel (Available on Windows |
| 730 | | clients, may not be available on non-Windows clients). |
| 731 | | |
| 732 | | block-local -- Block access to local LAN when the tunnel is |
| 733 | | active, except for the LAN gateway itself. This is accomplished |
| 734 | | by routing the local LAN (except for the LAN gateway address) |
| 735 | | into the tunnel. |
| | 702 | autolocal -- Try to automatically determine whether to enable local |
| | 703 | flag above. |
| | 704 | |
| | 705 | def1 -- Use this flag to override the default gateway by using |
| | 706 | 0.0.0.0/1 and 128.0.0.0/1 rather than 0.0.0.0/0. This has the ben‐ |
| | 707 | efit of overriding but not wiping out the original default gateway. |
| | 708 | |
| | 709 | bypass-dhcp -- Add a direct route to the DHCP server (if it is non- |
| | 710 | local) which bypasses the tunnel (Available on Windows clients, may |
| | 711 | not be available on non-Windows clients). |
| | 712 | |
| | 713 | bypass-dns -- Add a direct route to the DNS server(s) (if they are |
| | 714 | non-local) which bypasses the tunnel (Available on Windows clients, |
| | 715 | may not be available on non-Windows clients). |
| | 716 | |
| | 717 | block-local -- Block access to local LAN when the tunnel is active, |
| | 718 | except for the LAN gateway itself. This is accomplished by routing |
| | 719 | the local LAN (except for the LAN gateway address) into the tunnel. |
| 805 | | It should also be noted that this option is not meant to replace |
| 806 | | UDP fragmentation at the IP stack level. It is only meant as a |
| 807 | | last resort when path MTU discovery is broken. Using this |
| 808 | | option is less efficient than fixing path MTU discovery for your |
| 809 | | IP link and using native IP fragmentation instead. |
| 810 | | |
| 811 | | Having said that, there are circumstances where using OpenVPN's |
| 812 | | internal fragmentation capability may be your only option, such |
| 813 | | as tunneling a UDP multicast stream which requires fragmenta‐ |
| 814 | | tion. |
| | 787 | It should also be noted that this option is not meant to replace |
| | 788 | UDP fragmentation at the IP stack level. It is only meant as a |
| | 789 | last resort when path MTU discovery is broken. Using this option |
| | 790 | is less efficient than fixing path MTU discovery for your IP link |
| | 791 | and using native IP fragmentation instead. |
| | 792 | |
| | 793 | Having said that, there are circumstances where using OpenVPN's |
| | 794 | internal fragmentation capability may be your only option, such as |
| | 795 | tunneling a UDP multicast stream which requires fragmentation. |
| 817 | | Announce to TCP sessions running over the tunnel that they |
| 818 | | should limit their send packet sizes such that after OpenVPN has |
| 819 | | encapsulated them, the resulting UDP packet size that OpenVPN |
| 820 | | sends to its peer will not exceed max bytes. The default value |
| 821 | | is 1450. |
| 822 | | |
| 823 | | The max parameter is interpreted in the same way as the --link- |
| 824 | | mtu parameter, i.e. the UDP packet size after encapsulation |
| 825 | | overhead has been added in, but not including the UDP header |
| 826 | | itself. |
| 827 | | |
| 828 | | The --mssfix option only makes sense when you are using the UDP |
| 829 | | protocol for OpenVPN peer-to-peer communication, i.e. --proto |
| 830 | | udp. |
| 831 | | |
| 832 | | --mssfix and --fragment can be ideally used together, where |
| 833 | | --mssfix will try to keep TCP from needing packet fragmentation |
| 834 | | in the first place, and if big packets come through anyhow (from |
| 835 | | protocols other than TCP), --fragment will internally fragment |
| 836 | | them. |
| 837 | | |
| 838 | | Both --fragment and --mssfix are designed to work around cases |
| 839 | | where Path MTU discovery is broken on the network path between |
| | 798 | Announce to TCP sessions running over the tunnel that they should |
| | 799 | limit their send packet sizes such that after OpenVPN has encapsu‐ |
| | 800 | lated them, the resulting UDP packet size that OpenVPN sends to its |
| | 801 | peer will not exceed max bytes. The default value is 1450. |
| | 802 | |
| | 803 | The max parameter is interpreted in the same way as the --link-mtu |
| | 804 | parameter, i.e. the UDP packet size after encapsulation overhead |
| | 805 | has been added in, but not including the UDP header itself. |
| | 806 | |
| | 807 | The --mssfix option only makes sense when you are using the UDP |
| | 808 | protocol for OpenVPN peer-to-peer communication, i.e. --proto udp. |
| | 809 | |
| | 810 | --mssfix and --fragment can be ideally used together, where --mss‐ |
| | 811 | fix will try to keep TCP from needing packet fragmentation in the |
| | 812 | first place, and if big packets come through anyhow (from protocols |
| | 813 | other than TCP), --fragment will internally fragment them. |
| | 814 | |
| | 815 | Both --fragment and --mssfix are designed to work around cases |
| | 816 | where Path MTU discovery is broken on the network path between |
| 869 | | Apply the given flags to the OpenVPN transport socket. Cur‐ |
| 870 | | rently, only TCP_NODELAY is supported. |
| 871 | | |
| 872 | | The TCP_NODELAY socket flag is useful in TCP mode, and causes |
| 873 | | the kernel to send tunnel packets immediately over the TCP con‐ |
| 874 | | nection without trying to group several smaller packets into a |
| 875 | | larger packet. This can result in a considerably improvement in |
| 876 | | latency. |
| 877 | | |
| 878 | | This option is pushable from server to client, and should be |
| 879 | | used on both client and server for maximum effect. |
| | 846 | Apply the given flags to the OpenVPN transport socket. Currently, |
| | 847 | only TCP_NODELAY is supported. |
| | 848 | |
| | 849 | The TCP_NODELAY socket flag is useful in TCP mode, and causes the |
| | 850 | kernel to send tunnel packets immediately over the TCP connection |
| | 851 | without trying to group several smaller packets into a larger |
| | 852 | packet. This can result in a considerably improvement in latency. |
| | 853 | |
| | 854 | This option is pushable from server to client, and should be used |
| | 855 | on both client and server for maximum effect. |
| 890 | | OpenVPN uses the following algorithm to implement traffic shap‐ |
| 891 | | ing: Given a shaper rate of n bytes per second, after a datagram |
| 892 | | write of b bytes is queued on the TCP/UDP port, wait a minimum |
| 893 | | of (b / n) seconds before queuing the next write. |
| 894 | | |
| 895 | | It should be noted that OpenVPN supports multiple tunnels |
| 896 | | between the same two peers, allowing you to construct full-speed |
| 897 | | and reduced bandwidth tunnels at the same time, routing low-pri‐ |
| 898 | | ority data such as off-site backups over the reduced bandwidth |
| 899 | | tunnel, and other data over the full-speed tunnel. |
| 900 | | |
| 901 | | Also note that for low bandwidth tunnels (under 1000 bytes per |
| 902 | | second), you should probably use lower MTU values as well (see |
| 903 | | above), otherwise the packet latency will grow so large as to |
| 904 | | trigger timeouts in the TLS layer and TCP connections running |
| 905 | | over the tunnel. |
| | 866 | OpenVPN uses the following algorithm to implement traffic shaping: |
| | 867 | Given a shaper rate of n bytes per second, after a datagram write |
| | 868 | of b bytes is queued on the TCP/UDP port, wait a minimum of (b / n) |
| | 869 | seconds before queuing the next write. |
| | 870 | |
| | 871 | It should be noted that OpenVPN supports multiple tunnels between |
| | 872 | the same two peers, allowing you to construct full-speed and |
| | 873 | reduced bandwidth tunnels at the same time, routing low-priority |
| | 874 | data such as off-site backups over the reduced bandwidth tunnel, |
| | 875 | and other data over the full-speed tunnel. |
| | 876 | |
| | 877 | Also note that for low bandwidth tunnels (under 1000 bytes per sec‐ |
| | 878 | ond), you should probably use lower MTU values as well (see above), |
| | 879 | otherwise the packet latency will grow so large as to trigger time‐ |
| | 880 | outs in the TLS layer and TCP connections running over the tunnel. |
| 910 | | Causes OpenVPN to exit after n seconds of inactivity on the |
| 911 | | TUN/TAP device. The time length of inactivity is measured since |
| 912 | | the last incoming or outgoing tunnel packet. The default value |
| 913 | | is 0 seconds, which disables this feature. |
| 914 | | |
| 915 | | If the optional bytes parameter is included, exit if less than |
| 916 | | bytes of combined in/out traffic are produced on the tun/tap |
| 917 | | device in n seconds. |
| 918 | | |
| 919 | | In any case, OpenVPN's internal ping packets (which are just |
| 920 | | keepalives) and TLS control packets are not considered "activ‐ |
| 921 | | ity", nor are they counted as traffic, as they are used inter‐ |
| 922 | | nally by OpenVPN and are not an indication of actual user activ‐ |
| 923 | | ity. |
| | 885 | Causes OpenVPN to exit after n seconds of inactivity on the TUN/TAP |
| | 886 | device. The time length of inactivity is measured since the last |
| | 887 | incoming or outgoing tunnel packet. The default value is 0 sec‐ |
| | 888 | onds, which disables this feature. |
| | 889 | |
| | 890 | If the optional bytes parameter is included, exit if less than |
| | 891 | bytes of combined in/out traffic are produced on the tun/tap device |
| | 892 | in n seconds. |
| | 893 | |
| | 894 | In any case, OpenVPN's internal ping packets (which are just |
| | 895 | keepalives) and TLS control packets are not considered "activity", |
| | 896 | nor are they counted as traffic, as they are used internally by |
| | 897 | OpenVPN and are not an indication of actual user activity. |
| 958 | | Similar to --ping-exit, but trigger a SIGUSR1 restart after n |
| 959 | | seconds pass without reception of a ping or other packet from |
| 960 | | remote. |
| 961 | | |
| 962 | | This option is useful in cases where the remote peer has a |
| 963 | | dynamic IP address and a low-TTL DNS name is used to track the |
| 964 | | IP address using a service such as http://dyndns.org/ + a |
| 965 | | dynamic DNS client such as ddclient. |
| 966 | | |
| 967 | | If the peer cannot be reached, a restart will be triggered, |
| 968 | | causing the hostname used with --remote to be re-resolved (if |
| 969 | | --resolv-retry is also specified). |
| 970 | | |
| 971 | | In server mode, --ping-restart, --inactive, or any other type of |
| 972 | | internally generated signal will always be applied to individual |
| 973 | | client instance objects, never to whole server itself. Note |
| 974 | | also in server mode that any internally generated signal which |
| 975 | | would normally cause a restart, will cause the deletion of the |
| 976 | | client instance object instead. |
| 977 | | |
| 978 | | In client mode, the --ping-restart parameter is set to 120 sec‐ |
| 979 | | onds by default. This default will hold until the client pulls |
| 980 | | a replacement value from the server, based on the --keepalive |
| 981 | | setting in the server configuration. To disable the 120 second |
| 982 | | default, set --ping-restart 0 on the client. |
| | 932 | Similar to --ping-exit, but trigger a SIGUSR1 restart after n sec‐ |
| | 933 | onds pass without reception of a ping or other packet from remote. |
| | 934 | |
| | 935 | This option is useful in cases where the remote peer has a dynamic |
| | 936 | IP address and a low-TTL DNS name is used to track the IP address |
| | 937 | using a service such as http://dyndns.org/ + a dynamic DNS client |
| | 938 | such as ddclient. |
| | 939 | |
| | 940 | If the peer cannot be reached, a restart will be triggered, causing |
| | 941 | the hostname used with --remote to be re-resolved (if --resolv- |
| | 942 | retry is also specified). |
| | 943 | |
| | 944 | In server mode, --ping-restart, --inactive, or any other type of |
| | 945 | internally generated signal will always be applied to individual |
| | 946 | client instance objects, never to whole server itself. Note also |
| | 947 | in server mode that any internally generated signal which would |
| | 948 | normally cause a restart, will cause the deletion of the client |
| | 949 | instance object instead. |
| | 950 | |
| | 951 | In client mode, the --ping-restart parameter is set to 120 seconds |
| | 952 | by default. This default will hold until the client pulls a |
| | 953 | replacement value from the server, based on the --keepalive setting |
| | 954 | in the server configuration. To disable the 120 second default, |
| | 955 | set --ping-restart 0 on the client. |
| 1050 | | Using this option ensures that key material and tunnel data are |
| 1051 | | never written to disk due to virtual memory paging operations |
| 1052 | | which occur under most modern operating systems. It ensures |
| 1053 | | that even if an attacker was able to crack the box running Open‐ |
| 1054 | | VPN, he would not be able to scan the system swap file to |
| 1055 | | recover previously used ephemeral keys, which are used for a |
| 1056 | | period of time governed by the --reneg options (see below), then |
| 1057 | | are discarded. |
| 1058 | | |
| 1059 | | The downside of using --mlock is that it will reduce the amount |
| 1060 | | of physical memory available to other applications. |
| | 1022 | Using this option ensures that key material and tunnel data are |
| | 1023 | never written to disk due to virtual memory paging operations which |
| | 1024 | occur under most modern operating systems. It ensures that even if |
| | 1025 | an attacker was able to crack the box running OpenVPN, he would not |
| | 1026 | be able to scan the system swap file to recover previously used |
| | 1027 | ephemeral keys, which are used for a period of time governed by the |
| | 1028 | --reneg options (see below), then are discarded. |
| | 1029 | |
| | 1030 | The downside of using --mlock is that it will reduce the amount of |
| | 1031 | physical memory available to other applications. |
| 1094 | | Normally the up script is called after the TUN/TAP device is |
| 1095 | | opened. In this context, the last command line parameter passed |
| 1096 | | to the script will be init. If the --up-restart option is also |
| 1097 | | used, the up script will be called for restarts as well. A |
| 1098 | | restart is considered to be a partial reinitialization of Open‐ |
| 1099 | | VPN where the TUN/TAP instance is preserved (the --persist-tun |
| 1100 | | option will enable such preservation). A restart can be gener‐ |
| 1101 | | ated by a SIGUSR1 signal, a --ping-restart timeout, or a connec‐ |
| 1102 | | tion reset when the TCP protocol is enabled with the --proto |
| 1103 | | option. If a restart occurs, and --up-restart has been speci‐ |
| 1104 | | fied, the up script will be called with restart as the last |
| 1105 | | parameter. |
| 1106 | | |
| 1107 | | The following standalone example shows how the --up script can |
| 1108 | | be called in both an initialization and restart context. (NOTE: |
| 1109 | | for security reasons, don't run the following example unless UDP |
| 1110 | | port 9999 is blocked by your firewall. Also, the example will |
| 1111 | | run indefinitely, so you should abort with control-c). |
| 1112 | | |
| 1113 | | openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 --up |
| 1114 | | 'echo up' --down 'echo down' --persist-tun --up-restart |
| 1115 | | |
| 1116 | | Note that OpenVPN also provides the --ifconfig option to auto‐ |
| 1117 | | matically ifconfig the TUN device, eliminating the need to |
| 1118 | | define an --up script, unless you also want to configure routes |
| 1119 | | in the --up script. |
| 1120 | | |
| 1121 | | If --ifconfig is also specified, OpenVPN will pass the ifconfig |
| 1122 | | local and remote endpoints on the command line to the --up |
| 1123 | | script so that they can be used to configure routes such as: |
| | 1065 | Normally the up script is called after the TUN/TAP device is |
| | 1066 | opened. In this context, the last command line parameter passed to |
| | 1067 | the script will be init. If the --up-restart option is also used, |
| | 1068 | the up script will be called for restarts as well. A restart is |
| | 1069 | considered to be a partial reinitialization of OpenVPN where the |
| | 1070 | TUN/TAP instance is preserved (the --persist-tun option will enable |
| | 1071 | such preservation). A restart can be generated by a SIGUSR1 sig‐ |
| | 1072 | nal, a --ping-restart timeout, or a connection reset when the TCP |
| | 1073 | protocol is enabled with the --proto option. If a restart occurs, |
| | 1074 | and --up-restart has been specified, the up script will be called |
| | 1075 | with restart as the last parameter. |
| | 1076 | |
| | 1077 | The following standalone example shows how the --up script can be |
| | 1078 | called in both an initialization and restart context. (NOTE: for |
| | 1079 | security reasons, don't run the following example unless UDP port |
| | 1080 | 9999 is blocked by your firewall. Also, the example will run |
| | 1081 | indefinitely, so you should abort with control-c). |
| | 1082 | |
| | 1083 | openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 --up 'echo |
| | 1084 | up' --down 'echo down' --persist-tun --up-restart |
| | 1085 | |
| | 1086 | Note that OpenVPN also provides the --ifconfig option to automati‐ |
| | 1087 | cally ifconfig the TUN device, eliminating the need to define an |
| | 1088 | --up script, unless you also want to configure routes in the --up |
| | 1089 | script. |
| | 1090 | |
| | 1091 | If --ifconfig is also specified, OpenVPN will pass the ifconfig |
| | 1092 | local and remote endpoints on the command line to the --up script |
| | 1093 | so that they can be used to configure routes such as: |
| 1128 | | Delay TUN/TAP open and possible --up script execution until |
| 1129 | | after TCP/UDP connection establishment with peer. |
| 1130 | | |
| 1131 | | In --proto udp mode, this option normally requires the use of |
| 1132 | | --ping to allow connection initiation to be sensed in the |
| 1133 | | absence of tunnel data, since UDP is a "connectionless" proto‐ |
| 1134 | | col. |
| 1135 | | |
| 1136 | | On Windows, this option will delay the TAP-Win32 media state |
| 1137 | | transitioning to "connected" until connection establishment, |
| 1138 | | i.e. the receipt of the first authenticated packet from the |
| 1139 | | peer. |
| | 1098 | Delay TUN/TAP open and possible --up script execution until after |
| | 1099 | TCP/UDP connection establishment with peer. |
| | 1100 | |
| | 1101 | In --proto udp mode, this option normally requires the use of |
| | 1102 | --ping to allow connection initiation to be sensed in the absence |
| | 1103 | of tunnel data, since UDP is a "connectionless" protocol. |
| | 1104 | |
| | 1105 | On Windows, this option will delay the TAP-Win32 media state tran‐ |
| | 1106 | sitioning to "connected" until connection establishment, i.e. the |
| | 1107 | receipt of the first authenticated packet from the peer. |
| 1142 | | Run command cmd after TUN/TAP device close (post --user UID |
| 1143 | | change and/or --chroot ). cmd consists of a path to script (or |
| 1144 | | executable program), optionally followed by arguments. The path |
| 1145 | | and arguments may be single- or double-quoted and/or escaped |
| 1146 | | using a backslash, and should be separated by one or more spa‐ |
| 1147 | | ces. |
| 1148 | | |
| 1149 | | Called with the same parameters and environmental variables as |
| 1150 | | the --up option above. |
| 1151 | | |
| 1152 | | Note that if you reduce privileges by using --user and/or |
| 1153 | | --group, your --down script will also run at reduced privilege. |
| | 1110 | Run command cmd after TUN/TAP device close (post --user UID change |
| | 1111 | and/or --chroot ). cmd consists of a path to script (or executable |
| | 1112 | program), optionally followed by arguments. The path and arguments |
| | 1113 | may be single- or double-quoted and/or escaped using a backslash, |
| | 1114 | and should be separated by one or more spaces. |
| | 1115 | |
| | 1116 | Called with the same parameters and environmental variables as the |
| | 1117 | --up option above. |
| | 1118 | |
| | 1119 | Note that if you reduce privileges by using --user and/or --group, |
| | 1120 | your --down script will also run at reduced privilege. |
| 1167 | | --setenv FORWARD_COMPATIBLE 1 |
| 1168 | | Relax config file syntax checking so that unknown directives |
| 1169 | | will trigger a warning but not a fatal error, on the assumption |
| 1170 | | that a given unknown directive might be valid in future OpenVPN |
| 1171 | | versions. |
| 1172 | | |
| 1173 | | This option should be used with caution, as there are good secu‐ |
| 1174 | | rity reasons for having OpenVPN fail if it detects problems in a |
| 1175 | | config file. Having said that, there are valid reasons for |
| 1176 | | wanting new software features to gracefully degrade when encoun‐ |
| 1177 | | tered by older software versions. |
| 1178 | | |
| 1179 | | --setenv-safe name value |
| 1180 | | Set a custom environmental variable OPENVPN_name=value to pass |
| 1181 | | to script. |
| 1182 | | |
| 1183 | | This directive is designed to be pushed by the server to |
| 1184 | | clients, and the prepending of "OPENVPN_" to the environmental |
| 1185 | | variable is a safety precaution to prevent a LD_PRELOAD style |
| 1186 | | attack from a malicious or compromised server. |
| | 1148 | This directive is designed to be pushed by the server to clients, |
| | 1149 | and the prepending of "OPENVPN_" to the environmental variable is a |
| | 1150 | safety precaution to prevent a LD_PRELOAD style attack from a mali‐ |
| | 1151 | cious or compromised server. |
| 1202 | | OpenVPN releases before v2.3 also supported a method flag which |
| 1203 | | indicated how OpenVPN should call external commands and scripts. |
| 1204 | | This could be either execve or system. As of OpenVPN v2.3, this |
| 1205 | | flag is no longer accepted. In most *nix environments the |
| 1206 | | execve() approach has been used without any issues. |
| 1207 | | |
| 1208 | | To run scripts in Windows in earlier OpenVPN versions you needed |
| 1209 | | to either add a full path to the script interpreter which can |
| 1210 | | parse the script or use the system flag to run these scripts. |
| 1211 | | As of OpenVPN v2.3 it is now a strict requirement to have full |
| 1212 | | path to the script interpreter when running non-executables |
| 1213 | | files. This is not needed for executable files, such as .exe, |
| 1214 | | .com, .bat or .cmd files. For example, if you have a Visual |
| 1215 | | Basic script, you must use this syntax now: |
| | 1167 | OpenVPN releases before v2.3 also supported a method flag which |
| | 1168 | indicated how OpenVPN should call external commands and scripts. |
| | 1169 | This could be either execve or system. As of OpenVPN v2.3, this |
| | 1170 | flag is no longer accepted. In most *nix environments the execve() |
| | 1171 | approach has been used without any issues. |
| | 1172 | |
| | 1173 | To run scripts in Windows in earlier OpenVPN versions you needed to |
| | 1174 | either add a full path to the script interpreter which can parse |
| | 1175 | the script or use the system flag to run these scripts. As of |
| | 1176 | OpenVPN v2.3 it is now a strict requirement to have full path to |
| | 1177 | the script interpreter when running non-executables files. This is |
| | 1178 | not needed for executable files, such as .exe, .com, .bat or .cmd |
| | 1179 | files. For example, if you have a Visual Basic script, you must |
| | 1180 | use this syntax now: |
| 1237 | | Change the user ID of the OpenVPN process to user after initial‐ |
| 1238 | | ization, dropping privileges in the process. This option is |
| 1239 | | useful to protect the system in the event that some hostile |
| 1240 | | party was able to gain control of an OpenVPN session. Though |
| 1241 | | OpenVPN's security features make this unlikely, it is provided |
| 1242 | | as a second line of defense. |
| 1243 | | |
| 1244 | | By setting user to nobody or somebody similarly unprivileged, |
| 1245 | | the hostile party would be limited in what damage they could |
| 1246 | | cause. Of course once you take away privileges, you cannot |
| 1247 | | return them to an OpenVPN session. This means, for example, |
| 1248 | | that if you want to reset an OpenVPN daemon with a SIGUSR1 sig‐ |
| 1249 | | nal (for example in response to a DHCP reset), you should make |
| 1250 | | use of one or more of the --persist options to ensure that Open‐ |
| 1251 | | VPN doesn't need to execute any privileged operations in order |
| 1252 | | to restart (such as re-reading key files or running ifconfig on |
| 1253 | | the TUN device). |
| | 1202 | Change the user ID of the OpenVPN process to user after initializa‐ |
| | 1203 | tion, dropping privileges in the process. This option is useful to |
| | 1204 | protect the system in the event that some hostile party was able to |
| | 1205 | gain control of an OpenVPN session. Though OpenVPN's security fea‐ |
| | 1206 | tures make this unlikely, it is provided as a second line of |
| | 1207 | defense. |
| | 1208 | |
| | 1209 | By setting user to nobody or somebody similarly unprivileged, the |
| | 1210 | hostile party would be limited in what damage they could cause. Of |
| | 1211 | course once you take away privileges, you cannot return them to an |
| | 1212 | OpenVPN session. This means, for example, that if you want to |
| | 1213 | reset an OpenVPN daemon with a SIGUSR1 signal (for example in |
| | 1214 | response to a DHCP reset), you should make use of one or more of |
| | 1215 | the --persist options to ensure that OpenVPN doesn't need to exe‐ |
| | 1216 | cute any privileged operations in order to restart (such as re- |
| | 1217 | reading key files or running ifconfig on the TUN device). |
| 1270 | | Chroot to dir after initialization. --chroot essentially rede‐ |
| 1271 | | fines dir as being the top level directory tree (/). OpenVPN |
| 1272 | | will therefore be unable to access any files outside this tree. |
| 1273 | | This can be desirable from a security standpoint. |
| 1274 | | |
| 1275 | | Since the chroot operation is delayed until after initializa‐ |
| 1276 | | tion, most OpenVPN options that reference files will operate in |
| 1277 | | a pre-chroot context. |
| 1278 | | |
| 1279 | | In many cases, the dir parameter can point to an empty direc‐ |
| 1280 | | tory, however complications can result when scripts or restarts |
| 1281 | | are executed after the chroot operation. |
| | 1234 | Chroot to dir after initialization. --chroot essentially redefines |
| | 1235 | dir as being the top level directory tree (/). OpenVPN will there‐ |
| | 1236 | fore be unable to access any files outside this tree. This can be |
| | 1237 | desirable from a security standpoint. |
| | 1238 | |
| | 1239 | Since the chroot operation is delayed until after initialization, |
| | 1240 | most OpenVPN options that reference files will operate in a pre- |
| | 1241 | chroot context. |
| | 1242 | |
| | 1243 | In many cases, the dir parameter can point to an empty directory, |
| | 1244 | however complications can result when scripts or restarts are exe‐ |
| | 1245 | cuted after the chroot operation. |
| 1284 | | Apply SELinux context after initialization. This essentially |
| 1285 | | provides the ability to restrict OpenVPN's rights to only net‐ |
| 1286 | | work I/O operations, thanks to SELinux. This goes further than |
| 1287 | | --user and --chroot in that those two, while being great secu‐ |
| 1288 | | rity features, unfortunately do not protect against privilege |
| 1289 | | escalation by exploitation of a vulnerable system call. You can |
| 1290 | | of course combine all three, but please note that since setcon |
| 1291 | | requires access to /proc you will have to provide it inside the |
| 1292 | | chroot directory (e.g. with mount --bind). |
| 1293 | | |
| 1294 | | Since the setcon operation is delayed until after initializa‐ |
| 1295 | | tion, OpenVPN can be restricted to just network-related system |
| 1296 | | calls, whereas by applying the context before startup (such as |
| 1297 | | the OpenVPN one provided in the SELinux Reference Policies) you |
| 1298 | | will have to allow many things required only during initializa‐ |
| 1299 | | tion. |
| 1300 | | |
| 1301 | | Like with chroot, complications can result when scripts or |
| 1302 | | restarts are executed after the setcon operation, which is why |
| 1303 | | you should really consider using the --persist-key and --per‐ |
| 1304 | | sist-tun options. |
| | 1248 | Apply SELinux context after initialization. This essentially pro‐ |
| | 1249 | vides the ability to restrict OpenVPN's rights to only network I/O |
| | 1250 | operations, thanks to SELinux. This goes further than --user and |
| | 1251 | --chroot in that those two, while being great security features, |
| | 1252 | unfortunately do not protect against privilege escalation by |
| | 1253 | exploitation of a vulnerable system call. You can of course combine |
| | 1254 | all three, but please note that since setcon requires access to |
| | 1255 | /proc you will have to provide it inside the chroot directory (e.g. |
| | 1256 | with mount --bind). |
| | 1257 | |
| | 1258 | Since the setcon operation is delayed until after initialization, |
| | 1259 | OpenVPN can be restricted to just network-related system calls, |
| | 1260 | whereas by applying the context before startup (such as the OpenVPN |
| | 1261 | one provided in the SELinux Reference Policies) you will have to |
| | 1262 | allow many things required only during initialization. |
| | 1263 | |
| | 1264 | Like with chroot, complications can result when scripts or restarts |
| | 1265 | are executed after the setcon operation, which is why you should |
| | 1266 | really consider using the --persist-key and --persist-tun options. |
| 1307 | | Become a daemon after all initialization functions are com‐ |
| 1308 | | pleted. This option will cause all message and error output to |
| 1309 | | be sent to the syslog file (such as /var/log/messages), except |
| 1310 | | for the output of scripts and ifconfig commands, which will go |
| 1311 | | to /dev/null unless otherwise redirected. The syslog redirect‐ |
| 1312 | | ion occurs immediately at the point that --daemon is parsed on |
| 1313 | | the command line even though the daemonization point occurs |
| 1314 | | later. If one of the --log options is present, it will |
| 1315 | | supercede syslog redirection. |
| 1316 | | |
| 1317 | | The optional progname parameter will cause OpenVPN to report its |
| 1318 | | program name to the system logger as progname. This can be use‐ |
| 1319 | | ful in linking OpenVPN messages in the syslog file with specific |
| 1320 | | tunnels. When unspecified, progname defaults to "openvpn". |
| 1321 | | |
| 1322 | | When OpenVPN is run with the --daemon option, it will try to |
| 1323 | | delay daemonization until the majority of initialization func‐ |
| 1324 | | tions which are capable of generating fatal errors are complete. |
| 1325 | | This means that initialization scripts can test the return sta‐ |
| 1326 | | tus of the openvpn command for a fairly reliable indication of |
| 1327 | | whether the command has correctly initialized and entered the |
| 1328 | | packet forwarding event loop. |
| 1329 | | |
| 1330 | | In OpenVPN, the vast majority of errors which occur after ini‐ |
| 1331 | | tialization are non-fatal. |
| | 1269 | Become a daemon after all initialization functions are completed. |
| | 1270 | This option will cause all message and error output to be sent to |
| | 1271 | the syslog file (such as /var/log/messages), except for the output |
| | 1272 | of scripts and ifconfig commands, which will go to /dev/null unless |
| | 1273 | otherwise redirected. The syslog redirection occurs immediately at |
| | 1274 | the point that --daemon is parsed on the command line even though |
| | 1275 | the daemonization point occurs later. If one of the --log options |
| | 1276 | is present, it will supercede syslog redirection. |
| | 1277 | |
| | 1278 | The optional progname parameter will cause OpenVPN to report its |
| | 1279 | program name to the system logger as progname. This can be useful |
| | 1280 | in linking OpenVPN messages in the syslog file with specific tun‐ |
| | 1281 | nels. When unspecified, progname defaults to "openvpn". |
| | 1282 | |
| | 1283 | When OpenVPN is run with the --daemon option, it will try to delay |
| | 1284 | daemonization until the majority of initialization functions which |
| | 1285 | are capable of generating fatal errors are complete. This means |
| | 1286 | that initialization scripts can test the return status of the open‐ |
| | 1287 | vpn command for a fairly reliable indication of whether the command |
| | 1288 | has correctly initialized and entered the packet forwarding event |
| | 1289 | loop. |
| | 1290 | |
| | 1291 | In OpenVPN, the vast majority of errors which occur after initial‐ |
| | 1292 | ization are non-fatal. |
| 1350 | | The wait/nowait option must match what is specified in the |
| 1351 | | inetd/xinetd config file. The nowait mode can only be used with |
| 1352 | | --proto tcp-server. The default is wait. The nowait mode can |
| 1353 | | be used to instantiate the OpenVPN daemon as a classic TCP |
| 1354 | | server, where client connection requests are serviced on a sin‐ |
| 1355 | | gle port number. For additional information on this kind of |
| 1356 | | configuration, see the OpenVPN FAQ: http://open‐ |
| 1357 | | vpn.net/faq.html#oneport |
| 1358 | | |
| 1359 | | This option precludes the use of --daemon, --local, or --remote. |
| 1360 | | Note that this option causes message and error output to be han‐ |
| 1361 | | dled in the same way as the --daemon option. The optional prog‐ |
| 1362 | | name parameter is also handled exactly as in --daemon. |
| 1363 | | |
| 1364 | | Also note that in wait mode, each OpenVPN tunnel requires a sep‐ |
| 1365 | | arate TCP/UDP port and a separate inetd or xinetd entry. See |
| 1366 | | the OpenVPN 1.x HOWTO for an example on using OpenVPN with |
| 1367 | | xinetd: http://openvpn.net/1xhowto.html |
| | 1310 | The wait/nowait option must match what is specified in the |
| | 1311 | inetd/xinetd config file. The nowait mode can only be used with |
| | 1312 | --proto tcp-server. The default is wait. The nowait mode can be |
| | 1313 | used to instantiate the OpenVPN daemon as a classic TCP server, |
| | 1314 | where client connection requests are serviced on a single port num‐ |
| | 1315 | ber. For additional information on this kind of configuration, see |
| | 1316 | the OpenVPN FAQ: http://openvpn.net/faq.html#oneport |
| | 1317 | |
| | 1318 | This option precludes the use of --daemon, --local, or --remote. |
| | 1319 | Note that this option causes message and error output to be handled |
| | 1320 | in the same way as the --daemon option. The optional progname |
| | 1321 | parameter is also handled exactly as in --daemon. |
| | 1322 | |
| | 1323 | Also note that in wait mode, each OpenVPN tunnel requires a sepa‐ |
| | 1324 | rate TCP/UDP port and a separate inetd or xinetd entry. See the |
| | 1325 | OpenVPN 1.x HOWTO for an example on using OpenVPN with xinetd: |
| | 1326 | http://openvpn.net/1xhowto.html |
| 1370 | | Output logging messages to file, including output to std‐ |
| 1371 | | out/stderr which is generated by called scripts. If file |
| 1372 | | already exists it will be truncated. This option takes effect |
| 1373 | | immediately when it is parsed in the command line and will |
| 1374 | | supercede syslog output if --daemon or --inetd is also speci‐ |
| 1375 | | fied. This option is persistent over the entire course of an |
| 1376 | | OpenVPN instantiation and will not be reset by SIGHUP, SIGUSR1, |
| 1377 | | or --ping-restart. |
| 1378 | | |
| 1379 | | Note that on Windows, when OpenVPN is started as a service, log‐ |
| 1380 | | ging occurs by default without the need to specify this option. |
| | 1329 | Output logging messages to file, including output to stdout/stderr |
| | 1330 | which is generated by called scripts. If file already exists it |
| | 1331 | will be truncated. This option takes effect immediately when it is |
| | 1332 | parsed in the command line and will supercede syslog output if |
| | 1333 | --daemon or --inetd is also specified. This option is persistent |
| | 1334 | over the entire course of an OpenVPN instantiation and will not be |
| | 1335 | reset by SIGHUP, SIGUSR1, or --ping-restart. |
| | 1336 | |
| | 1337 | Note that on Windows, when OpenVPN is started as a service, logging |
| | 1338 | occurs by default without the need to specify this option. |
| 1400 | | (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a |
| 1401 | | call to poll/epoll/select prior to the write operation. The |
| 1402 | | purpose of such a call would normally be to block until the |
| 1403 | | device or socket is ready to accept the write. Such blocking is |
| 1404 | | unnecessary on some platforms which don't support write blocking |
| 1405 | | on UDP sockets or TUN/TAP devices. In such cases, one can opti‐ |
| 1406 | | mize the event loop by avoiding the poll/epoll/select call, |
| 1407 | | improving CPU efficiency by 5% to 10%. |
| 1408 | | |
| 1409 | | This option can only be used on non-Windows systems, when |
| 1410 | | --proto udp is specified, and when --shaper is NOT specified. |
| | 1358 | (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call |
| | 1359 | to poll/epoll/select prior to the write operation. The purpose of |
| | 1360 | such a call would normally be to block until the device or socket |
| | 1361 | is ready to accept the write. Such blocking is unnecessary on some |
| | 1362 | platforms which don't support write blocking on UDP sockets or |
| | 1363 | TUN/TAP devices. In such cases, one can optimize the event loop by |
| | 1364 | avoiding the poll/epoll/select call, improving CPU efficiency by 5% |
| | 1365 | to 10%. |
| | 1366 | |
| | 1367 | This option can only be used on non-Windows systems, when --proto |
| | 1368 | udp is specified, and when --shaper is NOT specified. |
| 1471 | | In a server mode setup, it is possible to selectively turn com‐ |
| 1472 | | pression on or off for individual clients. |
| 1473 | | |
| 1474 | | First, make sure the client-side config file enables selective |
| 1475 | | compression by having at least one --comp-lzo directive, such as |
| 1476 | | --comp-lzo no. This will turn off compression by default, but |
| 1477 | | allow a future directive push from the server to dynamically |
| 1478 | | change the on/off/adaptive setting. |
| 1479 | | |
| 1480 | | Next in a --client-config-dir file, specify the compression set‐ |
| 1481 | | ting for the client, for example: |
| | 1427 | In a server mode setup, it is possible to selectively turn compres‐ |
| | 1428 | sion on or off for individual clients. |
| | 1429 | |
| | 1430 | First, make sure the client-side config file enables selective com‐ |
| | 1431 | pression by having at least one --comp-lzo directive, such as |
| | 1432 | --comp-lzo no. This will turn off compression by default, but |
| | 1433 | allow a future directive push from the server to dynamically change |
| | 1434 | the on/off/adaptive setting. |
| | 1435 | |
| | 1436 | Next in a --client-config-dir file, specify the compression setting |
| | 1437 | for the client, for example: |
| 1490 | | When used in conjunction with --comp-lzo, this option will dis‐ |
| 1491 | | able OpenVPN's adaptive compression algorithm. Normally, adap‐ |
| 1492 | | tive compression is enabled with --comp-lzo. |
| 1493 | | |
| 1494 | | Adaptive compression tries to optimize the case where you have |
| 1495 | | compression enabled, but you are sending predominantly uncom‐ |
| 1496 | | pressible (or pre-compressed) packets over the tunnel, such as |
| 1497 | | an FTP or rsync transfer of a large, compressed file. With |
| 1498 | | adaptive compression, OpenVPN will periodically sample the com‐ |
| 1499 | | pression process to measure its efficiency. If the data being |
| 1500 | | sent over the tunnel is already compressed, the compression |
| 1501 | | efficiency will be very low, triggering openvpn to disable com‐ |
| 1502 | | pression for a period of time until the next re-sample test. |
| | 1446 | When used in conjunction with --comp-lzo, this option will disable |
| | 1447 | OpenVPN's adaptive compression algorithm. Normally, adaptive com‐ |
| | 1448 | pression is enabled with --comp-lzo. |
| | 1449 | |
| | 1450 | Adaptive compression tries to optimize the case where you have com‐ |
| | 1451 | pression enabled, but you are sending predominantly uncompressible |
| | 1452 | (or pre-compressed) packets over the tunnel, such as an FTP or |
| | 1453 | rsync transfer of a large, compressed file. With adaptive compres‐ |
| | 1454 | sion, OpenVPN will periodically sample the compression process to |
| | 1455 | measure its efficiency. If the data being sent over the tunnel is |
| | 1456 | already compressed, the compression efficiency will be very low, |
| | 1457 | triggering openvpn to disable compression for a period of time |
| | 1458 | until the next re-sample test. |
| 1505 | | Enable a TCP server on IP:port to handle daemon management func‐ |
| 1506 | | tions. pw-file, if specified, is a password file (password on |
| 1507 | | first line) or "stdin" to prompt from standard input. The pass‐ |
| 1508 | | word provided will set the password which TCP clients will need |
| 1509 | | to provide in order to access management functions. |
| 1510 | | |
| 1511 | | The management interface can also listen on a unix domain |
| 1512 | | socket, for those platforms that support it. To use a unix |
| 1513 | | domain socket, specify the unix socket pathname in place of IP |
| 1514 | | and set port to 'unix'. While the default behavior is to create |
| 1515 | | a unix domain socket that may be connected to by any process, |
| 1516 | | the --management-client-user and --management-client-group |
| 1517 | | directives can be used to restrict access. |
| 1518 | | |
| 1519 | | The management interface provides a special mode where the TCP |
| 1520 | | management link can operate over the tunnel itself. To enable |
| 1521 | | this mode, set IP = "tunnel". Tunnel mode will cause the man‐ |
| 1522 | | agement interface to listen for a TCP connection on the local |
| 1523 | | VPN address of the TUN/TAP interface. |
| 1524 | | |
| 1525 | | While the management port is designed for programmatic control |
| 1526 | | of OpenVPN by other applications, it is possible to telnet to |
| 1527 | | the port, using a telnet client in "raw" mode. Once connected, |
| 1528 | | type "help" for a list of commands. |
| 1529 | | |
| 1530 | | For detailed documentation on the management interface, see the |
| 1531 | | management-notes.txt file in the management folder of the Open‐ |
| 1532 | | VPN source distribution. |
| 1533 | | |
| 1534 | | It is strongly recommended that IP be set to 127.0.0.1 (local‐ |
| 1535 | | host) to restrict accessibility of the management server to |
| 1536 | | local clients. |
| | 1461 | Enable a TCP server on IP:port to handle daemon management func‐ |
| | 1462 | tions. pw-file, if specified, is a password file (password on |
| | 1463 | first line) or "stdin" to prompt from standard input. The password |
| | 1464 | provided will set the password which TCP clients will need to pro‐ |
| | 1465 | vide in order to access management functions. |
| | 1466 | |
| | 1467 | The management interface can also listen on a unix domain socket, |
| | 1468 | for those platforms that support it. To use a unix domain socket, |
| | 1469 | specify the unix socket pathname in place of IP and set port to |
| | 1470 | 'unix'. While the default behavior is to create a unix domain |
| | 1471 | socket that may be connected to by any process, the --management- |
| | 1472 | client-user and --management-client-group directives can be used to |
| | 1473 | restrict access. |
| | 1474 | |
| | 1475 | The management interface provides a special mode where the TCP man‐ |
| | 1476 | agement link can operate over the tunnel itself. To enable this |
| | 1477 | mode, set IP = "tunnel". Tunnel mode will cause the management |
| | 1478 | interface to listen for a TCP connection on the local VPN address |
| | 1479 | of the TUN/TAP interface. |
| | 1480 | |
| | 1481 | While the management port is designed for programmatic control of |
| | 1482 | OpenVPN by other applications, it is possible to telnet to the |
| | 1483 | port, using a telnet client in "raw" mode. Once connected, type |
| | 1484 | "help" for a list of commands. |
| | 1485 | |
| | 1486 | For detailed documentation on the management interface, see the |
| | 1487 | management-notes.txt file in the management folder of the OpenVPN |
| | 1488 | source distribution. |
| | 1489 | |
| | 1490 | It is strongly recommended that IP be set to 127.0.0.1 (localhost) |
| | 1491 | to restrict accessibility of the management server to local |
| | 1492 | clients. |
| 1606 | | Load plug-in module from the file module-pathname, passing init- |
| 1607 | | string as an argument to the module initialization function. |
| 1608 | | Multiple plugin modules may be loaded into one OpenVPN process. |
| 1609 | | |
| 1610 | | For more information and examples on how to build OpenVPN plug- |
| 1611 | | in modules, see the README file in the plugin folder of the |
| 1612 | | OpenVPN source distribution. |
| 1613 | | |
| 1614 | | If you are using an RPM install of OpenVPN, see /usr/share/open‐ |
| 1615 | | vpn/plugin. The documentation is in doc and the actual plugin |
| 1616 | | modules are in lib. |
| 1617 | | |
| 1618 | | Multiple plugin modules can be cascaded, and modules can be used |
| 1619 | | in tandem with scripts. The modules will be called by OpenVPN |
| 1620 | | in the order that they are declared in the config file. If both |
| 1621 | | a plugin and script are configured for the same callback, the |
| 1622 | | script will be called last. If the return code of the mod‐ |
| 1623 | | ule/script controls an authentication function (such as tls-ver‐ |
| 1624 | | ify, auth-user-pass-verify, or client-connect), then every mod‐ |
| 1625 | | ule and script must return success (0) in order for the connec‐ |
| 1626 | | tion to be authenticated. |
| | 1558 | Load plug-in module from the file module-pathname, passing init- |
| | 1559 | string as an argument to the module initialization function. Mul‐ |
| | 1560 | tiple plugin modules may be loaded into one OpenVPN process. |
| | 1561 | |
| | 1562 | For more information and examples on how to build OpenVPN plug-in |
| | 1563 | modules, see the README file in the plugin folder of the OpenVPN |
| | 1564 | source distribution. |
| | 1565 | |
| | 1566 | If you are using an RPM install of OpenVPN, see /usr/share/open‐ |
| | 1567 | vpn/plugin. The documentation is in doc and the actual plugin mod‐ |
| | 1568 | ules are in lib. |
| | 1569 | |
| | 1570 | Multiple plugin modules can be cascaded, and modules can be used in |
| | 1571 | tandem with scripts. The modules will be called by OpenVPN in the |
| | 1572 | order that they are declared in the config file. If both a plugin |
| | 1573 | and script are configured for the same callback, the script will be |
| | 1574 | called last. If the return code of the module/script controls an |
| | 1575 | authentication function (such as tls-verify, auth-user-pass-verify, |
| | 1576 | or client-connect), then every module and script must return suc‐ |
| | 1577 | cess (0) in order for the connection to be authenticated. |
| 1674 | | A helper directive similar to --server which is designed to sim‐ |
| 1675 | | plify the configuration of OpenVPN's server mode in ethernet |
| 1676 | | bridging configurations. |
| 1677 | | |
| 1678 | | If --server-bridge is used without any parameters, it will |
| 1679 | | enable a DHCP-proxy mode, where connecting OpenVPN clients will |
| 1680 | | receive an IP address for their TAP adapter from the DHCP server |
| 1681 | | running on the OpenVPN server-side LAN. Note that only clients |
| 1682 | | that support the binding of a DHCP client with the TAP adapter |
| 1683 | | (such as Windows) can support this mode. The optional nogw flag |
| 1684 | | (advanced) indicates that gateway information should not be |
| 1685 | | pushed to the client. |
| 1686 | | |
| 1687 | | To configure ethernet bridging, you must first use your OS's |
| 1688 | | bridging capability to bridge the TAP interface with the ether‐ |
| 1689 | | net NIC interface. For example, on Linux this is done with the |
| 1690 | | brctl tool, and with Windows XP it is done in the Network Con‐ |
| 1691 | | nections Panel by selecting the ethernet and TAP adapters and |
| 1692 | | right-clicking on "Bridge Connections". |
| 1693 | | |
| 1694 | | Next you you must manually set the IP/netmask on the bridge |
| 1695 | | interface. The gateway and netmask parameters to --server- |
| 1696 | | bridge can be set to either the IP/netmask of the bridge inter‐ |
| 1697 | | face, or the IP/netmask of the default gateway/router on the |
| 1698 | | bridged subnet. |
| 1699 | | |
| 1700 | | Finally, set aside a IP range in the bridged subnet, denoted by |
| 1701 | | pool-start-IP and pool-end-IP, for OpenVPN to allocate to con‐ |
| 1702 | | necting clients. |
| 1703 | | |
| 1704 | | For example, server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 |
| | 1625 | A helper directive similar to --server which is designed to sim‐ |
| | 1626 | plify the configuration of OpenVPN's server mode in ethernet bridg‐ |
| | 1627 | ing configurations. |
| | 1628 | |
| | 1629 | If --server-bridge is used without any parameters, it will enable a |
| | 1630 | DHCP-proxy mode, where connecting OpenVPN clients will receive an |
| | 1631 | IP address for their TAP adapter from the DHCP server running on |
| | 1632 | the OpenVPN server-side LAN. Note that only clients that support |
| | 1633 | the binding of a DHCP client with the TAP adapter (such as Windows) |
| | 1634 | can support this mode. The optional nogw flag (advanced) indicates |
| | 1635 | that gateway information should not be pushed to the client. |
| | 1636 | |
| | 1637 | To configure ethernet bridging, you must first use your OS's bridg‐ |
| | 1638 | ing capability to bridge the TAP interface with the ethernet NIC |
| | 1639 | interface. For example, on Linux this is done with the brctl tool, |
| | 1640 | and with Windows XP it is done in the Network Connections Panel by |
| | 1641 | selecting the ethernet and TAP adapters and right-clicking on |
| | 1642 | "Bridge Connections". |
| | 1643 | |
| | 1644 | Next you you must manually set the IP/netmask on the bridge inter‐ |
| | 1645 | face. The gateway and netmask parameters to --server-bridge can be |
| | 1646 | set to either the IP/netmask of the bridge interface, or the |
| | 1647 | IP/netmask of the default gateway/router on the bridged subnet. |
| | 1648 | |
| | 1649 | Finally, set aside a IP range in the bridged subnet, denoted by |
| | 1650 | pool-start-IP and pool-end-IP, for OpenVPN to allocate to connect‐ |
| | 1651 | ing clients. |
| | 1652 | |
| | 1653 | For example, server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 |
| 1727 | | Push a config file option back to the client for remote execu‐ |
| 1728 | | tion. Note that option must be enclosed in double quotes (""). |
| 1729 | | The client must specify --pull in its config file. The set of |
| 1730 | | options which can be pushed is limited by both feasibility and |
| 1731 | | security. Some options such as those which would execute |
| 1732 | | scripts are banned, since they would effectively allow a compro‐ |
| 1733 | | mised server to execute arbitrary code on the client. Other |
| 1734 | | options such as TLS or MTU parameters cannot be pushed because |
| 1735 | | the client needs to know them before the connection to the |
| 1736 | | server can be initiated. |
| 1737 | | |
| 1738 | | This is a partial list of options which can currently be pushed: |
| 1739 | | --route, --route-gateway, --route-delay, --redirect-gateway, |
| 1740 | | --ip-win32, --dhcp-option, --inactive, --ping, --ping-exit, |
| 1741 | | --ping-restart, --setenv, --persist-key, --persist-tun, --echo, |
| 1742 | | --comp-lzo, --socket-flags, --sndbuf, --rcvbuf |
| | 1676 | Push a config file option back to the client for remote execution. |
| | 1677 | Note that option must be enclosed in double quotes (""). The |
| | 1678 | client must specify --pull in its config file. The set of options |
| | 1679 | which can be pushed is limited by both feasibility and security. |
| | 1680 | Some options such as those which would execute scripts are banned, |
| | 1681 | since they would effectively allow a compromised server to execute |
| | 1682 | arbitrary code on the client. Other options such as TLS or MTU |
| | 1683 | parameters cannot be pushed because the client needs to know them |
| | 1684 | before the connection to the server can be initiated. |
| | 1685 | |
| | 1686 | This is a partial list of options which can currently be pushed: |
| | 1687 | --route, --route-gateway, --route-delay, --redirect-gateway, --ip- |
| | 1688 | win32, --dhcp-option, --inactive, --ping, --ping-exit, --ping- |
| | 1689 | restart, --setenv, --persist-key, --persist-tun, --echo, --comp- |
| | 1690 | lzo, --socket-flags, --sndbuf, --rcvbuf |
| 1788 | | Persist/unpersist ifconfig-pool data to file, at seconds inter‐ |
| 1789 | | vals (default=600), as well as on program startup and shutdown. |
| 1790 | | |
| 1791 | | The goal of this option is to provide a long-term association |
| 1792 | | between clients (denoted by their common name) and the virtual |
| 1793 | | IP address assigned to them from the ifconfig-pool. Maintaining |
| 1794 | | a long-term association is good for clients because it allows |
| 1795 | | them to effectively use the --persist-tun option. |
| 1796 | | |
| 1797 | | file is a comma-delimited ASCII file, formatted as <Common- |
| | 1736 | Persist/unpersist ifconfig-pool data to file, at seconds intervals |
| | 1737 | (default=600), as well as on program startup and shutdown. |
| | 1738 | |
| | 1739 | The goal of this option is to provide a long-term association |
| | 1740 | between clients (denoted by their common name) and the virtual IP |
| | 1741 | address assigned to them from the ifconfig-pool. Maintaining a |
| | 1742 | long-term association is good for clients because it allows them to |
| | 1743 | effectively use the --persist-tun option. |
| | 1744 | |
| | 1745 | file is a comma-delimited ASCII file, formatted as <Common- |
| 1821 | | The parameters local and remote-netmask are set according to the |
| 1822 | | --ifconfig directive which you want to execute on the client |
| 1823 | | machine to configure the remote end of the tunnel. Note that |
| 1824 | | the parameters local and remote-netmask are from the perspective |
| 1825 | | of the client, not the server. They may be DNS names rather |
| 1826 | | than IP addresses, in which case they will be resolved on the |
| 1827 | | server at the time of client connection. |
| 1828 | | |
| 1829 | | The optional alias parameter may be used in cases where NAT |
| 1830 | | causes the client view of its local endpoint to differ from the |
| 1831 | | server view. In this case local/remote-netmask will refer to |
| 1832 | | the server view while alias/remote-netmask will refer to the |
| 1833 | | client view. |
| 1834 | | |
| 1835 | | This option must be associated with a specific client instance, |
| 1836 | | which means that it must be specified either in a client |
| 1837 | | instance config file using --client-config-dir or dynamically |
| 1838 | | generated using a --client-connect script. |
| 1839 | | |
| 1840 | | Remember also to include a --route directive in the main OpenVPN |
| 1841 | | config file which encloses local, so that the kernel will know |
| 1842 | | to route it to the server's TUN/TAP interface. |
| 1843 | | |
| 1844 | | OpenVPN's internal client IP address selection algorithm works |
| 1845 | | as follows: |
| 1846 | | |
| 1847 | | 1 -- Use --client-connect script generated file for static IP |
| | 1769 | The parameters local and remote-netmask are set according to the |
| | 1770 | --ifconfig directive which you want to execute on the client |
| | 1771 | machine to configure the remote end of the tunnel. Note that the |
| | 1772 | parameters local and remote-netmask are from the perspective of the |
| | 1773 | client, not the server. They may be DNS names rather than IP |
| | 1774 | addresses, in which case they will be resolved on the server at the |
| | 1775 | time of client connection. |
| | 1776 | |
| | 1777 | The optional alias parameter may be used in cases where NAT causes |
| | 1778 | the client view of its local endpoint to differ from the server |
| | 1779 | view. In this case local/remote-netmask will refer to the server |
| | 1780 | view while alias/remote-netmask will refer to the client view. |
| | 1781 | |
| | 1782 | This option must be associated with a specific client instance, |
| | 1783 | which means that it must be specified either in a client instance |
| | 1784 | config file using --client-config-dir or dynamically generated |
| | 1785 | using a --client-connect script. |
| | 1786 | |
| | 1787 | Remember also to include a --route directive in the main OpenVPN |
| | 1788 | config file which encloses local, so that the kernel will know to |
| | 1789 | route it to the server's TUN/TAP interface. |
| | 1790 | |
| | 1791 | OpenVPN's internal client IP address selection algorithm works as |
| | 1792 | follows: |
| | 1793 | |
| | 1794 | 1 -- Use --client-connect script generated file for static IP |
| 1854 | | Generate an internal route to a specific client. The netmask |
| 1855 | | parameter, if omitted, defaults to 255.255.255.255. |
| 1856 | | |
| 1857 | | This directive can be used to route a fixed subnet from the |
| 1858 | | server to a particular client, regardless of where the client is |
| 1859 | | connecting from. Remember that you must also add the route to |
| 1860 | | the system routing table as well (such as by using the --route |
| 1861 | | directive). The reason why two routes are needed is that the |
| 1862 | | --route directive routes the packet from the kernel to OpenVPN. |
| 1863 | | Once in OpenVPN, the --iroute directive routes to the specific |
| 1864 | | client. |
| 1865 | | |
| 1866 | | This option must be specified either in a client instance config |
| 1867 | | file using --client-config-dir or dynamically generated using a |
| | 1800 | Generate an internal route to a specific client. The netmask param‐ |
| | 1801 | eter, if omitted, defaults to 255.255.255.255. |
| | 1802 | |
| | 1803 | This directive can be used to route a fixed subnet from the server |
| | 1804 | to a particular client, regardless of where the client is connect‐ |
| | 1805 | ing from. Remember that you must also add the route to the system |
| | 1806 | routing table as well (such as by using the --route directive). |
| | 1807 | The reason why two routes are needed is that the --route directive |
| | 1808 | routes the packet from the kernel to OpenVPN. Once in OpenVPN, the |
| | 1809 | --iroute directive routes to the specific client. |
| | 1810 | |
| | 1811 | This option must be specified either in a client instance config |
| | 1812 | file using --client-config-dir or dynamically generated using a |
| 1870 | | The --iroute directive also has an important interaction with |
| 1871 | | --push "route ...". --iroute essentially defines a subnet which |
| 1872 | | is owned by a particular client (we will call this client A). |
| 1873 | | If you would like other clients to be able to reach A's subnet, |
| 1874 | | you can use --push "route ..." together with --client-to-client |
| 1875 | | to effect this. In order for all clients to see A's subnet, |
| 1876 | | OpenVPN must push this route to all clients EXCEPT for A, since |
| 1877 | | the subnet is already owned by A. OpenVPN accomplishes this by |
| 1878 | | not not pushing a route to a client if it matches one of the |
| 1879 | | client's iroutes. |
| | 1815 | The --iroute directive also has an important interaction with |
| | 1816 | --push "route ...". --iroute essentially defines a subnet which is |
| | 1817 | owned by a particular client (we will call this client A). If you |
| | 1818 | would like other clients to be able to reach A's subnet, you can |
| | 1819 | use --push "route ..." together with --client-to-client to effect |
| | 1820 | this. In order for all clients to see A's subnet, OpenVPN must |
| | 1821 | push this route to all clients EXCEPT for A, since the subnet is |
| | 1822 | already owned by A. OpenVPN accomplishes this by not not pushing a |
| | 1823 | route to a client if it matches one of the client's iroutes. |
| 1882 | | Because the OpenVPN server mode handles multiple clients through |
| 1883 | | a single tun or tap interface, it is effectively a router. The |
| 1884 | | --client-to-client flag tells OpenVPN to internally route |
| 1885 | | client-to-client traffic rather than pushing all client-origi‐ |
| 1886 | | nating traffic to the TUN/TAP interface. |
| 1887 | | |
| 1888 | | When this option is used, each client will "see" the other |
| 1889 | | clients which are currently connected. Otherwise, each client |
| 1890 | | will only see the server. Don't use this option if you want to |
| 1891 | | firewall tunnel traffic using custom, per-client rules. |
| | 1826 | Because the OpenVPN server mode handles multiple clients through a |
| | 1827 | single tun or tap interface, it is effectively a router. The |
| | 1828 | --client-to-client flag tells OpenVPN to internally route client- |
| | 1829 | to-client traffic rather than pushing all client-originating traf‐ |
| | 1830 | fic to the TUN/TAP interface. |
| | 1831 | |
| | 1832 | When this option is used, each client will "see" the other clients |
| | 1833 | which are currently connected. Otherwise, each client will only |
| | 1834 | see the server. Don't use this option if you want to firewall tun‐ |
| | 1835 | nel traffic using custom, per-client rules. |
| 1902 | | cmd consists of a path to script (or executable program), |
| 1903 | | optionally followed by arguments. The path and arguments may be |
| 1904 | | single- or double-quoted and/or escaped using a backslash, and |
| 1905 | | should be separated by one or more spaces. |
| 1906 | | |
| 1907 | | The command is passed the common name and IP address of the |
| 1908 | | just-authenticated client as environmental variables (see envi‐ |
| 1909 | | ronmental variable section below). The command is also passed |
| 1910 | | the pathname of a freshly created temporary file as the last |
| 1911 | | argument (after any arguments specified in cmd ), to be used by |
| 1912 | | the command to pass dynamically generated config file directives |
| 1913 | | back to OpenVPN. |
| 1914 | | |
| 1915 | | If the script wants to generate a dynamic config file to be |
| 1916 | | applied on the server when the client connects, it should write |
| 1917 | | it to the file named by the last argument. |
| 1918 | | |
| 1919 | | See the --client-config-dir option below for options which can |
| 1920 | | be legally used in a dynamically generated config file. |
| 1921 | | |
| 1922 | | Note that the return value of script is significant. If script |
| 1923 | | returns a non-zero error status, it will cause the client to be |
| | 1846 | cmd consists of a path to script (or executable program), option‐ |
| | 1847 | ally followed by arguments. The path and arguments may be single- |
| | 1848 | or double-quoted and/or escaped using a backslash, and should be |
| | 1849 | separated by one or more spaces. |
| | 1850 | |
| | 1851 | The command is passed the common name and IP address of the just- |
| | 1852 | authenticated client as environmental variables (see environmental |
| | 1853 | variable section below). The command is also passed the pathname |
| | 1854 | of a freshly created temporary file as the last argument (after any |
| | 1855 | arguments specified in cmd ), to be used by the command to pass |
| | 1856 | dynamically generated config file directives back to OpenVPN. |
| | 1857 | |
| | 1858 | If the script wants to generate a dynamic config file to be applied |
| | 1859 | on the server when the client connects, it should write it to the |
| | 1860 | file named by the last argument. |
| | 1861 | |
| | 1862 | See the --client-config-dir option below for options which can be |
| | 1863 | legally used in a dynamically generated config file. |
| | 1864 | |
| | 1865 | Note that the return value of script is significant. If script |
| | 1866 | returns a non-zero error status, it will cause the client to be |
| 1927 | | Like --client-connect but called on client instance shutdown. |
| 1928 | | Will not be called unless the --client-connect script and plug‐ |
| 1929 | | ins (if defined) were previously called on this instance with |
| 1930 | | successful (0) status returns. |
| 1931 | | |
| 1932 | | The exception to this rule is if the --client-disconnect command |
| 1933 | | or plugins are cascaded, and at least one client-connect func‐ |
| 1934 | | tion succeeded, then ALL of the client-disconnect functions for |
| 1935 | | scripts and plugins will be called on client instance object |
| 1936 | | deletion, even in cases where some of the related client-connect |
| 1937 | | functions returned an error status. |
| 1938 | | |
| 1939 | | The --client-disconnect command is passed the same pathname as |
| 1940 | | the corresponding --client-connect command as its last argument. |
| 1941 | | (after any arguments specified in cmd ). |
| | 1870 | Like --client-connect but called on client instance shutdown. Will |
| | 1871 | not be called unless the --client-connect script and plugins (if |
| | 1872 | defined) were previously called on this instance with successful |
| | 1873 | (0) status returns. |
| | 1874 | |
| | 1875 | The exception to this rule is if the --client-disconnect command or |
| | 1876 | plugins are cascaded, and at least one client-connect function suc‐ |
| | 1877 | ceeded, then ALL of the client-disconnect functions for scripts and |
| | 1878 | plugins will be called on client instance object deletion, even in |
| | 1879 | cases where some of the related client-connect functions returned |
| | 1880 | an error status. |
| | 1881 | |
| | 1882 | The --client-disconnect command is passed the same pathname as the |
| | 1883 | corresponding --client-connect command as its last argument. (after |
| | 1884 | any arguments specified in cmd ). |
| 1944 | | Specify a directory dir for custom client config files. After a |
| 1945 | | connecting client has been authenticated, OpenVPN will look in |
| 1946 | | this directory for a file having the same name as the client's |
| 1947 | | X509 common name. If a matching file exists, it will be opened |
| 1948 | | and parsed for client-specific configuration options. If no |
| 1949 | | matching file is found, OpenVPN will instead try to open and |
| 1950 | | parse a default file called "DEFAULT", which may be provided but |
| 1951 | | is not required. Note that the configuration files must be read‐ |
| 1952 | | able by the OpenVPN process after it has dropped it's root priv‐ |
| 1953 | | ileges. |
| 1954 | | |
| 1955 | | This file can specify a fixed IP address for a given client |
| 1956 | | using --ifconfig-push, as well as fixed subnets owned by the |
| 1957 | | client using --iroute. |
| 1958 | | |
| 1959 | | One of the useful properties of this option is that it allows |
| 1960 | | client configuration files to be conveniently created, edited, |
| 1961 | | or removed while the server is live, without needing to restart |
| 1962 | | the server. |
| 1963 | | |
| 1964 | | The following options are legal in a client-specific context: |
| | 1887 | Specify a directory dir for custom client config files. After a |
| | 1888 | connecting client has been authenticated, OpenVPN will look in this |
| | 1889 | directory for a file having the same name as the client's X509 com‐ |
| | 1890 | mon name. If a matching file exists, it will be opened and parsed |
| | 1891 | for client-specific configuration options. If no matching file is |
| | 1892 | found, OpenVPN will instead try to open and parse a default file |
| | 1893 | called "DEFAULT", which may be provided but is not required. Note |
| | 1894 | that the configuration files must be readable by the OpenVPN |
| | 1895 | process after it has dropped it's root privileges. |
| | 1896 | |
| | 1897 | This file can specify a fixed IP address for a given client using |
| | 1898 | --ifconfig-push, as well as fixed subnets owned by the client using |
| | 1899 | --iroute. |
| | 1900 | |
| | 1901 | One of the useful properties of this option is that it allows |
| | 1902 | client configuration files to be conveniently created, edited, or |
| | 1903 | removed while the server is live, without needing to restart the |
| | 1904 | server. |
| | 1905 | |
| | 1906 | The following options are legal in a client-specific context: |
| 2028 | | Allow a maximum of n internal routes per client (default=256). |
| 2029 | | This is designed to help contain DoS attacks where an authenti‐ |
| 2030 | | cated client floods the server with packets appearing to come |
| 2031 | | from many unique MAC addresses, forcing the server to deplete |
| 2032 | | virtual memory as its internal routing table expands. This |
| 2033 | | directive can be used in a --client-config-dir file or auto-gen‐ |
| 2034 | | erated by a --client-connect script to override the global value |
| 2035 | | for a particular client. |
| 2036 | | |
| 2037 | | Note that this directive affects OpenVPN's internal routing ta‐ |
| 2038 | | ble, not the kernel routing table. |
| | 1969 | Allow a maximum of n internal routes per client (default=256). |
| | 1970 | This is designed to help contain DoS attacks where an authenticated |
| | 1971 | client floods the server with packets appearing to come from many |
| | 1972 | unique MAC addresses, forcing the server to deplete virtual memory |
| | 1973 | as its internal routing table expands. This directive can be used |
| | 1974 | in a --client-config-dir file or auto-generated by a --client-con‐ |
| | 1975 | nect script to override the global value for a particular client. |
| | 1976 | |
| | 1977 | Note that this directive affects OpenVPN's internal routing table, |
| | 1978 | not the kernel routing table. |
| 2074 | | [1] operation -- "add", "update", or "delete" based on whether |
| 2075 | | or not the address is being added to, modified, or deleted from |
| 2076 | | OpenVPN's internal routing table. |
| 2077 | | [2] address -- The address being learned or unlearned. This can |
| 2078 | | be an IPv4 address such as "198.162.10.14", an IPv4 subnet such |
| 2079 | | as "198.162.10.0/24", or an ethernet MAC address (when --dev tap |
| 2080 | | is being used) such as "00:FF:01:02:03:04". |
| 2081 | | [3] common name -- The common name on the certificate associated |
| 2082 | | with the client linked to this address. Only present for "add" |
| 2083 | | or "update" operations, not "delete". |
| 2084 | | |
| 2085 | | On "add" or "update" methods, if the script returns a failure |
| 2086 | | code (non-zero), OpenVPN will reject the address and will not |
| 2087 | | modify its internal routing table. |
| 2088 | | |
| 2089 | | Normally, the cmd script will use the information provided above |
| 2090 | | to set appropriate firewall entries on the VPN TUN/TAP inter‐ |
| 2091 | | face. Since OpenVPN provides the association between virtual IP |
| 2092 | | or MAC address and the client's authenticated common name, it |
| 2093 | | allows a user-defined script to configure firewall access poli‐ |
| 2094 | | cies with regard to the client's high-level common name, rather |
| 2095 | | than the low level client virtual addresses. |
| | 2014 | [1] operation -- "add", "update", or "delete" based on whether or |
| | 2015 | not the address is being added to, modified, or deleted from Open‐ |
| | 2016 | VPN's internal routing table. |
| | 2017 | [2] address -- The address being learned or unlearned. This can be |
| | 2018 | an IPv4 address such as "198.162.10.14", an IPv4 subnet such as |
| | 2019 | "198.162.10.0/24", or an ethernet MAC address (when --dev tap is |
| | 2020 | being used) such as "00:FF:01:02:03:04". |
| | 2021 | [3] common name -- The common name on the certificate associated |
| | 2022 | with the client linked to this address. Only present for "add" or |
| | 2023 | "update" operations, not "delete". |
| | 2024 | |
| | 2025 | On "add" or "update" methods, if the script returns a failure code |
| | 2026 | (non-zero), OpenVPN will reject the address and will not modify its |
| | 2027 | internal routing table. |
| | 2028 | |
| | 2029 | Normally, the cmd script will use the information provided above to |
| | 2030 | set appropriate firewall entries on the VPN TUN/TAP interface. |
| | 2031 | Since OpenVPN provides the association between virtual IP or MAC |
| | 2032 | address and the client's authenticated common name, it allows a |
| | 2033 | user-defined script to configure firewall access policies with |
| | 2034 | regard to the client's high-level common name, rather than the low |
| | 2035 | level client virtual addresses. |
| 2101 | | OpenVPN will run command cmd to validate the username/password |
| 2102 | | provided by the client. |
| 2103 | | |
| 2104 | | cmd consists of a path to script (or executable program), |
| 2105 | | optionally followed by arguments. The path and arguments may be |
| 2106 | | single- or double-quoted and/or escaped using a backslash, and |
| 2107 | | should be separated by one or more spaces. |
| 2108 | | |
| 2109 | | If method is set to "via-env", OpenVPN will call script with the |
| 2110 | | environmental variables username and password set to the user‐ |
| 2111 | | name/password strings provided by the client. Be aware that |
| 2112 | | this method is insecure on some platforms which make the envi‐ |
| 2113 | | ronment of a process publicly visible to other unprivileged pro‐ |
| 2114 | | cesses. |
| 2115 | | |
| 2116 | | If method is set to "via-file", OpenVPN will write the username |
| 2117 | | and password to the first two lines of a temporary file. The |
| 2118 | | filename will be passed as an argument to script, and the file |
| 2119 | | will be automatically deleted by OpenVPN after the script |
| 2120 | | returns. The location of the temporary file is controlled by |
| 2121 | | the --tmp-dir option, and will default to the current directory |
| 2122 | | if unspecified. For security, consider setting --tmp-dir to a |
| 2123 | | volatile storage medium such as /dev/shm (if available) to pre‐ |
| 2124 | | vent the username/password file from touching the hard drive. |
| 2125 | | |
| 2126 | | The script should examine the username and password, returning a |
| 2127 | | success exit code (0) if the client's authentication request is |
| 2128 | | to be accepted, or a failure code (1) to reject the client. |
| 2129 | | |
| 2130 | | This directive is designed to enable a plugin-style interface |
| 2131 | | for extending OpenVPN's authentication capabilities. |
| 2132 | | |
| 2133 | | To protect against a client passing a maliciously formed user‐ |
| 2134 | | name or password string, the username string must consist only |
| 2135 | | of these characters: alphanumeric, underbar ('_'), dash ('-'), |
| 2136 | | dot ('.'), or at ('@'). The password string can consist of any |
| 2137 | | printable characters except for CR or LF. Any illegal charac‐ |
| 2138 | | ters in either the username or password string will be converted |
| 2139 | | to underbar ('_'). |
| 2140 | | |
| 2141 | | Care must be taken by any user-defined scripts to avoid creating |
| 2142 | | a security vulnerability in the way that these strings are han‐ |
| 2143 | | dled. Never use these strings in such a way that they might be |
| 2144 | | escaped or evaluated by a shell interpreter. |
| 2145 | | |
| 2146 | | For a sample script that performs PAM authentication, see sam‐ |
| 2147 | | ple-scripts/auth-pam.pl in the OpenVPN source distribution. |
| | 2041 | OpenVPN will run command cmd to validate the username/password pro‐ |
| | 2042 | vided by the client. |
| | 2043 | |
| | 2044 | cmd consists of a path to script (or executable program), option‐ |
| | 2045 | ally followed by arguments. The path and arguments may be single- |
| | 2046 | or double-quoted and/or escaped using a backslash, and should be |
| | 2047 | separated by one or more spaces. |
| | 2048 | |
| | 2049 | If method is set to "via-env", OpenVPN will call script with the |
| | 2050 | environmental variables username and password set to the user‐ |
| | 2051 | name/password strings provided by the client. Be aware that this |
| | 2052 | method is insecure on some platforms which make the environment of |
| | 2053 | a process publicly visible to other unprivileged processes. |
| | 2054 | |
| | 2055 | If method is set to "via-file", OpenVPN will write the username and |
| | 2056 | password to the first two lines of a temporary file. The filename |
| | 2057 | will be passed as an argument to script, and the file will be auto‐ |
| | 2058 | matically deleted by OpenVPN after the script returns. The loca‐ |
| | 2059 | tion of the temporary file is controlled by the --tmp-dir option, |
| | 2060 | and will default to the current directory if unspecified. For |
| | 2061 | security, consider setting --tmp-dir to a volatile storage medium |
| | 2062 | such as /dev/shm (if available) to prevent the username/password |
| | 2063 | file from touching the hard drive. |
| | 2064 | |
| | 2065 | The script should examine the username and password, returning a |
| | 2066 | success exit code (0) if the client's authentication request is to |
| | 2067 | be accepted, or a failure code (1) to reject the client. |
| | 2068 | |
| | 2069 | This directive is designed to enable a plugin-style interface for |
| | 2070 | extending OpenVPN's authentication capabilities. |
| | 2071 | |
| | 2072 | To protect against a client passing a maliciously formed username |
| | 2073 | or password string, the username string must consist only of these |
| | 2074 | characters: alphanumeric, underbar ('_'), dash ('-'), dot ('.'), or |
| | 2075 | at ('@'). The password string can consist of any printable charac‐ |
| | 2076 | ters except for CR or LF. Any illegal characters in either the |
| | 2077 | username or password string will be converted to underbar ('_'). |
| | 2078 | |
| | 2079 | Care must be taken by any user-defined scripts to avoid creating a |
| | 2080 | security vulnerability in the way that these strings are handled. |
| | 2081 | Never use these strings in such a way that they might be escaped or |
| | 2082 | evaluated by a shell interpreter. |
| | 2083 | |
| | 2084 | For a sample script that performs PAM authentication, see sample- |
| | 2085 | scripts/auth-pam.pl in the OpenVPN source distribution. |
| 2150 | | Clients that connect with options that are incompatible with |
| 2151 | | those of the server will be disconnected. |
| 2152 | | |
| 2153 | | Options that will be compared for compatibility include dev- |
| 2154 | | type, link-mtu, tun-mtu, proto, tun-ipv6, ifconfig, comp-lzo, |
| 2155 | | fragment, keydir, cipher, auth, keysize, secret, no-replay, no- |
| 2156 | | iv, tls-auth, key-method, tls-server, and tls-client. |
| | 2088 | Clients that connect with options that are incompatible with those |
| | 2089 | of the server will be disconnected. |
| | 2090 | |
| | 2091 | Options that will be compared for compatibility include dev-type, |
| | 2092 | link-mtu, tun-mtu, proto, tun-ipv6, ifconfig, comp-lzo, fragment, |
| | 2093 | keydir, cipher, auth, keysize, secret, no-replay, no-iv, tls-auth, |
| | 2094 | key-method, tls-server, and tls-client. |
| 2161 | | Allow connections by clients that do not specify a user‐ |
| 2162 | | name/password. Normally, when --auth-user-pass-verify or --man‐ |
| 2163 | | agement-client-auth is specified (or an authentication plugin |
| 2164 | | module), the OpenVPN server daemon will require connecting |
| 2165 | | clients to specify a username and password. This option makes |
| 2166 | | the submission of a username/password by clients optional, pass‐ |
| 2167 | | ing the responsibility to the user-defined authentication mod‐ |
| 2168 | | ule/script to accept or deny the client based on other factors |
| 2169 | | (such as the setting of X509 certificate fields). When this |
| 2170 | | option is used, and a connecting client does not submit a user‐ |
| 2171 | | name/password, the user-defined authentication module/script |
| 2172 | | will see the username and password as being set to empty strings |
| 2173 | | (""). The authentication module/script MUST have logic to |
| 2174 | | detect this condition and respond accordingly. |
| | 2099 | Allow connections by clients that do not specify a username/pass‐ |
| | 2100 | word. Normally, when --auth-user-pass-verify or --management- |
| | 2101 | client-auth is specified (or an authentication plugin module), the |
| | 2102 | OpenVPN server daemon will require connecting clients to specify a |
| | 2103 | username and password. This option makes the submission of a user‐ |
| | 2104 | name/password by clients optional, passing the responsibility to |
| | 2105 | the user-defined authentication module/script to accept or deny the |
| | 2106 | client based on other factors (such as the setting of X509 certifi‐ |
| | 2107 | cate fields). When this option is used, and a connecting client |
| | 2108 | does not submit a username/password, the user-defined authentica‐ |
| | 2109 | tion module/script will see the username and password as being set |
| | 2110 | to empty strings (""). The authentication module/script MUST have |
| | 2111 | logic to detect this condition and respond accordingly. |
| 2177 | | Don't require client certificate, client will authenticate using |
| 2178 | | username/password only. Be aware that using this directive is |
| 2179 | | less secure than requiring certificates from all clients. |
| 2180 | | |
| 2181 | | If you use this directive, the entire responsibility of authen‐ |
| 2182 | | tication will rest on your --auth-user-pass-verify script, so |
| 2183 | | keep in mind that bugs in your script could potentially compro‐ |
| 2184 | | mise the security of your VPN. |
| 2185 | | |
| 2186 | | If you don't use this directive, but you also specify an --auth- |
| 2187 | | user-pass-verify script, then OpenVPN will perform double |
| 2188 | | authentication. The client certificate verification AND the |
| 2189 | | --auth-user-pass-verify script will need to succeed in order for |
| 2190 | | a client to be authenticated and accepted onto the VPN. |
| | 2114 | Don't require client certificate, client will authenticate using |
| | 2115 | username/password only. Be aware that using this directive is less |
| | 2116 | secure than requiring certificates from all clients. |
| | 2117 | |
| | 2118 | If you use this directive, the entire responsibility of authentica‐ |
| | 2119 | tion will rest on your --auth-user-pass-verify script, so keep in |
| | 2120 | mind that bugs in your script could potentially compromise the |
| | 2121 | security of your VPN. |
| | 2122 | |
| | 2123 | If you don't use this directive, but you also specify an --auth- |
| | 2124 | user-pass-verify script, then OpenVPN will perform double authenti‐ |
| | 2125 | cation. The client certificate verification AND the --auth-user- |
| | 2126 | pass-verify script will need to succeed in order for a client to be |
| | 2127 | authenticated and accepted onto the VPN. |
| 2203 | | In addition the old behavivour was to remap any character other |
| 2204 | | than alphanumeric, underscore ('_'), dash ('-'), dot ('.'), and |
| 2205 | | slash ('/') to underscore ('_'). The X.509 Subject string as |
| 2206 | | returned by the tls_id environmental variable, could addition‐ |
| 2207 | | ally contain colon (':') or equal ('='). |
| 2208 | | |
| 2209 | | When using the --compat-names option, this old formatting and |
| 2210 | | remapping will be re-enabled again. This is purely implemented |
| 2211 | | for compatibility reasons when using older plug-ins or scripts |
| 2212 | | which does not handle the new formatting or UTF-8 characters. |
| 2213 | | |
| 2214 | | In OpenVPN v2.3 the formatting of these fields changed into a |
| 2215 | | more standardised format. It now looks like: |
| | 2140 | In addition the old behavivour was to remap any character other |
| | 2141 | than alphanumeric, underscore ('_'), dash ('-'), dot ('.'), and |
| | 2142 | slash ('/') to underscore ('_'). The X.509 Subject string as |
| | 2143 | returned by the tls_id environmental variable, could additionally |
| | 2144 | contain colon (':') or equal ('='). |
| | 2145 | |
| | 2146 | When using the --compat-names option, this old formatting and |
| | 2147 | remapping will be re-enabled again. This is purely implemented for |
| | 2148 | compatibility reasons when using older plug-ins or scripts which |
| | 2149 | does not handle the new formatting or UTF-8 characters. |
| | 2150 | |
| | 2151 | In OpenVPN v2.3 the formatting of these fields changed into a more |
| | 2152 | standardised format. It now looks like: |
| 2219 | | The new default format in OpenVPN v2.3 also does not do the |
| 2220 | | character remapping which happened earlier. This new format |
| 2221 | | enables proper support for UTF-8 characters in the usernames, |
| 2222 | | X.509 Subject fields and Common Name variables and it complies |
| 2223 | | to the RFC 2253, UTF-8 String Representation of Distinguished |
| 2224 | | Names. |
| 2225 | | |
| 2226 | | As a backwards compatibility for the removed --no-name-remapping |
| 2227 | | feature in older OpenVPN versions, the no-remapping mode flag |
| 2228 | | can be used with the --compat-names option. When this mode flag |
| 2229 | | is used, the Common Name, Subject, and username strings are |
| 2230 | | allowed to include any printable character including space, but |
| 2231 | | excluding control characters such as tab, newline, and carriage- |
| 2232 | | return. It ensures compatibility with the --no-name-remapping |
| 2233 | | option of OpenVPN versions before v2.3. |
| 2234 | | |
| 2235 | | Please note: This option will not be around for a long time. It |
| 2236 | | is only implemented to make the transition to the new formatting |
| 2237 | | less intrusive. It will be removed either in OpenVPN v2.4 or |
| 2238 | | v2.5. So please make sure you start the process to support the |
| 2239 | | new formatting as soon as possible. |
| | 2156 | The new default format in OpenVPN v2.3 also does not do the charac‐ |
| | 2157 | ter remapping which happened earlier. This new format enables |
| | 2158 | proper support for UTF-8 characters in the usernames, X.509 Subject |
| | 2159 | fields and Common Name variables and it complies to the RFC 2253, |
| | 2160 | UTF-8 String Representation of Distinguished Names. |
| | 2161 | |
| | 2162 | The no-remapping mode flag can be used with the --compat-names |
| | 2163 | option to be compatible with the now deprecated --no-name-remapping |
| | 2164 | option. It is only available at the server. When this mode flag is |
| | 2165 | used, the Common Name, Subject, and username strings are allowed to |
| | 2166 | include any printable character including space, but excluding con‐ |
| | 2167 | trol characters such as tab, newline, and carriage-return. no- |
| | 2168 | remapping is only available on the server side. |
| | 2169 | |
| | 2170 | Please note: This option is immediately deprecated. It is only |
| | 2171 | implemented to make the transition to the new formatting less |
| | 2172 | intrusive. It will be removed either in OpenVPN v2.4 or v2.5. So |
| | 2173 | please make sure you use the --verify-x509-name option instead of |
| | 2174 | --tls-remote as soon as possible and update your scripts where nec‐ |
| | 2175 | essary. |
| | 2176 | |
| | 2177 | --no-name-remapping (DEPRECATED) |
| | 2178 | The --no-name-remapping option is an alias for --com‐ |
| | 2179 | pat-names no-remapping. It ensures compatibility with server con‐ |
| | 2180 | figurations using the --no-name-remapping option. |
| | 2181 | |
| | 2182 | Please note: This option is now deprecated. It will be removed |
| | 2183 | either in OpenVPN v2.4 or v2.5. So please make sure you support |
| | 2184 | the new X.509 name formatting described with the --compat-names |
| | 2185 | option as soon as possible. |
| 2242 | | When run in TCP server mode, share the OpenVPN port with another |
| 2243 | | application, such as an HTTPS server. If OpenVPN senses a con‐ |
| 2244 | | nection to its port which is using a non-OpenVPN protocol, it |
| 2245 | | will proxy the connection to the server at host:port. Currently |
| 2246 | | only designed to work with HTTP/HTTPS, though it would be theo‐ |
| 2247 | | retically possible to extend to other protocols such as ssh. |
| 2248 | | |
| 2249 | | dir specifies an optional directory where a temporary file with |
| 2250 | | name N containing content C will be dynamically generated for |
| 2251 | | each proxy connection, where N is the source IP:port of the |
| 2252 | | client connection and C is the source IP:port of the connection |
| 2253 | | to the proxy receiver. This directory can be used as a dictio‐ |
| 2254 | | nary by the proxy receiver to determine the origin of the con‐ |
| 2255 | | nection. Each generated file will be automatically deleted when |
| 2256 | | the proxied connection is torn down. |
| | 2188 | When run in TCP server mode, share the OpenVPN port with another |
| | 2189 | application, such as an HTTPS server. If OpenVPN senses a connec‐ |
| | 2190 | tion to its port which is using a non-OpenVPN protocol, it will |
| | 2191 | proxy the connection to the server at host:port. Currently only |
| | 2192 | designed to work with HTTP/HTTPS, though it would be theoretically |
| | 2193 | possible to extend to other protocols such as ssh. |
| | 2194 | |
| | 2195 | dir specifies an optional directory where a temporary file with |
| | 2196 | name N containing content C will be dynamically generated for each |
| | 2197 | proxy connection, where N is the source IP:port of the client con‐ |
| | 2198 | nection and C is the source IP:port of the connection to the proxy |
| | 2199 | receiver. This directory can be used as a dictionary by the proxy |
| | 2200 | receiver to determine the origin of the connection. Each generated |
| | 2201 | file will be automatically deleted when the proxied connection is |
| | 2202 | torn down. |
| 2271 | | --pull This option must be used on a client which is connecting to a |
| 2272 | | multi-client server. It indicates to OpenVPN that it should |
| 2273 | | accept options pushed by the server, provided they are part of |
| 2274 | | the legal set of pushable options (note that the --pull option |
| 2275 | | is implied by --client ). |
| 2276 | | |
| 2277 | | In particular, --pull allows the server to push routes to the |
| 2278 | | client, so you should not use --pull or --client in situations |
| 2279 | | where you don't trust the server to have control over the |
| 2280 | | client's routing table. |
| | 2217 | --pull This option must be used on a client which is connecting to a |
| | 2218 | multi-client server. It indicates to OpenVPN that it should accept |
| | 2219 | options pushed by the server, provided they are part of the legal |
| | 2220 | set of pushable options (note that the --pull option is implied by |
| | 2221 | --client ). |
| | 2222 | |
| | 2223 | In particular, --pull allows the server to push routes to the |
| | 2224 | client, so you should not use --pull or --client in situations |
| | 2225 | where you don't trust the server to have control over the client's |
| | 2226 | routing table. |
| 2296 | | Controls how OpenVPN responds to username/password verification |
| 2297 | | errors such as the client-side response to an AUTH_FAILED mes‐ |
| 2298 | | sage from the server or verification failure of the private key |
| 2299 | | password. |
| 2300 | | |
| 2301 | | Normally used to prevent auth errors from being fatal on the |
| 2302 | | client side, and to permit username/password requeries in case |
| 2303 | | of error. |
| 2304 | | |
| 2305 | | An AUTH_FAILED message is generated by the server if the client |
| 2306 | | fails --auth-user-pass authentication, or if the server-side |
| 2307 | | --client-connect script returns an error status when the client |
| | 2242 | Controls how OpenVPN responds to username/password verification |
| | 2243 | errors such as the client-side response to an AUTH_FAILED message |
| | 2244 | from the server or verification failure of the private key pass‐ |
| | 2245 | word. |
| | 2246 | |
| | 2247 | Normally used to prevent auth errors from being fatal on the client |
| | 2248 | side, and to permit username/password requeries in case of error. |
| | 2249 | |
| | 2250 | An AUTH_FAILED message is generated by the server if the client |
| | 2251 | fails --auth-user-pass authentication, or if the server-side |
| | 2252 | --client-connect script returns an error status when the client |
| 2340 | | In UDP client mode or point-to-point mode, send server/peer an |
| 2341 | | exit notification if tunnel is restarted or OpenVPN process is |
| 2342 | | exited. In client mode, on exit/restart, this option will tell |
| 2343 | | the server to immediately close its client instance object |
| 2344 | | rather than waiting for a timeout. The n parameter (default=1) |
| 2345 | | controls the maximum number of attempts that the client will try |
| 2346 | | to resend the exit notification message. OpenVPN will not send |
| 2347 | | any exit notifications unless this option is enabled. |
| | 2284 | In UDP client mode or point-to-point mode, send server/peer an exit |
| | 2285 | notification if tunnel is restarted or OpenVPN process is exited. |
| | 2286 | In client mode, on exit/restart, this option will tell the server |
| | 2287 | to immediately close its client instance object rather than waiting |
| | 2288 | for a timeout. The n parameter (default=1) controls the maximum |
| | 2289 | number of attempts that the client will try to resend the exit |
| | 2290 | notification message. OpenVPN will not send any exit notifications |
| | 2291 | unless this option is enabled. |
| 2354 | | Enable Static Key encryption mode (non-TLS). Use pre-shared |
| 2355 | | secret file which was generated with --genkey. |
| 2356 | | |
| 2357 | | The optional direction parameter enables the use of 4 distinct |
| 2358 | | keys (HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), |
| 2359 | | so that each data flow direction has a different set of HMAC and |
| 2360 | | cipher keys. This has a number of desirable security properties |
| 2361 | | including eliminating certain kinds of DoS and message replay |
| 2362 | | attacks. |
| 2363 | | |
| 2364 | | When the direction parameter is omitted, 2 keys are used bidi‐ |
| 2365 | | rectionally, one for HMAC and the other for encryption/decryp‐ |
| 2366 | | tion. |
| 2367 | | |
| 2368 | | The direction parameter should always be complementary on either |
| 2369 | | side of the connection, i.e. one side should use "0" and the |
| 2370 | | other should use "1", or both sides should omit it altogether. |
| 2371 | | |
| 2372 | | The direction parameter requires that file contains a 2048 bit |
| 2373 | | key. While pre-1.5 versions of OpenVPN generate 1024 bit key |
| 2374 | | files, any version of OpenVPN which supports the direction |
| 2375 | | parameter, will also support 2048 bit key file generation using |
| 2376 | | the --genkey option. |
| 2377 | | |
| 2378 | | Static key encryption mode has certain advantages, the primary |
| | 2298 | Enable Static Key encryption mode (non-TLS). Use pre-shared secret |
| | 2299 | file which was generated with --genkey. |
| | 2300 | |
| | 2301 | The optional direction parameter enables the use of 4 distinct keys |
| | 2302 | (HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that |
| | 2303 | each data flow direction has a different set of HMAC and cipher |
| | 2304 | keys. This has a number of desirable security properties including |
| | 2305 | eliminating certain kinds of DoS and message replay attacks. |
| | 2306 | |
| | 2307 | When the direction parameter is omitted, 2 keys are used bidirec‐ |
| | 2308 | tionally, one for HMAC and the other for encryption/decryption. |
| | 2309 | |
| | 2310 | The direction parameter should always be complementary on either |
| | 2311 | side of the connection, i.e. one side should use "0" and the other |
| | 2312 | should use "1", or both sides should omit it altogether. |
| | 2313 | |
| | 2314 | The direction parameter requires that file contains a 2048 bit key. |
| | 2315 | While pre-1.5 versions of OpenVPN generate 1024 bit key files, any |
| | 2316 | version of OpenVPN which supports the direction parameter, will |
| | 2317 | also support 2048 bit key file generation using the --genkey |
| | 2318 | option. |
| | 2319 | |
| | 2320 | Static key encryption mode has certain advantages, the primary |
| 2381 | | There are no certificates or certificate authorities or compli‐ |
| 2382 | | cated negotiation handshakes and protocols. The only require‐ |
| 2383 | | ment is that you have a pre-existing secure channel with your |
| 2384 | | peer (such as ssh ) to initially copy the key. This require‐ |
| 2385 | | ment, along with the fact that your key never changes unless you |
| 2386 | | manually generate a new one, makes it somewhat less secure than |
| 2387 | | TLS mode (see below). If an attacker manages to steal your key, |
| 2388 | | everything that was ever encrypted with it is compromised. Con‐ |
| 2389 | | trast that to the perfect forward secrecy features of TLS mode |
| 2390 | | (using Diffie Hellman key exchange), where even if an attacker |
| 2391 | | was able to steal your private key, he would gain no information |
| 2392 | | to help him decrypt past sessions. |
| 2393 | | |
| 2394 | | Another advantageous aspect of Static Key encryption mode is |
| 2395 | | that it is a handshake-free protocol without any distinguishing |
| 2396 | | signature or feature (such as a header or protocol handshake |
| 2397 | | sequence) that would mark the ciphertext packets as being gener‐ |
| 2398 | | ated by OpenVPN. Anyone eavesdropping on the wire would see |
| 2399 | | nothing but random-looking data. |
| | 2323 | There are no certificates or certificate authorities or complicated |
| | 2324 | negotiation handshakes and protocols. The only requirement is that |
| | 2325 | you have a pre-existing secure channel with your peer (such as ssh |
| | 2326 | ) to initially copy the key. This requirement, along with the fact |
| | 2327 | that your key never changes unless you manually generate a new one, |
| | 2328 | makes it somewhat less secure than TLS mode (see below). If an |
| | 2329 | attacker manages to steal your key, everything that was ever |
| | 2330 | encrypted with it is compromised. Contrast that to the perfect |
| | 2331 | forward secrecy features of TLS mode (using Diffie Hellman key |
| | 2332 | exchange), where even if an attacker was able to steal your private |
| | 2333 | key, he would gain no information to help him decrypt past ses‐ |
| | 2334 | sions. |
| | 2335 | |
| | 2336 | Another advantageous aspect of Static Key encryption mode is that |
| | 2337 | it is a handshake-free protocol without any distinguishing signa‐ |
| | 2338 | ture or feature (such as a header or protocol handshake sequence) |
| | 2339 | that would mark the ciphertext packets as being generated by Open‐ |
| | 2340 | VPN. Anyone eavesdropping on the wire would see nothing but ran‐ |
| | 2341 | dom-looking data. |
| 2407 | | Authenticate packets with HMAC using message digest algorithm |
| 2408 | | alg. (The default is SHA1 ). HMAC is a commonly used message |
| 2409 | | authentication algorithm (MAC) that uses a data string, a secure |
| 2410 | | hash algorithm, and a key, to produce a digital signature. |
| 2411 | | |
| 2412 | | OpenVPN's usage of HMAC is to first encrypt a packet, then HMAC |
| 2413 | | the resulting ciphertext. |
| 2414 | | |
| 2415 | | In static-key encryption mode, the HMAC key is included in the |
| 2416 | | key file generated by --genkey. In TLS mode, the HMAC key is |
| 2417 | | dynamically generated and shared between peers via the TLS con‐ |
| 2418 | | trol channel. If OpenVPN receives a packet with a bad HMAC it |
| 2419 | | will drop the packet. HMAC usually adds 16 or 20 bytes per |
| 2420 | | packet. Set alg=none to disable authentication. |
| 2421 | | |
| 2422 | | For more information on HMAC see |
| | 2349 | Authenticate packets with HMAC using message digest algorithm alg. |
| | 2350 | (The default is SHA1 ). HMAC is a commonly used message authenti‐ |
| | 2351 | cation algorithm (MAC) that uses a data string, a secure hash algo‐ |
| | 2352 | rithm, and a key, to produce a digital signature. |
| | 2353 | |
| | 2354 | OpenVPN's usage of HMAC is to first encrypt a packet, then HMAC the |
| | 2355 | resulting ciphertext. |
| | 2356 | |
| | 2357 | In static-key encryption mode, the HMAC key is included in the key |
| | 2358 | file generated by --genkey. In TLS mode, the HMAC key is dynami‐ |
| | 2359 | cally generated and shared between peers via the TLS control chan‐ |
| | 2360 | nel. If OpenVPN receives a packet with a bad HMAC it will drop the |
| | 2361 | packet. HMAC usually adds 16 or 20 bytes per packet. Set alg=none |
| | 2362 | to disable authentication. |
| | 2363 | |
| | 2364 | For more information on HMAC see |
| 2445 | | Size of cipher key in bits (optional). If unspecified, defaults |
| 2446 | | to cipher-specific default. The --show-ciphers option (see |
| 2447 | | below) shows all available OpenSSL ciphers, their default key |
| 2448 | | sizes, and whether the key size can be changed. Use care in |
| 2449 | | changing a cipher's default key size. Many ciphers have not |
| 2450 | | been extensively cryptanalyzed with non-standard key lengths, |
| 2451 | | and a larger key may offer no real guarantee of greater secu‐ |
| 2452 | | rity, or may even reduce security. |
| | 2386 | Size of cipher key in bits (optional). If unspecified, defaults to |
| | 2387 | cipher-specific default. The --show-ciphers option (see below) |
| | 2388 | shows all available OpenSSL ciphers, their default key sizes, and |
| | 2389 | whether the key size can be changed. Use care in changing a |
| | 2390 | cipher's default key size. Many ciphers have not been extensively |
| | 2391 | cryptanalyzed with non-standard key lengths, and a larger key may |
| | 2392 | offer no real guarantee of greater security, or may even reduce |
| | 2393 | security. |
| 2477 | | Replay protection is accomplished by tagging each outgoing data‐ |
| 2478 | | gram with an identifier that is guaranteed to be unique for the |
| 2479 | | key being used. The peer that receives the datagram will check |
| 2480 | | for the uniqueness of the identifier. If the identifier was |
| 2481 | | already received in a previous datagram, OpenVPN will drop the |
| 2482 | | packet. Replay protection is important to defeat attacks such |
| 2483 | | as a SYN flood attack, where the attacker listens in the wire, |
| 2484 | | intercepts a TCP SYN packet (identifying it by the context in |
| 2485 | | which it occurs in relation to other packets), then floods the |
| 2486 | | receiving peer with copies of this packet. |
| 2487 | | |
| 2488 | | OpenVPN's replay protection is implemented in slightly different |
| | 2417 | Replay protection is accomplished by tagging each outgoing datagram |
| | 2418 | with an identifier that is guaranteed to be unique for the key |
| | 2419 | being used. The peer that receives the datagram will check for the |
| | 2420 | uniqueness of the identifier. If the identifier was already |
| | 2421 | received in a previous datagram, OpenVPN will drop the packet. |
| | 2422 | Replay protection is important to defeat attacks such as a SYN |
| | 2423 | flood attack, where the attacker listens in the wire, intercepts a |
| | 2424 | TCP SYN packet (identifying it by the context in which it occurs in |
| | 2425 | relation to other packets), then floods the receiving peer with |
| | 2426 | copies of this packet. |
| | 2427 | |
| | 2428 | OpenVPN's replay protection is implemented in slightly different |
| 2491 | | In Static Key mode or when using an CFB or OFB mode cipher, |
| 2492 | | OpenVPN uses a 64 bit unique identifier that combines a time |
| 2493 | | stamp with an incrementing sequence number. |
| 2494 | | |
| 2495 | | When using TLS mode for key exchange and a CBC cipher mode, |
| 2496 | | OpenVPN uses only a 32 bit sequence number without a time stamp, |
| 2497 | | since OpenVPN can guarantee the uniqueness of this value for |
| 2498 | | each key. As in IPSec, if the sequence number is close to wrap‐ |
| 2499 | | ping back to zero, OpenVPN will trigger a new key exchange. |
| 2500 | | |
| 2501 | | To check for replays, OpenVPN uses the sliding window algorithm |
| | 2431 | In Static Key mode or when using an CFB or OFB mode cipher, OpenVPN |
| | 2432 | uses a 64 bit unique identifier that combines a time stamp with an |
| | 2433 | incrementing sequence number. |
| | 2434 | |
| | 2435 | When using TLS mode for key exchange and a CBC cipher mode, OpenVPN |
| | 2436 | uses only a 32 bit sequence number without a time stamp, since |
| | 2437 | OpenVPN can guarantee the uniqueness of this value for each key. |
| | 2438 | As in IPSec, if the sequence number is close to wrapping back to |
| | 2439 | zero, OpenVPN will trigger a new key exchange. |
| | 2440 | |
| | 2441 | To check for replays, OpenVPN uses the sliding window algorithm |
| 2510 | | This option is only relevant in UDP mode, i.e. when either |
| 2511 | | --proto udp is specifed, or no --proto option is specified. |
| 2512 | | |
| 2513 | | When OpenVPN tunnels IP packets over UDP, there is the possibil‐ |
| 2514 | | ity that packets might be dropped or delivered out of order. |
| 2515 | | Because OpenVPN, like IPSec, is emulating the physical network |
| 2516 | | layer, it will accept an out-of-order packet sequence, and will |
| 2517 | | deliver such packets in the same order they were received to the |
| 2518 | | TCP/IP protocol stack, provided they satisfy several con‐ |
| 2519 | | straints. |
| 2520 | | |
| 2521 | | (a) The packet cannot be a replay (unless --no-replay is speci‐ |
| 2522 | | fied, which disables replay protection altogether). |
| 2523 | | |
| 2524 | | (b) If a packet arrives out of order, it will only be accepted |
| 2525 | | if the difference between its sequence number and the highest |
| 2526 | | sequence number received so far is less than n. |
| 2527 | | |
| 2528 | | (c) If a packet arrives out of order, it will only be accepted |
| 2529 | | if it arrives no later than t seconds after any packet contain‐ |
| 2530 | | ing a higher sequence number. |
| 2531 | | |
| 2532 | | If you are using a network link with a large pipeline (meaning |
| 2533 | | that the product of bandwidth and latency is high), you may want |
| 2534 | | to use a larger value for n. Satellite links in particular |
| 2535 | | often require this. |
| 2536 | | |
| 2537 | | If you run OpenVPN at --verb 4, you will see the message |
| 2538 | | "Replay-window backtrack occurred [x]" every time the maximum |
| 2539 | | sequence number backtrack seen thus far increases. This can be |
| 2540 | | used to calibrate n. |
| 2541 | | |
| 2542 | | There is some controversy on the appropriate method of handling |
| | 2450 | This option is only relevant in UDP mode, i.e. when either --proto |
| | 2451 | udp is specifed, or no --proto option is specified. |
| | 2452 | |
| | 2453 | When OpenVPN tunnels IP packets over UDP, there is the possibility |
| | 2454 | that packets might be dropped or delivered out of order. Because |
| | 2455 | OpenVPN, like IPSec, is emulating the physical network layer, it |
| | 2456 | will accept an out-of-order packet sequence, and will deliver such |
| | 2457 | packets in the same order they were received to the TCP/IP protocol |
| | 2458 | stack, provided they satisfy several constraints. |
| | 2459 | |
| | 2460 | (a) The packet cannot be a replay (unless --no-replay is specified, |
| | 2461 | which disables replay protection altogether). |
| | 2462 | |
| | 2463 | (b) If a packet arrives out of order, it will only be accepted if |
| | 2464 | the difference between its sequence number and the highest sequence |
| | 2465 | number received so far is less than n. |
| | 2466 | |
| | 2467 | (c) If a packet arrives out of order, it will only be accepted if |
| | 2468 | it arrives no later than t seconds after any packet containing a |
| | 2469 | higher sequence number. |
| | 2470 | |
| | 2471 | If you are using a network link with a large pipeline (meaning that |
| | 2472 | the product of bandwidth and latency is high), you may want to use |
| | 2473 | a larger value for n. Satellite links in particular often require |
| | 2474 | this. |
| | 2475 | |
| | 2476 | If you run OpenVPN at --verb 4, you will see the message "Replay- |
| | 2477 | window backtrack occurred [x]" every time the maximum sequence num‐ |
| | 2478 | ber backtrack seen thus far increases. This can be used to cali‐ |
| | 2479 | brate n. |
| | 2480 | |
| | 2481 | There is some controversy on the appropriate method of handling |
| 2545 | | Namely, to what extent should the security layer protect the |
| 2546 | | encapsulated protocol from attacks which masquerade as the kinds |
| 2547 | | of normal packet loss and reordering that occur over IP net‐ |
| 2548 | | works? |
| 2549 | | |
| 2550 | | The IPSec and OpenVPN approach is to allow packet reordering |
| 2551 | | within a certain fixed sequence number window. |
| 2552 | | |
| 2553 | | OpenVPN adds to the IPSec model by limiting the window size in |
| 2554 | | time as well as sequence space. |
| 2555 | | |
| 2556 | | OpenVPN also adds TCP transport as an option (not offered by |
| 2557 | | IPSec) in which case OpenVPN can adopt a very strict attitude |
| 2558 | | towards message deletion and reordering: Don't allow it. Since |
| 2559 | | TCP guarantees reliability, any packet loss or reordering event |
| 2560 | | can be assumed to be an attack. |
| 2561 | | |
| 2562 | | In this sense, it could be argued that TCP tunnel transport is |
| 2563 | | preferred when tunneling non-IP or UDP application protocols |
| 2564 | | which might be vulnerable to a message deletion or reordering |
| 2565 | | attack which falls within the normal operational parameters of |
| 2566 | | IP networks. |
| 2567 | | |
| 2568 | | So I would make the statement that one should never tunnel a |
| 2569 | | non-IP protocol or UDP application protocol over UDP, if the |
| 2570 | | protocol might be vulnerable to a message deletion or reordering |
| 2571 | | attack that falls within the normal operating parameters of what |
| 2572 | | is to be expected from the physical IP layer. The problem is |
| 2573 | | easily fixed by simply using TCP as the VPN transport layer. |
| | 2484 | Namely, to what extent should the security layer protect the encap‐ |
| | 2485 | sulated protocol from attacks which masquerade as the kinds of nor‐ |
| | 2486 | mal packet loss and reordering that occur over IP networks? |
| | 2487 | |
| | 2488 | The IPSec and OpenVPN approach is to allow packet reordering within |
| | 2489 | a certain fixed sequence number window. |
| | 2490 | |
| | 2491 | OpenVPN adds to the IPSec model by limiting the window size in time |
| | 2492 | as well as sequence space. |
| | 2493 | |
| | 2494 | OpenVPN also adds TCP transport as an option (not offered by IPSec) |
| | 2495 | in which case OpenVPN can adopt a very strict attitude towards mes‐ |
| | 2496 | sage deletion and reordering: Don't allow it. Since TCP guaran‐ |
| | 2497 | tees reliability, any packet loss or reordering event can be |
| | 2498 | assumed to be an attack. |
| | 2499 | |
| | 2500 | In this sense, it could be argued that TCP tunnel transport is pre‐ |
| | 2501 | ferred when tunneling non-IP or UDP application protocols which |
| | 2502 | might be vulnerable to a message deletion or reordering attack |
| | 2503 | which falls within the normal operational parameters of IP net‐ |
| | 2504 | works. |
| | 2505 | |
| | 2506 | So I would make the statement that one should never tunnel a non-IP |
| | 2507 | protocol or UDP application protocol over UDP, if the protocol |
| | 2508 | might be vulnerable to a message deletion or reordering attack that |
| | 2509 | falls within the normal operating parameters of what is to be |
| | 2510 | expected from the physical IP layer. The problem is easily fixed |
| | 2511 | by simply using TCP as the VPN transport layer. |
| 2582 | | Persist replay-protection state across sessions using file to |
| 2583 | | save and reload the state. |
| 2584 | | |
| 2585 | | This option will strengthen protection against replay attacks, |
| 2586 | | especially when you are using OpenVPN in a dynamic context (such |
| 2587 | | as with --inetd) when OpenVPN sessions are frequently started |
| 2588 | | and stopped. |
| 2589 | | |
| 2590 | | This option will keep a disk copy of the current replay protec‐ |
| 2591 | | tion state (i.e. the most recent packet timestamp and sequence |
| 2592 | | number received from the remote peer), so that if an OpenVPN |
| 2593 | | session is stopped and restarted, it will reject any replays of |
| 2594 | | packets which were already received by the prior session. |
| 2595 | | |
| 2596 | | This option only makes sense when replay protection is enabled |
| 2597 | | (the default) and you are using either --secret (shared-secret |
| 2598 | | key mode) or TLS mode with --tls-auth. |
| | 2520 | Persist replay-protection state across sessions using file to save |
| | 2521 | and reload the state. |
| | 2522 | |
| | 2523 | This option will strengthen protection against replay attacks, |
| | 2524 | especially when you are using OpenVPN in a dynamic context (such as |
| | 2525 | with --inetd) when OpenVPN sessions are frequently started and |
| | 2526 | stopped. |
| | 2527 | |
| | 2528 | This option will keep a disk copy of the current replay protection |
| | 2529 | state (i.e. the most recent packet timestamp and sequence number |
| | 2530 | received from the remote peer), so that if an OpenVPN session is |
| | 2531 | stopped and restarted, it will reject any replays of packets which |
| | 2532 | were already received by the prior session. |
| | 2533 | |
| | 2534 | This option only makes sense when replay protection is enabled (the |
| | 2535 | default) and you are using either --secret (shared-secret key mode) |
| | 2536 | or TLS mode with --tls-auth. |
| 2654 | | TLS mode is the most powerful crypto mode of OpenVPN in both security |
| 2655 | | and flexibility. TLS mode works by establishing control and data chan‐ |
| 2656 | | nels which are multiplexed over a single TCP/UDP port. OpenVPN initi‐ |
| 2657 | | ates a TLS session over the control channel and uses it to exchange |
| 2658 | | cipher and HMAC keys to protect the data channel. TLS mode uses a |
| 2659 | | robust reliability layer over the UDP connection for all control chan‐ |
| 2660 | | nel communication, while the data channel, over which encrypted tunnel |
| 2661 | | data passes, is forwarded without any mediation. The result is the |
| 2662 | | best of both worlds: a fast data channel that forwards over UDP with |
| 2663 | | only the overhead of encrypt, decrypt, and HMAC functions, and a con‐ |
| 2664 | | trol channel that provides all of the security features of TLS, includ‐ |
| 2665 | | ing certificate-based authentication and Diffie Hellman forward |
| 2666 | | secrecy. |
| 2667 | | |
| 2668 | | To use TLS mode, each peer that runs OpenVPN should have its own local |
| 2669 | | certificate/key pair ( --cert and --key ), signed by the root certifi‐ |
| 2670 | | cate which is specified in --ca. |
| 2671 | | |
| 2672 | | When two OpenVPN peers connect, each presents its local certificate to |
| 2673 | | the other. Each peer will then check that its partner peer presented a |
| 2674 | | certificate which was signed by the master root certificate as speci‐ |
| 2675 | | fied in --ca. |
| 2676 | | |
| 2677 | | If that check on both peers succeeds, then the TLS negotiation will |
| 2678 | | succeed, both OpenVPN peers will exchange temporary session keys, and |
| 2679 | | the tunnel will begin passing data. |
| 2680 | | |
| 2681 | | The OpenVPN distribution contains a set of scripts for managing RSA |
| 2682 | | certificates & keys, located in the easy-rsa subdirectory. |
| 2683 | | |
| 2684 | | The easy-rsa package is also rendered in web form here: http://open‐ |
| | 2591 | TLS mode is the most powerful crypto mode of OpenVPN in both security and |
| | 2592 | flexibility. TLS mode works by establishing control and data channels |
| | 2593 | which are multiplexed over a single TCP/UDP port. OpenVPN initiates a TLS |
| | 2594 | session over the control channel and uses it to exchange cipher and HMAC |
| | 2595 | keys to protect the data channel. TLS mode uses a robust reliability |
| | 2596 | layer over the UDP connection for all control channel communication, while |
| | 2597 | the data channel, over which encrypted tunnel data passes, is forwarded |
| | 2598 | without any mediation. The result is the best of both worlds: a fast data |
| | 2599 | channel that forwards over UDP with only the overhead of encrypt, decrypt, |
| | 2600 | and HMAC functions, and a control channel that provides all of the secu‐ |
| | 2601 | rity features of TLS, including certificate-based authentication and |
| | 2602 | Diffie Hellman forward secrecy. |
| | 2603 | |
| | 2604 | To use TLS mode, each peer that runs OpenVPN should have its own local |
| | 2605 | certificate/key pair ( --cert and --key ), signed by the root certificate |
| | 2606 | which is specified in --ca. |
| | 2607 | |
| | 2608 | When two OpenVPN peers connect, each presents its local certificate to the |
| | 2609 | other. Each peer will then check that its partner peer presented a cer‐ |
| | 2610 | tificate which was signed by the master root certificate as specified in |
| | 2611 | --ca. |
| | 2612 | |
| | 2613 | If that check on both peers succeeds, then the TLS negotiation will suc‐ |
| | 2614 | ceed, both OpenVPN peers will exchange temporary session keys, and the |
| | 2615 | tunnel will begin passing data. |
| | 2616 | |
| | 2617 | The OpenVPN distribution contains a set of scripts for managing RSA cer‐ |
| | 2618 | tificates & keys, located in the easy-rsa subdirectory. |
| | 2619 | |
| | 2620 | The easy-rsa package is also rendered in web form here: http://open‐ |
| 2730 | | Local peer's signed certificate in .pem format -- must be signed |
| 2731 | | by a certificate authority whose certificate is in --ca file. |
| 2732 | | Each peer in an OpenVPN link running in TLS mode should have its |
| 2733 | | own certificate and private key file. In addition, each cer‐ |
| 2734 | | tificate should have been signed by the key of a certificate |
| 2735 | | authority whose public key resides in the --ca certificate |
| 2736 | | authority file. You can easily make your own certificate |
| 2737 | | authority (see above) or pay money to use a commercial service |
| 2738 | | such as thawte.com (in which case you will be helping to finance |
| 2739 | | the world's second space tourist :). To generate a certificate, |
| 2740 | | you can use a command such as: |
| | 2666 | Local peer's signed certificate in .pem format -- must be signed by |
| | 2667 | a certificate authority whose certificate is in --ca file. Each |
| | 2668 | peer in an OpenVPN link running in TLS mode should have its own |
| | 2669 | certificate and private key file. In addition, each certificate |
| | 2670 | should have been signed by the key of a certificate authority whose |
| | 2671 | public key resides in the --ca certificate authority file. You can |
| | 2672 | easily make your own certificate authority (see above) or pay money |
| | 2673 | to use a commercial service such as thawte.com (in which case you |
| | 2674 | will be helping to finance the world's second space tourist :). To |
| | 2675 | generate a certificate, you can use a command such as: |
| 2838 | | This makes it possible to use any smart card, supported by Win‐ |
| 2839 | | dows, but also any kind of certificate, residing in the Cert |
| 2840 | | Store, where you have access to the private key. This option |
| 2841 | | has been tested with a couple of different smart cards (GemSAFE, |
| 2842 | | Cryptoflex, and Swedish Post Office eID) on the client side, and |
| 2843 | | also an imported PKCS12 software certificate on the server side. |
| 2844 | | |
| 2845 | | To select a certificate, based on a substring search in the cer‐ |
| | 2768 | This makes it possible to use any smart card, supported by Windows, |
| | 2769 | but also any kind of certificate, residing in the Cert Store, where |
| | 2770 | you have access to the private key. This option has been tested |
| | 2771 | with a couple of different smart cards (GemSAFE, Cryptoflex, and |
| | 2772 | Swedish Post Office eID) on the client side, and also an imported |
| | 2773 | PKCS12 software certificate on the server side. |
| | 2774 | |
| | 2775 | To select a certificate, based on a substring search in the cer‐ |
| 2862 | | After OpenVPN negotiates a TLS session, a new set of keys for |
| 2863 | | protecting the tunnel data channel is generated and exchanged |
| 2864 | | over the TLS session. |
| 2865 | | |
| 2866 | | In method 1 (the default for OpenVPN 1.x), both sides generate |
| 2867 | | random encrypt and HMAC-send keys which are forwarded to the |
| 2868 | | other host over the TLS channel. |
| 2869 | | |
| 2870 | | In method 2, (the default for OpenVPN 2.0) the client generates |
| 2871 | | a random key. Both client and server also generate some random |
| 2872 | | seed material. All key source material is exchanged over the |
| 2873 | | TLS channel. The actual keys are generated using the TLS PRF |
| 2874 | | function, taking source entropy from both client and server. |
| 2875 | | Method 2 is designed to closely parallel the key generation |
| 2876 | | process used by TLS 1.0. |
| | 2792 | After OpenVPN negotiates a TLS session, a new set of keys for pro‐ |
| | 2793 | tecting the tunnel data channel is generated and exchanged over the |
| | 2794 | TLS session. |
| | 2795 | |
| | 2796 | In method 1 (the default for OpenVPN 1.x), both sides generate ran‐ |
| | 2797 | dom encrypt and HMAC-send keys which are forwarded to the other |
| | 2798 | host over the TLS channel. |
| | 2799 | |
| | 2800 | In method 2, (the default for OpenVPN 2.0) the client generates a |
| | 2801 | random key. Both client and server also generate some random seed |
| | 2802 | material. All key source material is exchanged over the TLS chan‐ |
| | 2803 | nel. The actual keys are generated using the TLS PRF function, tak‐ |
| | 2804 | ing source entropy from both client and server. Method 2 is |
| | 2805 | designed to closely parallel the key generation process used by TLS |
| | 2806 | 1.0. |
