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