Changes between Version 5 and Version 6 of Openvpn23ManPage
- Timestamp:
- 03/28/13 10:02:11 (11 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
Openvpn23ManPage
v5 v6 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 sourceVPN daemon by James Yonan. Because OpenVPN16 tries to be a universal VPN tool offering a great dealof flexibility,17 there are a lot of options on this manual page. If you're new to Open ‐18 VPN, you might want to skip ahead to the examples section where you19 will see how to construct simple VPNs on the command line without even20 needing aconfiguration file.21 22 Also note that there's more documentation and examples on the OpenVPN23 website: http://openvpn.net/24 25 And if you wouldlike to see a shorter version of this manual, see the26 openvpn usage message which can be obtained by running openvpn without27 anyparameters.15 OpenVPN is an open source VPN daemon by James Yonan. Because OpenVPN 16 tries to be a universal VPN tool offering a great deal of flexibility, 17 there are a lot of options on this manual page. If you're new to OpenVPN, 18 you might want to skip ahead to the examples section where you will see 19 how to construct simple VPNs on the command line without even needing a 20 configuration file. 21 22 Also note that there's more documentation and examples on the OpenVPN web 23 site: http://openvpn.net/ 24 25 And if you would like to see a shorter version of this manual, see the 26 openvpn usage message which can be obtained by running openvpn without any 27 parameters. 28 28 29 29 DESCRIPTION 30 OpenVPN is a robust and highly flexible VPN daemon. OpenVPN supports 31 SSL/TLS security, ethernet bridging, TCP or UDP tunnel transport 32 through proxies or NAT, support for dynamic IP addresses and DHCP, 33 scalability to hundreds or thousands of users, and portability to most 34 major OS platforms. 35 36 OpenVPN is tightly bound to the OpenSSL library, and derives much of 37 its crypto capabilities from it. 38 39 OpenVPN supports conventional encryption using a pre-shared secret key 40 (Static Key mode) or public key security (SSL/TLS mode) using client & 41 server certificates. OpenVPN also supports non-encrypted TCP/UDP tun‐ 42 nels. 43 44 OpenVPN is designed to work with the TUN/TAP virtual networking inter‐ 45 face that exists on most platforms. 46 47 Overall, OpenVPN aims to offer many of the key features of IPSec but 48 with a relatively lightweight footprint. 30 OpenVPN is a robust and highly flexible VPN daemon. OpenVPN supports 31 SSL/TLS security, ethernet bridging, TCP or UDP tunnel transport through 32 proxies or NAT, support for dynamic IP addresses and DHCP, scalability to 33 hundreds or thousands of users, and portability to most major OS plat‐ 34 forms. 35 36 OpenVPN is tightly bound to the OpenSSL library, and derives much of its 37 crypto capabilities from it. 38 39 OpenVPN supports conventional encryption using a pre-shared secret key 40 (Static Key mode) or public key security (SSL/TLS mode) using client & 41 server certificates. OpenVPN also supports non-encrypted TCP/UDP tunnels. 42 43 OpenVPN is designed to work with the TUN/TAP virtual networking interface 44 that exists on most platforms. 45 46 Overall, OpenVPN aims to offer many of the key features of IPSec but with 47 a relatively lightweight footprint. 49 48 50 49 OPTIONS 51 OpenVPN allows any option to be placed either on the command line or in 52 a configuration file. Though all command line options are preceded by53 a double-leading-dash ("--"), this prefix can be removed when an option54 isplaced in a configuration file.50 OpenVPN allows any option to be placed either on the command line or in a 51 configuration file. Though all command line options are preceded by a 52 double-leading-dash ("--"), this prefix can be removed when an option is 53 placed in a configuration file. 55 54 56 55 --help Show options. 57 56 58 57 --config file 59 Load additional config options from file where each linecorre‐60 sponds to one command line option, but with the leading'--'58 Load additional config options from file where each line corre‐ 59 sponds to one command line option, but with the leading '--' 61 60 removed. 62 61 63 If --config file is the only option to the openvpn command,the64 --config can be removed, and the command can be given asopenvpn62 If --config file is the only option to the openvpn command, the 63 --config can be removed, and the command can be given as openvpn 65 64 file 66 65 67 Note that configuration files can be nested to a reasonable 68 depth. 69 70 Double quotation or single quotation characters ("", '') can be 71 used to enclose single parameters containing whitespace, and "#" 72 or ";" characters in the first column can be used to denote com‐ 73 ments. 74 75 Note that OpenVPN 2.0 and higher performs backslash-based shell 76 escaping for characters not in single quotations, so the follow‐ 77 ing mappings should be observed: 66 Note that configuration files can be nested to a reasonable depth. 67 68 Double quotation or single quotation characters ("", '') can be 69 used to enclose single parameters containing whitespace, and "#" or 70 ";" characters in the first column can be used to denote comments. 71 72 Note that OpenVPN 2.0 and higher performs backslash-based shell 73 escaping for characters not in single quotations, so the following 74 mappings should be observed: 78 75 79 76 \\ Maps to a single backslash character (\). … … 83 80 interpret it as a parameter delimiter. 84 81 85 For example on Windows, use double backslashes to represent86 pathnames:82 For example on Windows, use double backslashes to represent path‐ 83 names: 87 84 88 85 secret "c:\\OpenVPN\\secret.key" 89 86 90 For examples of configuration files, see http://open‐91 vpn.net/examples.html87 For examples of configuration files, see http://openvpn.net/exam‐ 88 ples.html 92 89 93 90 Here is an example configuration file: … … 114 111 Tunnel Options: 115 112 --mode m 116 Set OpenVPN major mode. By default, OpenVPN runs in point-to-117 point mode ("p2p"). OpenVPN 2.0 introduces a new mode118 ("server") whichimplements a multi-client server capability.113 Set OpenVPN major mode. By default, OpenVPN runs in point-to-point 114 mode ("p2p"). OpenVPN 2.0 introduces a new mode ("server") which 115 implements a multi-client server capability. 119 116 120 117 --local host 121 Local host name or IP address for bind. If specified, OpenVPN122 will bind to this address only. If unspecified, OpenVPN will123 bind toall interfaces.118 Local host name or IP address for bind. If specified, OpenVPN will 119 bind to this address only. If unspecified, OpenVPN will bind to 120 all interfaces. 124 121 125 122 --remote host [port] [proto] 126 Remote host name or IP address. On the client, multiple 127 --remote options may be specified for redundancy, each referring 128 to a different OpenVPN server. Specifying multiple --remote 129 options for this purpose is a special case of the more general 130 connection-profile feature. See the <connection> documentation 131 below. 132 133 The OpenVPN client will try to connect to a server at host:port 134 in the order specified by the list of --remote options. 135 136 proto indicates the protocol to use when connecting with the 123 Remote host name or IP address. On the client, multiple --remote 124 options may be specified for redundancy, each referring to a dif‐ 125 ferent OpenVPN server. Specifying multiple --remote options for 126 this purpose is a special case of the more general connection-pro‐ 127 file feature. See the <connection> documentation below. 128 129 The OpenVPN client will try to connect to a server at host:port in 130 the order specified by the list of --remote options. 131 132 proto indicates the protocol to use when connecting with the 137 133 remote, and may be "tcp" or "udp". 138 134 139 The client will move on to the next host in the list, in the140 event of connection failure. Note that at any given time, the141 OpenVPNclient will at most be connected to one server.142 143 Note that since UDP is connectionless, connectionfailure is135 The client will move on to the next host in the list, in the event 136 of connection failure. Note that at any given time, the OpenVPN 137 client will at most be connected to one server. 138 139 Note that since UDP is connectionless, connection failure is 144 140 defined by the --ping and --ping-restart options. 145 141 146 Note the following corner case: If you use multiple --remote 147 options, AND you are dropping root privileges on the client with 148 --user and/or --group, AND the client is running a non-Windows 149 OS, if the client needs to switch to a different server, and 150 that server pushes back different TUN/TAP or route settings, the 151 client may lack the necessary privileges to close and reopen the 152 TUN/TAP interface. This could cause the client to exit with a 153 fatal error. 154 155 If --remote is unspecified, OpenVPN will listen for packets from 156 any IP address, but will not act on those packets unless they 157 pass all authentication tests. This requirement for authentica‐ 158 tion is binding on all potential peers, even those from known 159 and supposedly trusted IP addresses (it is very easy to forge a 160 source IP address on a UDP packet). 161 162 When used in TCP mode, --remote will act as a filter, rejecting 142 Note the following corner case: If you use multiple --remote 143 options, AND you are dropping root privileges on the client with 144 --user and/or --group, AND the client is running a non-Windows OS, 145 if the client needs to switch to a different server, and that 146 server pushes back different TUN/TAP or route settings, the client 147 may lack the necessary privileges to close and reopen the TUN/TAP 148 interface. This could cause the client to exit with a fatal error. 149 150 If --remote is unspecified, OpenVPN will listen for packets from 151 any IP address, but will not act on those packets unless they pass 152 all authentication tests. This requirement for authentication is 153 binding on all potential peers, even those from known and suppos‐ 154 edly trusted IP addresses (it is very easy to forge a source IP 155 address on a UDP packet). 156 157 When used in TCP mode, --remote will act as a filter, rejecting 163 158 connections from any host which does not match host. 164 159 165 If host is a DNS name which resolves to multiple IP addresses,166 one will be randomly chosen, providing a sort of basic load-bal‐167 an cing and failover capability.160 If host is a DNS name which resolves to multiple IP addresses, one 161 will be randomly chosen, providing a sort of basic load-balancing 162 and failover capability. 168 163 169 164 --remote-random-hostname 170 Add a random string (6 characters) to first DNS label of host‐171 name to prevent DNS caching. For example, "foo.bar.gov" would172 be modified to "<random-chars>.foo.bar.gov".165 Add a random string (6 characters) to first DNS label of hostname 166 to prevent DNS caching. For example, "foo.bar.gov" would be modi‐ 167 fied to "<random-chars>.foo.bar.gov". 173 168 174 169 <connection> 175 Define a client connection profile. Client connection profiles176 are groups of OpenVPN options that describe how to connect to a177 given OpenVPN server. Client connection profiles are specified178 within an OpenVPN configuration file, and each profile is brack‐179 eted by <connection> and </connection>.180 181 An OpenVPN client will try each connection profilesequentially170 Define a client connection profile. Client connection profiles are 171 groups of OpenVPN options that describe how to connect to a given 172 OpenVPN server. Client connection profiles are specified within an 173 OpenVPN configuration file, and each profile is bracketed by <con‐ 174 nection> and </connection>. 175 176 An OpenVPN client will try each connection profile sequentially 182 177 until it achieves a successful connection. 183 178 184 --remote-random can be used to initially "scramble" the connec‐185 tionlist.179 --remote-random can be used to initially "scramble" the connection 180 list. 186 181 187 182 Here is an example of connection profile usage: … … 216 211 verb 3 217 212 218 First we try to connect to a server at 198.19.34.56:1194 using219 UDP. If that fails, we then try to connect to 198.19.34.56:443220 using TCP. If that also fails, then try connecting through an221 HTTP proxy at 192.168.0.8:8080 to 198.19.34.56:443 using TCP.222 Finally, try to connect through the same proxy to a server at223 198.19.36.99:443using TCP.224 225 The following OpenVPN options may be used inside of a <connec‐226 tion>block:227 228 bind, connect-retry, connect-retry-max, connect-timeout, float,229 http-proxy, http-proxy-option, http-proxy-retry, http-proxy-230 timeout, local, lport, nobind, port, proto, remote, rport,231 socks-proxy, and socks-proxy-retry.232 233 A defaulting mechanism exists for specifying options to apply to 234 all <connection> profiles. If any of the above options (with235 the exception of remote ) appear outside of a <connection>236 block, but in a configuration file which has one or more <con‐237 nection> blocks, the option setting will be used as a default238 for <connection> blocks which follow it in the configuration239 file.240 241 For example, supposethe nobind option were placed in the sample242 configuration file above, near the top of the file, beforethe243 first <connection> block.The effect would be as if nobind were213 First we try to connect to a server at 198.19.34.56:1194 using UDP. 214 If that fails, we then try to connect to 198.19.34.56:443 using 215 TCP. If that also fails, then try connecting through an HTTP proxy 216 at 192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to 217 connect through the same proxy to a server at 198.19.36.99:443 218 using TCP. 219 220 The following OpenVPN options may be used inside of a <connection> 221 block: 222 223 bind, connect-retry, connect-retry-max, connect-timeout, explicit- 224 exit-notify, float, fragment, http-proxy, http-proxy-option, http- 225 proxy-retry, http-proxy-timeout, link-mtu, local, lport, mssfix, 226 mtu-disc, nobind, port, proto, remote, rport, socks-proxy, socks- 227 proxy-retry, tun-mtu and tun-mtu-extra. 228 229 A defaulting mechanism exists for specifying options to apply to 230 all <connection> profiles. If any of the above options (with the 231 exception of remote ) appear outside of a <connection> block, but 232 in a configuration file which has one or more <connection> blocks, 233 the option setting will be used as a default for <connection> 234 blocks which follow it in the configuration file. 235 236 For example, suppose the nobind option were placed in the sample 237 configuration file above, near the top of the file, before the 238 first <connection> block. The effect would be as if nobind were 244 239 declared in all <connection> blocks below it. 245 240 246 241 --proto-force p 247 When iterating through connection profiles, only consider pro‐248 filesusing protocol p ('tcp'|'udp').242 When iterating through connection profiles, only consider profiles 243 using protocol p ('tcp'|'udp'). 249 244 250 245 --remote-random 251 When multiple --remote address/ports are specified, or if con‐252 nection profiles are being used, initially randomize the order253 of thelist as a kind of basic load-balancing measure.246 When multiple --remote address/ports are specified, or if connec‐ 247 tion profiles are being used, initially randomize the order of the 248 list as a kind of basic load-balancing measure. 254 249 255 250 --proto p 256 Use protocol p for communicating with remote host. p can be257 udp,tcp-client, or tcp-server.251 Use protocol p for communicating with remote host. p can be udp, 252 tcp-client, or tcp-server. 258 253 259 254 The default protocol is udp when --proto is not specified. 260 255 261 For UDP operation, --proto udp should be specified on both 262 peers. 263 264 For TCP operation, one peer must use --proto tcp-server and the 265 other must use --proto tcp-client. A peer started with tcp- 266 server will wait indefinitely for an incoming connection. A 267 peer started with tcp-client will attempt to connect, and if 268 that fails, will sleep for 5 seconds (adjustable via the --con‐ 269 nect-retry option) and try again infinite or up to N retries 270 (adjustable via the --connect-retry-max option). Both TCP 271 client and server will simulate a SIGUSR1 restart signal if 272 either side resets the connection. 273 274 OpenVPN is designed to operate optimally over UDP, but TCP capa‐ 275 bility is provided for situations where UDP cannot be used. In 276 comparison with UDP, TCP will usually be somewhat less efficient 277 and less robust when used over unreliable or congested networks. 278 279 This article outlines some of problems with tunneling IP over 280 TCP: 256 For UDP operation, --proto udp should be specified on both peers. 257 258 For TCP operation, one peer must use --proto tcp-server and the 259 other must use --proto tcp-client. A peer started with tcp-server 260 will wait indefinitely for an incoming connection. A peer started 261 with tcp-client will attempt to connect, and if that fails, will 262 sleep for 5 seconds (adjustable via the --connect-retry option) and 263 try again infinite or up to N retries (adjustable via the --con‐ 264 nect-retry-max option). Both TCP client and server will simulate a 265 SIGUSR1 restart signal if either side resets the connection. 266 267 OpenVPN is designed to operate optimally over UDP, but TCP capabil‐ 268 ity is provided for situations where UDP cannot be used. In com‐ 269 parison with UDP, TCP will usually be somewhat less efficient and 270 less robust when used over unreliable or congested networks. 271 272 This article outlines some of problems with tunneling IP over TCP: 281 273 282 274 http://sites.inka.de/sites/bigred/devel/tcp-tcp.html 283 275 284 There are certain cases, however, where using TCP may be advan‐285 tageous from a security and robustness perspective, such as tun‐286 n eling non-IP or application-level UDP protocols, or tunneling287 protocolswhich don't possess a built-in reliability layer.276 There are certain cases, however, where using TCP may be advanta‐ 277 geous from a security and robustness perspective, such as tunneling 278 non-IP or application-level UDP protocols, or tunneling protocols 279 which don't possess a built-in reliability layer. 288 280 289 281 --connect-retry n 290 For --proto tcp-client, taken as the number of seconds to wait282 For --proto tcp-client, take n as the number of seconds to wait 291 283 between connection retries (default=5). 292 284 293 285 --connect-timeout n 294 For --proto tcp-client,set connection timeout to n seconds286 For --proto tcp-client, set connection timeout to n seconds 295 287 (default=10). 296 288 297 289 --connect-retry-max n 298 For --proto tcp-client, take n as the number of retries of con ‐299 nection attempt (default=infinite).290 For --proto tcp-client, take n as the number of retries of connec‐ 291 tion attempt (default=infinite). 300 292 301 293 --show-proxy-settings 302 Show sensed HTTP or SOCKS proxy settings. Currently, only Win ‐303 dowsclients support this option.294 Show sensed HTTP or SOCKS proxy settings. Currently, only Windows 295 clients support this option. 304 296 305 297 --http-proxy server port [authfile|'auto'|'auto-nct'] [auth-method] 306 Connect to remote host through an HTTP proxy at address server307 and port port. If HTTP Proxy-Authenticate is required, authfile308 is a file containing a username and password on 2 lines, or309 "stdin" toprompt from console.298 Connect to remote host through an HTTP proxy at address server and 299 port port. If HTTP Proxy-Authenticate is required, authfile is a 300 file containing a username and password on 2 lines, or "stdin" to 301 prompt from console. 310 302 311 303 auth-method should be one of "none", "basic", or "ntlm". 312 304 313 HTTP Digest authentication is supported as well, but only via314 theauto or auto-nct flags (below).315 316 The auto flag causes OpenVPN to automatically determine the317 auth-method and query stdin or the management interface for318 username/password credentials, if required. This flag exists on319 OpenVPN 2.1 or higher.320 321 The auto-nct flag (no clear-text auth) instructs OpenVPN to322 automatically determine the authentication method, but to reject323 weakauthentication protocols such as HTTP Basic Authentication.305 HTTP Digest authentication is supported as well, but only via the 306 auto or auto-nct flags (below). 307 308 The auto flag causes OpenVPN to automatically determine the auth- 309 method and query stdin or the management interface for user‐ 310 name/password credentials, if required. This flag exists on Open‐ 311 VPN 2.1 or higher. 312 313 The auto-nct flag (no clear-text auth) instructs OpenVPN to auto‐ 314 matically determine the authentication method, but to reject weak 315 authentication protocols such as HTTP Basic Authentication. 324 316 325 317 --http-proxy-retry 326 Retry indefinitely on HTTP proxy errors. If an HTTP proxyerror318 Retry indefinitely on HTTP proxy errors. If an HTTP proxy error 327 319 occurs, simulate a SIGUSR1 reset. 328 320 … … 331 323 332 324 --http-proxy-option type [parm] 333 Set extended HTTP proxy options. Repeat to set multiple 334 options. 335 336 VERSION version -- Set HTTP version number to version 325 Set extended HTTP proxy options. Repeat to set multiple options. 326 327 VERSION version -- Set HTTP version number to version 337 328 (default=1.0). 338 329 … … 340 331 341 332 --socks-proxy server [port] 342 Connect to remote host through a Socks5 proxy at address server343 andport port (default=1080).333 Connect to remote host through a Socks5 proxy at address server and 334 port port (default=1080). 344 335 345 336 --socks-proxy-retry 346 Retry indefinitely on Socks proxy errors. If a Socks proxy347 erroroccurs, simulate a SIGUSR1 reset.337 Retry indefinitely on Socks proxy errors. If a Socks proxy error 338 occurs, simulate a SIGUSR1 reset. 348 339 349 340 --resolv-retry n 350 If hostname resolve fails for --remote, retry resolve for n sec ‐351 ondsbefore failing.341 If hostname resolve fails for --remote, retry resolve for n seconds 342 before failing. 352 343 353 344 Set n to "infinite" to retry indefinitely. 354 345 355 By default, --resolv-retry infinite is enabled. You can disable 356 bysetting n=0.346 By default, --resolv-retry infinite is enabled. You can disable by 347 setting n=0. 357 348 358 349 --float 359 Allow remote peer to change its IP address and/or port number,360 such as due to DHCP (this is the default if --remote is not361 used). --float when specified with --remote allows an OpenVPN362 session to initially connect to a peer at a known address, how‐363 ever if packets arrive from a new address and pass all authenti‐364 cation tests, the new address will take control of the session.365 This is useful when you are connecting to a peer which holds a366 dynamic address such asa dial-in user or DHCP client.367 368 Essentially, --float tells OpenVPN to accept authenticated pack‐369 ets from any address, not only the address which was specified370 in the--remote option.350 Allow remote peer to change its IP address and/or port number, such 351 as due to DHCP (this is the default if --remote is not used). 352 --float when specified with --remote allows an OpenVPN session to 353 initially connect to a peer at a known address, however if packets 354 arrive from a new address and pass all authentication tests, the 355 new address will take control of the session. This is useful when 356 you are connecting to a peer which holds a dynamic address such as 357 a dial-in user or DHCP client. 358 359 Essentially, --float tells OpenVPN to accept authenticated packets 360 from any address, not only the address which was specified in the 361 --remote option. 371 362 372 363 --ipchange cmd 373 Run command cmd when our remote ip-address is initially authen‐374 ticated or changes.375 376 cmd consists of a path to script (or executable program),377 optionally followed by arguments. The path and arguments may be378 single- or double-quoted and/or escaped using a backslash, and379 s hould be separated by one or more spaces.380 381 When cmd is executed two arguments are appended after any argu‐382 mentsspecified in cmd , as follows:364 Run command cmd when our remote ip-address is initially authenti‐ 365 cated or changes. 366 367 cmd consists of a path to script (or executable program), option‐ 368 ally followed by arguments. The path and arguments may be single- 369 or double-quoted and/or escaped using a backslash, and should be 370 separated by one or more spaces. 371 372 When cmd is executed two arguments are appended after any arguments 373 specified in cmd , as follows: 383 374 384 375 cmd ip_address port_number 385 376 386 Don't use --ipchange in --mode server mode. Use a --client-con ‐387 nectscript instead.388 389 See the "Environmental Variables" section below foradditional377 Don't use --ipchange in --mode server mode. Use a --client-connect 378 script instead. 379 380 See the "Environmental Variables" section below for additional 390 381 parameters passed as environmental variables. 391 382 392 If you are running in a dynamic IP address environment where the 393 IP addresses of either peer could change without notice, you can394 use this script, for example, to edit the /etc/hosts file with395 the current address of the peer. The script will be run every396 time theremote peer changes its IP address.397 398 Similarly if our IP address changes due to DHCP, we should con‐399 figure our IP address change script (see man page for dhcpcd(8)400 ) to deliver a SIGHUP or SIGUSR1 signal to OpenVPN. OpenVPN401 will then reestablish a connection with its most recently402 authenticated peeron its new IP address.383 If you are running in a dynamic IP address environment where the IP 384 addresses of either peer could change without notice, you can use 385 this script, for example, to edit the /etc/hosts file with the cur‐ 386 rent address of the peer. The script will be run every time the 387 remote peer changes its IP address. 388 389 Similarly if our IP address changes due to DHCP, we should config‐ 390 ure our IP address change script (see man page for dhcpcd(8) ) to 391 deliver a SIGHUP or SIGUSR1 signal to OpenVPN. OpenVPN will then 392 reestablish a connection with its most recently authenticated peer 393 on its new IP address. 403 394 404 395 --port port 405 TCP/UDP port number for both local and remote. The current406 default of 1194 represents the official IANA port number assign‐407 ment for OpenVPN and has been used since version 2.0-beta17.408 Previous versions used port 5000 as the default.396 TCP/UDP port number for both local and remote. The current default 397 of 1194 represents the official IANA port number assignment for 398 OpenVPN and has been used since version 2.0-beta17. Previous ver‐ 399 sions used port 5000 as the default. 409 400 410 401 --lport port … … 414 405 TCP/UDP port number for remote. 415 406 416 --bind Bind to local address and port. This is the default unless any417 of--proto tcp-client , --http-proxy or --socks-proxy are used.407 --bind Bind to local address and port. This is the default unless any of 408 --proto tcp-client , --http-proxy or --socks-proxy are used. 418 409 419 410 --nobind 420 Do not bind to local address and port. The IP stack will allo‐421 cate a dynamic port for returning packets. Since the value of422 the dynamic port could not be known in advance by a peer, this423 option is only suitable for peers which will be initiating con‐424 nections byusing the --remote option.411 Do not bind to local address and port. The IP stack will allocate 412 a dynamic port for returning packets. Since the value of the 413 dynamic port could not be known in advance by a peer, this option 414 is only suitable for peers which will be initiating connections by 415 using the --remote option. 425 416 426 417 --dev tunX | tapX | null 427 TUN/TAP virtual network device ( X can be omitted for adynamic418 TUN/TAP virtual network device ( X can be omitted for a dynamic 428 419 device.) 429 420 430 See examples section below for an example on setting up aTUN421 See examples section below for an example on setting up a TUN 431 422 device. 432 423 433 You must use either tun devices on both ends of the connection434 or tap devices on both ends. You cannot mix them, as they rep‐435 resentdifferent underlying network layers.436 437 tun devices encapsulate IPv4 or IPv6 (OSI Layer 3) whiletap424 You must use either tun devices on both ends of the connection or 425 tap devices on both ends. You cannot mix them, as they represent 426 different underlying network layers. 427 428 tun devices encapsulate IPv4 or IPv6 (OSI Layer 3) while tap 438 429 devices encapsulate Ethernet 802.3 (OSI Layer 2). 439 430 440 431 --dev-type device-type 441 Which device type are we using? device-type should be tun(OSI442 Layer 3) or tap (OSI Layer 2). Use this option only if the443 TUN/TAPdevice used with --dev does not begin with tun or tap.432 Which device type are we using? device-type should be tun (OSI 433 Layer 3) or tap (OSI Layer 2). Use this option only if the TUN/TAP 434 device used with --dev does not begin with tun or tap. 444 435 445 436 --topology mode 446 Configure virtual addressing topology when running in --devtun447 mode. This directive has no meaning in --dev tap mode,which437 Configure virtual addressing topology when running in --dev tun 438 mode. This directive has no meaning in --dev tap mode, which 448 439 always uses a subnet topology. 449 440 450 If you set this directive on the server, the --server and451 --server-bridge directives will automatically push your chosen452 t opology setting to clients as well. This directive can also be453 manually pushed to clients. Like the --dev directive, this454 directive mustalways be compatible between client and server.441 If you set this directive on the server, the --server and --server- 442 bridge directives will automatically push your chosen topology set‐ 443 ting to clients as well. This directive can also be manually 444 pushed to clients. Like the --dev directive, this directive must 445 always be compatible between client and server. 455 446 456 447 mode can be one of: 457 448 458 net30 -- Use a point-to-point topology, by allocating one /30459 subnet per client. This is designed to allow point-to-point460 semantics when some or all of the connecting clients might be461 Windows systems. This is the default on OpenVPN 2.0.462 463 p2p -- Use a point-to-point topology where the remote endpoint464 of the client's tun interface always points to the local end‐465 point of the server's tun interface. This mode allocates a sin‐466 gle IP address per connecting client. Only use when none of the467 connecting clients are Windows systems. This mode is function‐468 ally equivalent to the --ifconfig-pool-linear directive which is469 available inOpenVPN 2.0 and is now deprecated.470 471 subnet -- Use a subnet rather than a point-to-point topologyby472 configuring the tuninterface with a local IP address and subnet473 mask, similar to the topology used in --dev tap and ethernet474 bridging mode. This mode allocates a single IP address per con‐475 necting client and works on Windows as well. Only available476 when server and clients are OpenVPN 2.1 or higher, or OpenVPN477 2.0.x which has been manually patched with the --topology direc‐478 tive code. When used on Windows, requires version 8.2 or higher479 of the TAP-Win32 driver. When used on *nix, requires that the480 tun driver supports an ifconfig(8) command which sets a subnet481 instead of a remote endpoint IP address.449 net30 -- Use a point-to-point topology, by allocating one /30 sub‐ 450 net per client. This is designed to allow point-to-point semantics 451 when some or all of the connecting clients might be Windows sys‐ 452 tems. This is the default on OpenVPN 2.0. 453 454 p2p -- Use a point-to-point topology where the remote endpoint of 455 the client's tun interface always points to the local endpoint of 456 the server's tun interface. This mode allocates a single IP 457 address per connecting client. Only use when none of the connect‐ 458 ing clients are Windows systems. This mode is functionally equiva‐ 459 lent to the --ifconfig-pool-linear directive which is available in 460 OpenVPN 2.0 and is now deprecated. 461 462 subnet -- Use a subnet rather than a point-to-point topology by 463 configuring the tun interface with a local IP address and subnet 464 mask, similar to the topology used in --dev tap and ethernet bridg‐ 465 ing mode. This mode allocates a single IP address per connecting 466 client and works on Windows as well. Only available when server 467 and clients are OpenVPN 2.1 or higher, or OpenVPN 2.0.x which has 468 been manually patched with the --topology directive code. When 469 used on Windows, requires version 8.2 or higher of the TAP-Win32 470 driver. When used on *nix, requires that the tun driver supports 471 an ifconfig(8) command which sets a subnet instead of a remote end‐ 472 point IP address. 482 473 483 474 This option exists in OpenVPN 2.1 or higher. 484 475 485 476 --tun-ipv6 486 Build a tun link capable of forwarding IPv6 traffic. Shouldbe487 used in conjunction with --dev tun or --dev tunX. A warning488 will be displayed if no specific IPv6 TUN support for your OS489 has beencompiled into OpenVPN.477 Build a tun link capable of forwarding IPv6 traffic. Should be 478 used in conjunction with --dev tun or --dev tunX. A warning will 479 be displayed if no specific IPv6 TUN support for your OS has been 480 compiled into OpenVPN. 490 481 491 482 See below for further IPv6-related configuration options. 492 483 493 484 --dev-node node 494 Explicitly set the device node rather than using/dev/net/tun,495 /dev/tun, /dev/tap, etc. If OpenVPN cannot figure out whether496 node is a TUN or TAP device based on the name, you should also497 specify--dev-type tun or --dev-type tap.498 499 On Windows systems, select the TAP-Win32 adapter which isnamed500 node in theNetwork Connections Control Panel or the raw GUID of501 the adapter enclosed by braces. The --show-adapters option502 under Windows can also be used to enumerate all available TAP-503 Win32 adapters and will show both the network connections con‐504 trol panelname and the GUID for each TAP-Win32 adapter.485 Explicitly set the device node rather than using /dev/net/tun, 486 /dev/tun, /dev/tap, etc. If OpenVPN cannot figure out whether node 487 is a TUN or TAP device based on the name, you should also specify 488 --dev-type tun or --dev-type tap. 489 490 On Windows systems, select the TAP-Win32 adapter which is named 491 node in the Network Connections Control Panel or the raw GUID of 492 the adapter enclosed by braces. The --show-adapters option under 493 Windows can also be used to enumerate all available TAP-Win32 494 adapters and will show both the network connections control panel 495 name and the GUID for each TAP-Win32 adapter. 505 496 506 497 --lladdr address 507 Specify the link layer address, more commonly known as theMAC498 Specify the link layer address, more commonly known as the MAC 508 499 address. Only applied to TAP devices. 509 500 510 501 --iproute cmd 511 Set alternate command to execute instead of default iproute2512 command. May be used in order to execute OpenVPN in unprivi‐513 legedenvironment.502 Set alternate command to execute instead of default iproute2 com‐ 503 mand. May be used in order to execute OpenVPN in unprivileged 504 environment. 514 505 515 506 --ifconfig l rn 516 Set TUN/TAP adapter parameters. l is the IP address of the 517 local VPN endpoint. For TUN devices, rn is the IP address of 518 the remote VPN endpoint. For TAP devices, rn is the subnet mask 519 of the virtual ethernet segment which is being created or con‐ 520 nected to. 521 522 For TUN devices, which facilitate virtual point-to-point IP con‐ 523 nections, the proper usage of --ifconfig is to use two private 524 IP addresses which are not a member of any existing subnet which 525 is in use. The IP addresses may be consecutive and should have 526 their order reversed on the remote peer. After the VPN is 527 established, by pinging rn, you will be pinging across the VPN. 528 529 For TAP devices, which provide the ability to create virtual 530 ethernet segments, --ifconfig is used to set an IP address and 531 subnet mask just as a physical ethernet adapter would be simi‐ 532 larly configured. If you are attempting to connect to a remote 533 ethernet bridge, the IP address and subnet should be set to val‐ 534 ues which would be valid on the the bridged ethernet segment 535 (note also that DHCP can be used for the same purpose). 536 537 This option, while primarily a proxy for the ifconfig(8) com‐ 538 mand, is designed to simplify TUN/TAP tunnel configuration by 539 providing a standard interface to the different ifconfig imple‐ 540 mentations on different platforms. 541 542 --ifconfig parameters which are IP addresses can also be speci‐ 543 fied as a DNS or /etc/hosts file resolvable name. 544 545 For TAP devices, --ifconfig should not be used if the TAP inter‐ 546 face will be getting an IP address lease from a DHCP server. 507 Set TUN/TAP adapter parameters. l is the IP address of the local 508 VPN endpoint. For TUN devices, rn is the IP address of the remote 509 VPN endpoint. For TAP devices, rn is the subnet mask of the vir‐ 510 tual ethernet segment which is being created or connected to. 511 512 For TUN devices, which facilitate virtual point-to-point IP connec‐ 513 tions, the proper usage of --ifconfig is to use two private IP 514 addresses which are not a member of any existing subnet which is in 515 use. The IP addresses may be consecutive and should have their 516 order reversed on the remote peer. After the VPN is established, 517 by pinging rn, you will be pinging across the VPN. 518 519 For TAP devices, which provide the ability to create virtual ether‐ 520 net segments, --ifconfig is used to set an IP address and subnet 521 mask just as a physical ethernet adapter would be similarly config‐ 522 ured. If you are attempting to connect to a remote ethernet 523 bridge, the IP address and subnet should be set to values which 524 would be valid on the the bridged ethernet segment (note also that 525 DHCP can be used for the same purpose). 526 527 This option, while primarily a proxy for the ifconfig(8) command, 528 is designed to simplify TUN/TAP tunnel configuration by providing a 529 standard interface to the different ifconfig implementations on 530 different platforms. 531 532 --ifconfig parameters which are IP addresses can also be specified 533 as a DNS or /etc/hosts file resolvable name. 534 535 For TAP devices, --ifconfig should not be used if the TAP interface 536 will be getting an IP address lease from a DHCP server. 547 537 548 538 --ifconfig-noexec 549 Don't actually execute ifconfig/netsh commands, insteadpass539 Don't actually execute ifconfig/netsh commands, instead pass 550 540 --ifconfig parameters to scripts using environmental variables. 551 541 552 542 --ifconfig-nowarn 553 Don't output an options consistency check warning if the 554 --ifconfig option on this side of the connection doesn't match 555 the remote side. This is useful when you want to retain the 556 overall benefits of the options consistency check (also see 557 --disable-occ option) while only disabling the ifconfig compo‐ 558 nent of the check. 559 560 For example, if you have a configuration where the local host 561 uses --ifconfig but the remote host does not, use --ifconfig- 562 nowarn on the local host. 563 564 This option will also silence warnings about potential address 565 conflicts which occasionally annoy more experienced users by 566 triggering "false positive" warnings. 543 Don't output an options consistency check warning if the --ifconfig 544 option on this side of the connection doesn't match the remote 545 side. This is useful when you want to retain the overall benefits 546 of the options consistency check (also see --disable-occ option) 547 while only disabling the ifconfig component of the check. 548 549 For example, if you have a configuration where the local host uses 550 --ifconfig but the remote host does not, use --ifconfig-nowarn on 551 the local host. 552 553 This option will also silence warnings about potential address con‐ 554 flicts which occasionally annoy more experienced users by trigger‐ 555 ing "false positive" warnings. 567 556 568 557 --route network/IP [netmask] [gateway] [metric] 569 Add route to routing table after connection is established.570 Multiple routes can be specified. Routes will be automatically571 torndown in reverse order prior to TUN/TAP device close.572 573 This option is intended as a convenience proxy for theroute(8)574 shell command, while at the same time providing portable seman‐575 ticsacross OpenVPN's platform space.558 Add route to routing table after connection is established. Multi‐ 559 ple routes can be specified. Routes will be automatically torn 560 down in reverse order prior to TUN/TAP device close. 561 562 This option is intended as a convenience proxy for the route(8) 563 shell command, while at the same time providing portable semantics 564 across OpenVPN's platform space. 576 565 577 566 netmask default -- 255.255.255.255 578 567 579 gateway default -- taken from --route-gateway or the second580 parameter to --ifconfig when --dev tun is specified.568 gateway default -- taken from --route-gateway or the second parame‐ 569 ter to --ifconfig when --dev tun is specified. 581 570 582 571 metric default -- taken from --route-metric otherwise 0. 583 572 584 The default can be specified by leaving an option blank or set‐585 tingit to "default".586 587 The network and gateway parameters can also be specified as a588 DNS or /etc/hosts file resolvable name, or as one of three spe‐589 cial keywords:590 591 vpn_gateway -- The remote VPN endpoint address (derived either592 from --route-gateway or the second parameter to --ifconfig when593 --devtun is specified).594 595 net_gateway -- The pre-existing IP default gateway, read from596 therouting table (not supported on all OSes).597 598 remote_host -- The --remote address if OpenVPN is being runin573 The default can be specified by leaving an option blank or setting 574 it to "default". 575 576 The network and gateway parameters can also be specified as a DNS 577 or /etc/hosts file resolvable name, or as one of three special key‐ 578 words: 579 580 vpn_gateway -- The remote VPN endpoint address (derived either from 581 --route-gateway or the second parameter to --ifconfig when --dev 582 tun is specified). 583 584 net_gateway -- The pre-existing IP default gateway, read from the 585 routing table (not supported on all OSes). 586 587 remote_host -- The --remote address if OpenVPN is being run in 599 588 client mode, and is undefined in server mode. 600 589 601 590 --max-routes n 602 Allow a maximum number of n --route options to be specified,603 either in the local configuration file, or pulled from an Open‐604 VPN server.By default, n=100.591 Allow a maximum number of n --route options to be specified, either 592 in the local configuration file, or pulled from an OpenVPN server. 593 By default, n=100. 605 594 606 595 --route-gateway gw|'dhcp' 607 596 Specify a default gateway gw for use with --route. 608 597 609 If dhcp is specified as the parameter, the gateway address will 610 be extracted from a DHCP negotiation with the OpenVPN server- 611 side LAN. 598 If dhcp is specified as the parameter, the gateway address will be 599 extracted from a DHCP negotiation with the OpenVPN server-side LAN. 612 600 613 601 --route-metric m … … 615 603 616 604 --route-delay [n] [w] 617 Delay n seconds (default=0) after connection establishment,618 before adding routes. If n is 0, routes will be added immedi‐619 ately upon connection establishment. If --route-delay is omit‐620 ted, routes will be added immediately after TUN/TAP device open621 and --up script execution, before any --user or --group privi‐622 lege downgrade (or--chroot execution.)623 624 This option is designed to be useful in scenarios whereDHCP is625 used to settap adapter addresses. The delay will give the DHCP605 Delay n seconds (default=0) after connection establishment, before 606 adding routes. If n is 0, routes will be added immediately upon 607 connection establishment. If --route-delay is omitted, routes will 608 be added immediately after TUN/TAP device open and --up script exe‐ 609 cution, before any --user or --group privilege downgrade (or 610 --chroot execution.) 611 612 This option is designed to be useful in scenarios where DHCP is 613 used to set tap adapter addresses. The delay will give the DHCP 626 614 handshake time to complete before routes are added. 627 615 628 On Windows, --route-delay tries to be more intelligent by wait‐629 ing w seconds (w=30 by default) for the TAP-Win32 adapter to630 come upbefore adding routes.616 On Windows, --route-delay tries to be more intelligent by waiting w 617 seconds (w=30 by default) for the TAP-Win32 adapter to come up 618 before adding routes. 631 619 632 620 --route-up cmd 633 Run command cmd after routes are added, subject to --route- 634 delay. 635 636 cmd consists of a path to script (or executable program), 637 optionally followed by arguments. The path and arguments may be 638 single- or double-quoted and/or escaped using a backslash, and 639 should be separated by one or more spaces. 640 641 See the "Environmental Variables" section below for additional 621 Run command cmd after routes are added, subject to --route-delay. 622 623 cmd consists of a path to script (or executable program), option‐ 624 ally followed by arguments. The path and arguments may be single- 625 or double-quoted and/or escaped using a backslash, and should be 626 separated by one or more spaces. 627 628 See the "Environmental Variables" section below for additional 642 629 parameters passed as environmental variables. 643 630 … … 645 632 Run command cmd before routes are removed upon disconnection. 646 633 647 cmd consists of a path to script (or executable program),648 optionally followed by arguments. The path and arguments may be649 single- or double-quoted and/or escaped using a backslash, and650 s hould be separated by one or more spaces.651 652 See the "Environmental Variables" section below foradditional634 cmd consists of a path to script (or executable program), option‐ 635 ally followed by arguments. The path and arguments may be single- 636 or double-quoted and/or escaped using a backslash, and should be 637 separated by one or more spaces. 638 639 See the "Environmental Variables" section below for additional 653 640 parameters passed as environmental variables. 654 641 655 642 --route-noexec 656 Don't add or remove routes automatically. Instead pass routes657 to--route-up script using environmental variables.643 Don't add or remove routes automatically. Instead pass routes to 644 --route-up script using environmental variables. 658 645 659 646 --route-nopull 660 When used with --client or --pull, accept options pushed by661 serverEXCEPT for routes and dhcp options like DNS servers.662 663 When used on the client, this option effectively bars theserver664 from adding routes to the client's routing table, however note665 th at this option still allows the server to set the TCP/IP prop‐666 erties ofthe client's TUN/TAP interface.647 When used with --client or --pull, accept options pushed by server 648 EXCEPT for routes and dhcp options like DNS servers. 649 650 When used on the client, this option effectively bars the server 651 from adding routes to the client's routing table, however note that 652 this option still allows the server to set the TCP/IP properties of 653 the client's TUN/TAP interface. 667 654 668 655 --allow-pull-fqdn 669 Allow client to pull DNS names from server (rather than being 670 limited to IP address) for --ifconfig, --route, and --route- 671 gateway. 656 Allow client to pull DNS names from server (rather than being lim‐ 657 ited to IP address) for --ifconfig, --route, and --route-gateway. 672 658 673 659 --client-nat snat|dnat network netmask alias 674 This pushable client option sets up a stateless one-to-one NAT675 rule on packet addresses (not ports), and is useful in cases676 where routes or ifconfig settings pushed to the client would677 create an IPnumbering conflict.678 679 network/netmask (for example 192.168.0.0/255.255.0.0) defines680 the local view of a resource from the clientperspective, while681 alias/netmask (for example 10.64.0.0/255.255.0.0) definesthe660 This pushable client option sets up a stateless one-to-one NAT rule 661 on packet addresses (not ports), and is useful in cases where 662 routes or ifconfig settings pushed to the client would create an IP 663 numbering conflict. 664 665 network/netmask (for example 192.168.0.0/255.255.0.0) defines the 666 local view of a resource from the client perspective, while 667 alias/netmask (for example 10.64.0.0/255.255.0.0) defines the 682 668 remote view from the server perspective. 683 669 684 Use snat (source NAT) for resources owned by the client anddnat670 Use snat (source NAT) for resources owned by the client and dnat 685 671 (destination NAT) for remote resources. 686 672 687 Set --verb 6 for debugging infoshowing the transformation of673 Set --verb 6 for debugging info showing the transformation of 688 674 src/dest addresses in packets. 689 675 690 676 --redirect-gateway flags... 691 Automatically execute routing commands to cause alloutgoing IP692 traffic to be redirected over theVPN. This is a client-side677 Automatically execute routing commands to cause all outgoing IP 678 traffic to be redirected over the VPN. This is a client-side 693 679 option. 694 680 695 681 This option performs three steps: 696 682 697 (1) Create a static route for the --remote address which for‐698 wards to the pre-existing default gateway. This is done so that699 (3) willnot create a routing loop.683 (1) Create a static route for the --remote address which forwards 684 to the pre-existing default gateway. This is done so that (3) will 685 not create a routing loop. 700 686 701 687 (2) Delete the default gateway route. 702 688 703 (3) Set the new default gateway to be theVPN endpoint address704 (derived either from --route-gatewayor the second parameter to689 (3) Set the new default gateway to be the VPN endpoint address 690 (derived either from --route-gateway or the second parameter to 705 691 --ifconfig when --dev tun is specified). 706 692 707 When the tunnel is torn down, all of the above steps are708 reversedso that the original default route is restored.693 When the tunnel is torn down, all of the above steps are reversed 694 so that the original default route is restored. 709 695 710 696 Option flags: 711 697 712 local -- Addthe local flag if both OpenVPN servers are directly713 connected via a common subnet, such as with wireless. Thelocal698 local -- Add the local flag if both OpenVPN servers are directly 699 connected via a common subnet, such as with wireless. The local 714 700 flag will cause step 1 above to be omitted. 715 701 716 autolocal -- Try to automatically determine whether to enable 717 local flag above. 718 719 def1 -- Use this flag to override the default gateway by using 720 0.0.0.0/1 and 128.0.0.0/1 rather than 0.0.0.0/0. This has the 721 benefit of overriding but not wiping out the original default 722 gateway. 723 724 bypass-dhcp -- Add a direct route to the DHCP server (if it is 725 non-local) which bypasses the tunnel (Available on Windows 726 clients, may not be available on non-Windows clients). 727 728 bypass-dns -- Add a direct route to the DNS server(s) (if they 729 are non-local) which bypasses the tunnel (Available on Windows 730 clients, may not be available on non-Windows clients). 731 732 block-local -- Block access to local LAN when the tunnel is 733 active, except for the LAN gateway itself. This is accomplished 734 by routing the local LAN (except for the LAN gateway address) 735 into the tunnel. 702 autolocal -- Try to automatically determine whether to enable local 703 flag above. 704 705 def1 -- Use this flag to override the default gateway by using 706 0.0.0.0/1 and 128.0.0.0/1 rather than 0.0.0.0/0. This has the ben‐ 707 efit of overriding but not wiping out the original default gateway. 708 709 bypass-dhcp -- Add a direct route to the DHCP server (if it is non- 710 local) which bypasses the tunnel (Available on Windows clients, may 711 not be available on non-Windows clients). 712 713 bypass-dns -- Add a direct route to the DNS server(s) (if they are 714 non-local) which bypasses the tunnel (Available on Windows clients, 715 may not be available on non-Windows clients). 716 717 block-local -- Block access to local LAN when the tunnel is active, 718 except for the LAN gateway itself. This is accomplished by routing 719 the local LAN (except for the LAN gateway address) into the tunnel. 736 720 737 721 --link-mtu n 738 Sets an upper bound on the size of UDPpackets which are sent739 between OpenVPN peers. It's best not to set this parameter740 unlessyou know what you're doing.722 Sets an upper bound on the size of UDP packets which are sent 723 between OpenVPN peers. It's best not to set this parameter unless 724 you know what you're doing. 741 725 742 726 --redirect-private [flags] 743 Like --redirect-gateway, but omit actually changingthe default727 Like --redirect-gateway, but omit actually changing the default 744 728 gateway. Useful when pushing private subnets. 745 729 746 730 --tun-mtu n 747 Take the TUN deviceMTU to be n and derive the link MTU from it748 (default=1500). In most cases, you will probably wantto leave731 Take the TUN device MTU to be n and derive the link MTU from it 732 (default=1500). In most cases, you will probably want to leave 749 733 this parameter set to its default value. 750 734 751 The MTU (Maximum Transmission Units) is the maximum datagram752 size in bytes that can be sent unfragmented over a particular753 network path. OpenVPN requires that packets on the control or754 data channels be sent unfragmented.755 756 MTU problems often manifest themselves as connections whichhang735 The MTU (Maximum Transmission Units) is the maximum datagram size 736 in bytes that can be sent unfragmented over a particular network 737 path. OpenVPN requires that packets on the control or data chan‐ 738 nels be sent unfragmented. 739 740 MTU problems often manifest themselves as connections which hang 757 741 during periods of active usage. 758 742 759 It's best to usethe --fragment and/or --mssfix options to deal743 It's best to use the --fragment and/or --mssfix options to deal 760 744 with MTU sizing issues. 761 745 762 746 --tun-mtu-extra n 763 Assume that the TUN/TAP device might return as many as n bytes 764 more than the --tun-mtu size on read. This parameter defaults 765 to 0, which is sufficient for most TUN devices. TAP devices may 766 introduce additional overhead in excess of the MTU size, and a 767 setting of 32 is the default when TAP devices are used. This 768 parameter only controls internal OpenVPN buffer sizing, so there 769 is no transmission overhead associated with using a larger 770 value. 747 Assume that the TUN/TAP device might return as many as n bytes more 748 than the --tun-mtu size on read. This parameter defaults to 0, 749 which is sufficient for most TUN devices. TAP devices may intro‐ 750 duce additional overhead in excess of the MTU size, and a setting 751 of 32 is the default when TAP devices are used. This parameter 752 only controls internal OpenVPN buffer sizing, so there is no trans‐ 753 mission overhead associated with using a larger value. 771 754 772 755 --mtu-disc type 773 Should we do Path MTU discovery on TCP/UDP channel? Only sup‐774 ported on OSes such as Linux that supports the necessary system775 call toset.756 Should we do Path MTU discovery on TCP/UDP channel? Only supported 757 on OSes such as Linux that supports the necessary system call to 758 set. 776 759 777 760 'no' -- Never send DF (Don't Fragment) frames … … 780 763 781 764 --mtu-test 782 To empirically measure MTU on connection startup, add the--mtu-783 test option to your configuration. OpenVPN will send ping pack‐784 ets of various sizes to the remote peer and measure the largest785 packets which were successfully received. The --mtu-test786 process normallytakes about 3 minutes to complete.765 To empirically measure MTU on connection startup, add the --mtu- 766 test option to your configuration. OpenVPN will send ping packets 767 of various sizes to the remote peer and measure the largest packets 768 which were successfully received. The --mtu-test process normally 769 takes about 3 minutes to complete. 787 770 788 771 --fragment max 789 Enable internal datagram fragmentation so that no UDP datagrams 790 are sent which are larger than max bytes. 791 792 The max parameter is interpreted in the same way as the --link- 793 mtu parameter, i.e. the UDP packet size after encapsulation 794 overhead has been added in, but not including the UDP header 795 itself. 796 797 The --fragment option only makes sense when you are using the 798 UDP protocol ( --proto udp ). 772 Enable internal datagram fragmentation so that no UDP datagrams are 773 sent which are larger than max bytes. 774 775 The max parameter is interpreted in the same way as the --link-mtu 776 parameter, i.e. the UDP packet size after encapsulation overhead 777 has been added in, but not including the UDP header itself. 778 779 The --fragment option only makes sense when you are using the UDP 780 protocol ( --proto udp ). 799 781 800 782 --fragment adds 4 bytes of overhead per datagram. 801 783 802 See the --mssfix option below for an important related optionto784 See the --mssfix option below for an important related option to 803 785 --fragment. 804 786 805 It should also be noted that this option is not meant to replace 806 UDP fragmentation at the IP stack level. It is only meant as a 807 last resort when path MTU discovery is broken. Using this 808 option is less efficient than fixing path MTU discovery for your 809 IP link and using native IP fragmentation instead. 810 811 Having said that, there are circumstances where using OpenVPN's 812 internal fragmentation capability may be your only option, such 813 as tunneling a UDP multicast stream which requires fragmenta‐ 814 tion. 787 It should also be noted that this option is not meant to replace 788 UDP fragmentation at the IP stack level. It is only meant as a 789 last resort when path MTU discovery is broken. Using this option 790 is less efficient than fixing path MTU discovery for your IP link 791 and using native IP fragmentation instead. 792 793 Having said that, there are circumstances where using OpenVPN's 794 internal fragmentation capability may be your only option, such as 795 tunneling a UDP multicast stream which requires fragmentation. 815 796 816 797 --mssfix max 817 Announce to TCP sessions running over the tunnel that they 818 should limit their send packet sizes such that after OpenVPN has 819 encapsulated them, the resulting UDP packet size that OpenVPN 820 sends to its peer will not exceed max bytes. The default value 821 is 1450. 822 823 The max parameter is interpreted in the same way as the --link- 824 mtu parameter, i.e. the UDP packet size after encapsulation 825 overhead has been added in, but not including the UDP header 826 itself. 827 828 The --mssfix option only makes sense when you are using the UDP 829 protocol for OpenVPN peer-to-peer communication, i.e. --proto 830 udp. 831 832 --mssfix and --fragment can be ideally used together, where 833 --mssfix will try to keep TCP from needing packet fragmentation 834 in the first place, and if big packets come through anyhow (from 835 protocols other than TCP), --fragment will internally fragment 836 them. 837 838 Both --fragment and --mssfix are designed to work around cases 839 where Path MTU discovery is broken on the network path between 798 Announce to TCP sessions running over the tunnel that they should 799 limit their send packet sizes such that after OpenVPN has encapsu‐ 800 lated them, the resulting UDP packet size that OpenVPN sends to its 801 peer will not exceed max bytes. The default value is 1450. 802 803 The max parameter is interpreted in the same way as the --link-mtu 804 parameter, i.e. the UDP packet size after encapsulation overhead 805 has been added in, but not including the UDP header itself. 806 807 The --mssfix option only makes sense when you are using the UDP 808 protocol for OpenVPN peer-to-peer communication, i.e. --proto udp. 809 810 --mssfix and --fragment can be ideally used together, where --mss‐ 811 fix will try to keep TCP from needing packet fragmentation in the 812 first place, and if big packets come through anyhow (from protocols 813 other than TCP), --fragment will internally fragment them. 814 815 Both --fragment and --mssfix are designed to work around cases 816 where Path MTU discovery is broken on the network path between 840 817 OpenVPN peers. 841 818 842 The usual symptom of such a breakdown is an OpenVPNconnection819 The usual symptom of such a breakdown is an OpenVPN connection 843 820 which successfully starts, but then stalls during active usage. 844 821 845 If --fragment and--mssfix are used together, --mssfix will take822 If --fragment and --mssfix are used together, --mssfix will take 846 823 its default max parameter from the --fragment max option. 847 824 848 Therefore, one could lower the maximum UDP packet size to 1300849 (a good first try for solving MTU-related connection problems)850 withthe following options:825 Therefore, one could lower the maximum UDP packet size to 1300 (a 826 good first try for solving MTU-related connection problems) with 827 the following options: 851 828 852 829 --tun-mtu 1500 --fragment 1300 --mssfix 853 830 854 831 --sndbuf size 855 Set the TCP/UDP socket send buffer size. Currently defaultsto832 Set the TCP/UDP socket send buffer size. Currently defaults to 856 833 65536 bytes. 857 834 858 835 --rcvbuf size 859 Set the TCP/UDP socket receive buffer size. Currently defaults860 to65536 bytes.836 Set the TCP/UDP socket receive buffer size. Currently defaults to 837 65536 bytes. 861 838 862 839 --mark value 863 Mark encrypted packets being sent with value. The mark value can 864 be matched in policy routing and packetfilter rules. This option865 is only supported in Linux and does nothing on other operating866 systems.840 Mark encrypted packets being sent with value. The mark value can be 841 matched in policy routing and packetfilter rules. This option is 842 only supported in Linux and does nothing on other operating sys‐ 843 tems. 867 844 868 845 --socket-flags flags... 869 Apply the given flags to the OpenVPN transport socket. Cur‐ 870 rently, only TCP_NODELAY is supported. 871 872 The TCP_NODELAY socket flag is useful in TCP mode, and causes 873 the kernel to send tunnel packets immediately over the TCP con‐ 874 nection without trying to group several smaller packets into a 875 larger packet. This can result in a considerably improvement in 876 latency. 877 878 This option is pushable from server to client, and should be 879 used on both client and server for maximum effect. 846 Apply the given flags to the OpenVPN transport socket. Currently, 847 only TCP_NODELAY is supported. 848 849 The TCP_NODELAY socket flag is useful in TCP mode, and causes the 850 kernel to send tunnel packets immediately over the TCP connection 851 without trying to group several smaller packets into a larger 852 packet. This can result in a considerably improvement in latency. 853 854 This option is pushable from server to client, and should be used 855 on both client and server for maximum effect. 880 856 881 857 --txqueuelen n 882 (Linux only) Set the TX queue length onthe TUN/TAP interface.858 (Linux only) Set the TX queue length on the TUN/TAP interface. 883 859 Currently defaults to 100. 884 860 885 861 --shaper n 886 Limit bandwidth ofoutgoing tunnel data to n bytes per second on887 the TCP/UDP port. If you want to limitthe bandwidth in both862 Limit bandwidth of outgoing tunnel data to n bytes per second on 863 the TCP/UDP port. If you want to limit the bandwidth in both 888 864 directions, use this option on both peers. 889 865 890 OpenVPN uses the following algorithm to implement traffic shap‐ 891 ing: Given a shaper rate of n bytes per second, after a datagram 892 write of b bytes is queued on the TCP/UDP port, wait a minimum 893 of (b / n) seconds before queuing the next write. 894 895 It should be noted that OpenVPN supports multiple tunnels 896 between the same two peers, allowing you to construct full-speed 897 and reduced bandwidth tunnels at the same time, routing low-pri‐ 898 ority data such as off-site backups over the reduced bandwidth 899 tunnel, and other data over the full-speed tunnel. 900 901 Also note that for low bandwidth tunnels (under 1000 bytes per 902 second), you should probably use lower MTU values as well (see 903 above), otherwise the packet latency will grow so large as to 904 trigger timeouts in the TLS layer and TCP connections running 905 over the tunnel. 866 OpenVPN uses the following algorithm to implement traffic shaping: 867 Given a shaper rate of n bytes per second, after a datagram write 868 of b bytes is queued on the TCP/UDP port, wait a minimum of (b / n) 869 seconds before queuing the next write. 870 871 It should be noted that OpenVPN supports multiple tunnels between 872 the same two peers, allowing you to construct full-speed and 873 reduced bandwidth tunnels at the same time, routing low-priority 874 data such as off-site backups over the reduced bandwidth tunnel, 875 and other data over the full-speed tunnel. 876 877 Also note that for low bandwidth tunnels (under 1000 bytes per sec‐ 878 ond), you should probably use lower MTU values as well (see above), 879 otherwise the packet latency will grow so large as to trigger time‐ 880 outs in the TLS layer and TCP connections running over the tunnel. 906 881 907 882 OpenVPN allows n to be between 100 bytes/sec and 100 Mbytes/sec. 908 883 909 884 --inactive n [bytes] 910 Causes OpenVPN to exit after n seconds of inactivity on the 911 TUN/TAP device. The time length of inactivity is measured since 912 the last incoming or outgoing tunnel packet. The default value 913 is 0 seconds, which disables this feature. 914 915 If the optional bytes parameter is included, exit if less than 916 bytes of combined in/out traffic are produced on the tun/tap 917 device in n seconds. 918 919 In any case, OpenVPN's internal ping packets (which are just 920 keepalives) and TLS control packets are not considered "activ‐ 921 ity", nor are they counted as traffic, as they are used inter‐ 922 nally by OpenVPN and are not an indication of actual user activ‐ 923 ity. 885 Causes OpenVPN to exit after n seconds of inactivity on the TUN/TAP 886 device. The time length of inactivity is measured since the last 887 incoming or outgoing tunnel packet. The default value is 0 sec‐ 888 onds, which disables this feature. 889 890 If the optional bytes parameter is included, exit if less than 891 bytes of combined in/out traffic are produced on the tun/tap device 892 in n seconds. 893 894 In any case, OpenVPN's internal ping packets (which are just 895 keepalives) and TLS control packets are not considered "activity", 896 nor are they counted as traffic, as they are used internally by 897 OpenVPN and are not an indication of actual user activity. 924 898 925 899 --ping n 926 Ping remote over theTCP/UDP control channel if no packets have927 been sent for at least n seconds (specify --ping on both peers928 to cause ping packets to be sent in both directions since Open‐929 VPN ping packets are not echoed like IP ping packets). When930 used in one of OpenVPN's secure modes (where --secret,--tls-931 server, or --tls-client is specified), the ping packet will be932 cryptographicallysecure.900 Ping remote over the TCP/UDP control channel if no packets have 901 been sent for at least n seconds (specify --ping on both peers to 902 cause ping packets to be sent in both directions since OpenVPN ping 903 packets are not echoed like IP ping packets). When used in one of 904 OpenVPN's secure modes (where --secret, --tls-server, or --tls- 905 client is specified), the ping packet will be cryptographically 906 secure. 933 907 934 908 This option has two intended uses: 935 909 936 (1) Compatibility with stateful firewalls. The periodic ping937 will ensure that a stateful firewall rule which allows OpenVPN938 UDP packets to pass will not time out.939 940 (2) To provide a basis for the remote to test the existence of941 itspeer using the --ping-exit option.910 (1) Compatibility with stateful firewalls. The periodic ping will 911 ensure that a stateful firewall rule which allows OpenVPN UDP pack‐ 912 ets to pass will not time out. 913 914 (2) To provide a basis for the remote to test the existence of its 915 peer using the --ping-exit option. 942 916 943 917 --ping-exit n 944 Causes OpenVPN to exit after n seconds pass without reception of 945 a ping or other packet from remote. This option can be combined946 with --inactive, --ping, and --ping-exit to create a two-tiered947 i nactivity disconnect.918 Causes OpenVPN to exit after n seconds pass without reception of a 919 ping or other packet from remote. This option can be combined with 920 --inactive, --ping, and --ping-exit to create a two-tiered inactiv‐ 921 ity disconnect. 948 922 949 923 For example, … … 951 925 openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60 952 926 953 when used on both peers will cause OpenVPN to exit within 60954 seconds if its peer disconnects, but will exit after one hour if955 noactual tunnel data is exchanged.927 when used on both peers will cause OpenVPN to exit within 60 sec‐ 928 onds if its peer disconnects, but will exit after one hour if no 929 actual tunnel data is exchanged. 956 930 957 931 --ping-restart n 958 Similar to --ping-exit, but trigger a SIGUSR1 restart after n 959 seconds pass without reception of a ping or other packet from 960 remote. 961 962 This option is useful in cases where the remote peer has a 963 dynamic IP address and a low-TTL DNS name is used to track the 964 IP address using a service such as http://dyndns.org/ + a 965 dynamic DNS client such as ddclient. 966 967 If the peer cannot be reached, a restart will be triggered, 968 causing the hostname used with --remote to be re-resolved (if 969 --resolv-retry is also specified). 970 971 In server mode, --ping-restart, --inactive, or any other type of 972 internally generated signal will always be applied to individual 973 client instance objects, never to whole server itself. Note 974 also in server mode that any internally generated signal which 975 would normally cause a restart, will cause the deletion of the 976 client instance object instead. 977 978 In client mode, the --ping-restart parameter is set to 120 sec‐ 979 onds by default. This default will hold until the client pulls 980 a replacement value from the server, based on the --keepalive 981 setting in the server configuration. To disable the 120 second 982 default, set --ping-restart 0 on the client. 932 Similar to --ping-exit, but trigger a SIGUSR1 restart after n sec‐ 933 onds pass without reception of a ping or other packet from remote. 934 935 This option is useful in cases where the remote peer has a dynamic 936 IP address and a low-TTL DNS name is used to track the IP address 937 using a service such as http://dyndns.org/ + a dynamic DNS client 938 such as ddclient. 939 940 If the peer cannot be reached, a restart will be triggered, causing 941 the hostname used with --remote to be re-resolved (if --resolv- 942 retry is also specified). 943 944 In server mode, --ping-restart, --inactive, or any other type of 945 internally generated signal will always be applied to individual 946 client instance objects, never to whole server itself. Note also 947 in server mode that any internally generated signal which would 948 normally cause a restart, will cause the deletion of the client 949 instance object instead. 950 951 In client mode, the --ping-restart parameter is set to 120 seconds 952 by default. This default will hold until the client pulls a 953 replacement value from the server, based on the --keepalive setting 954 in the server configuration. To disable the 120 second default, 955 set --ping-restart 0 on the client. 983 956 984 957 See the signals section below for more information on SIGUSR1. 985 958 986 Note that the behavior of SIGUSR1 can be modified by the --per‐987 sist-tun, --persist-key, --persist-local-ip, and --persist-988 remote-ipoptions.989 990 Also note that --ping-exit and --ping-restart are mutually991 exclusive and cannot be used together.959 Note that the behavior of SIGUSR1 can be modified by the --persist- 960 tun, --persist-key, --persist-local-ip, and --persist-remote-ip 961 options. 962 963 Also note that --ping-exit and --ping-restart are mutually exclu‐ 964 sive and cannot be used together. 992 965 993 966 --keepalive n m 994 A helper directivedesigned to simplify the expression of --ping967 A helper directive designed to simplify the expression of --ping 995 968 and --ping-restart in server mode configurations. 996 969 997 The server timeout is set twice the value of the second argu‐998 ment. This ensures that a timeout is dectected on client side999 before theserver side drops the connection.970 The server timeout is set twice the value of the second argument. 971 This ensures that a timeout is dectected on client side before the 972 server side drops the connection. 1000 973 1001 974 For example, --keepalive 10 60 expands as follows: … … 1011 984 1012 985 --ping-timer-rem 1013 Run the --ping-exit / --ping-restart timer only if we have a 1014 remote address. Use this option if you are starting the daemon 1015 in listen mode (i.e. without an explicit --remote peer), and you 1016 don't want to start clocking timeouts until a remote peer con‐ 1017 nects. 986 Run the --ping-exit / --ping-restart timer only if we have a remote 987 address. Use this option if you are starting the daemon in listen 988 mode (i.e. without an explicit --remote peer), and you don't want 989 to start clocking timeouts until a remote peer connects. 1018 990 1019 991 --persist-tun 1020 Don't close and reopen TUN/TAP device or run up/down scripts1021 acrossSIGUSR1 or --ping-restart restarts.1022 1023 SIGUSR1 is a restart signal similar to SIGHUP, butwhich offers992 Don't close and reopen TUN/TAP device or run up/down scripts across 993 SIGUSR1 or --ping-restart restarts. 994 995 SIGUSR1 is a restart signal similar to SIGHUP, but which offers 1024 996 finer-grained control over reset options. 1025 997 … … 1027 999 Don't re-read key files across SIGUSR1 or --ping-restart. 1028 1000 1029 This option canbe combined with --user nobody to allow restarts1030 triggered by the SIGUSR1 signal. Normally if you drop root1031 privileges in OpenVPN, the daemon cannot be restarted since it1032 will nowbe unable to re-read protected key files.1033 1034 This option solves the problem by persisting keys acrossSIGUSR11001 This option can be combined with --user nobody to allow restarts 1002 triggered by the SIGUSR1 signal. Normally if you drop root privi‐ 1003 leges in OpenVPN, the daemon cannot be restarted since it will now 1004 be unable to re-read protected key files. 1005 1006 This option solves the problem by persisting keys across SIGUSR1 1035 1007 resets, so they don't need to be re-read. 1036 1008 1037 1009 --persist-local-ip 1038 Preserve initially resolved local IP address and port number1039 acrossSIGUSR1 or --ping-restart restarts.1010 Preserve initially resolved local IP address and port number across 1011 SIGUSR1 or --ping-restart restarts. 1040 1012 1041 1013 --persist-remote-ip 1042 Preserve most recently authenticated remote IP addressand port1014 Preserve most recently authenticated remote IP address and port 1043 1015 number across SIGUSR1 or --ping-restart restarts. 1044 1016 1045 1017 --mlock 1046 Disable paging bycalling the POSIX mlockall function. Requires1047 that OpenVPN be initially run as root (though OpenVPN cansubse‐1018 Disable paging by calling the POSIX mlockall function. Requires 1019 that OpenVPN be initially run as root (though OpenVPN can subse‐ 1048 1020 quently downgrade its UID using the --user option). 1049 1021 1050 Using this option ensures that key material and tunnel data are 1051 never written to disk due to virtual memory paging operations 1052 which occur under most modern operating systems. It ensures 1053 that even if an attacker was able to crack the box running Open‐ 1054 VPN, he would not be able to scan the system swap file to 1055 recover previously used ephemeral keys, which are used for a 1056 period of time governed by the --reneg options (see below), then 1057 are discarded. 1058 1059 The downside of using --mlock is that it will reduce the amount 1060 of physical memory available to other applications. 1022 Using this option ensures that key material and tunnel data are 1023 never written to disk due to virtual memory paging operations which 1024 occur under most modern operating systems. It ensures that even if 1025 an attacker was able to crack the box running OpenVPN, he would not 1026 be able to scan the system swap file to recover previously used 1027 ephemeral keys, which are used for a period of time governed by the 1028 --reneg options (see below), then are discarded. 1029 1030 The downside of using --mlock is that it will reduce the amount of 1031 physical memory available to other applications. 1061 1032 1062 1033 --up cmd 1063 Run command cmd after successful TUN/TAP device open (pre--user1034 Run command cmd after successful TUN/TAP device open (pre --user 1064 1035 UID change). 1065 1036 1066 cmd consists of a path to script (or executable program),1067 optionally followed by arguments. The path and arguments may be1068 single- or double-quoted and/or escaped using a backslash, and1069 s hould be separated by one or more spaces.1070 1071 The up command is useful for specifying route commands which1072 route IP traffic destined for private subnets which exist at the1073 otherend of the VPN connection into the tunnel.1037 cmd consists of a path to script (or executable program), option‐ 1038 ally followed by arguments. The path and arguments may be single- 1039 or double-quoted and/or escaped using a backslash, and should be 1040 separated by one or more spaces. 1041 1042 The up command is useful for specifying route commands which route 1043 IP traffic destined for private subnets which exist at the other 1044 end of the VPN connection into the tunnel. 1074 1045 1075 1046 For --dev tun execute as: 1076 1047 1077 cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifcon‐1078 fig_remote_ip [init | restart ]1048 cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [ 1049 init | restart ] 1079 1050 1080 1051 For --dev tap execute as: 1081 1052 1082 cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask1083 [init | restart ]1084 1085 See the "Environmental Variables" section below foradditional1053 cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [ 1054 init | restart ] 1055 1056 See the "Environmental Variables" section below for additional 1086 1057 parameters passed as environmental variables. 1087 1058 1088 Note that ifcmd includes arguments, all OpenVPN-generated argu‐1089 ments will be appended to them to build an argument list with1090 whichthe executable will be called.1059 Note that if cmd includes arguments, all OpenVPN-generated argu‐ 1060 ments will be appended to them to build an argument list with which 1061 the executable will be called. 1091 1062 1092 1063 Typically, cmd will run a script to add routes to the tunnel. 1093 1064 1094 Normally the up script is called after the TUN/TAP device is 1095 opened. In this context, the last command line parameter passed 1096 to the script will be init. If the --up-restart option is also 1097 used, the up script will be called for restarts as well. A 1098 restart is considered to be a partial reinitialization of Open‐ 1099 VPN where the TUN/TAP instance is preserved (the --persist-tun 1100 option will enable such preservation). A restart can be gener‐ 1101 ated by a SIGUSR1 signal, a --ping-restart timeout, or a connec‐ 1102 tion reset when the TCP protocol is enabled with the --proto 1103 option. If a restart occurs, and --up-restart has been speci‐ 1104 fied, the up script will be called with restart as the last 1105 parameter. 1106 1107 The following standalone example shows how the --up script can 1108 be called in both an initialization and restart context. (NOTE: 1109 for security reasons, don't run the following example unless UDP 1110 port 9999 is blocked by your firewall. Also, the example will 1111 run indefinitely, so you should abort with control-c). 1112 1113 openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 --up 1114 'echo up' --down 'echo down' --persist-tun --up-restart 1115 1116 Note that OpenVPN also provides the --ifconfig option to auto‐ 1117 matically ifconfig the TUN device, eliminating the need to 1118 define an --up script, unless you also want to configure routes 1119 in the --up script. 1120 1121 If --ifconfig is also specified, OpenVPN will pass the ifconfig 1122 local and remote endpoints on the command line to the --up 1123 script so that they can be used to configure routes such as: 1065 Normally the up script is called after the TUN/TAP device is 1066 opened. In this context, the last command line parameter passed to 1067 the script will be init. If the --up-restart option is also used, 1068 the up script will be called for restarts as well. A restart is 1069 considered to be a partial reinitialization of OpenVPN where the 1070 TUN/TAP instance is preserved (the --persist-tun option will enable 1071 such preservation). A restart can be generated by a SIGUSR1 sig‐ 1072 nal, a --ping-restart timeout, or a connection reset when the TCP 1073 protocol is enabled with the --proto option. If a restart occurs, 1074 and --up-restart has been specified, the up script will be called 1075 with restart as the last parameter. 1076 1077 The following standalone example shows how the --up script can be 1078 called in both an initialization and restart context. (NOTE: for 1079 security reasons, don't run the following example unless UDP port 1080 9999 is blocked by your firewall. Also, the example will run 1081 indefinitely, so you should abort with control-c). 1082 1083 openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 --up 'echo 1084 up' --down 'echo down' --persist-tun --up-restart 1085 1086 Note that OpenVPN also provides the --ifconfig option to automati‐ 1087 cally ifconfig the TUN device, eliminating the need to define an 1088 --up script, unless you also want to configure routes in the --up 1089 script. 1090 1091 If --ifconfig is also specified, OpenVPN will pass the ifconfig 1092 local and remote endpoints on the command line to the --up script 1093 so that they can be used to configure routes such as: 1124 1094 1125 1095 route add -net 10.0.0.0 netmask 255.255.255.0 gw $5 1126 1096 1127 1097 --up-delay 1128 Delay TUN/TAP open and possible --up script execution until 1129 after TCP/UDP connection establishment with peer. 1130 1131 In --proto udp mode, this option normally requires the use of 1132 --ping to allow connection initiation to be sensed in the 1133 absence of tunnel data, since UDP is a "connectionless" proto‐ 1134 col. 1135 1136 On Windows, this option will delay the TAP-Win32 media state 1137 transitioning to "connected" until connection establishment, 1138 i.e. the receipt of the first authenticated packet from the 1139 peer. 1098 Delay TUN/TAP open and possible --up script execution until after 1099 TCP/UDP connection establishment with peer. 1100 1101 In --proto udp mode, this option normally requires the use of 1102 --ping to allow connection initiation to be sensed in the absence 1103 of tunnel data, since UDP is a "connectionless" protocol. 1104 1105 On Windows, this option will delay the TAP-Win32 media state tran‐ 1106 sitioning to "connected" until connection establishment, i.e. the 1107 receipt of the first authenticated packet from the peer. 1140 1108 1141 1109 --down cmd 1142 Run command cmd after TUN/TAP device close (post --user UID 1143 change and/or --chroot ). cmd consists of a path to script (or 1144 executable program), optionally followed by arguments. The path 1145 and arguments may be single- or double-quoted and/or escaped 1146 using a backslash, and should be separated by one or more spa‐ 1147 ces. 1148 1149 Called with the same parameters and environmental variables as 1150 the --up option above. 1151 1152 Note that if you reduce privileges by using --user and/or 1153 --group, your --down script will also run at reduced privilege. 1110 Run command cmd after TUN/TAP device close (post --user UID change 1111 and/or --chroot ). cmd consists of a path to script (or executable 1112 program), optionally followed by arguments. The path and arguments 1113 may be single- or double-quoted and/or escaped using a backslash, 1114 and should be separated by one or more spaces. 1115 1116 Called with the same parameters and environmental variables as the 1117 --up option above. 1118 1119 Note that if you reduce privileges by using --user and/or --group, 1120 your --down script will also run at reduced privilege. 1154 1121 1155 1122 --down-pre … … 1157 1124 1158 1125 --up-restart 1159 Enable the --up and --down scripts to be called for restartsas1160 well as initial program start. This option is described more1161 fullyabove in the --up option documentation.1126 Enable the --up and --down scripts to be called for restarts as 1127 well as initial program start. This option is described more fully 1128 above in the --up option documentation. 1162 1129 1163 1130 --setenv name value 1164 Set a custom environmental variable name=value to pass to 1131 Set a custom environmental variable name=value to pass to script. 1132 1133 --setenv FORWARD_COMPATIBLE 1 1134 Relax config file syntax checking so that unknown directives will 1135 trigger a warning but not a fatal error, on the assumption that a 1136 given unknown directive might be valid in future OpenVPN versions. 1137 1138 This option should be used with caution, as there are good security 1139 reasons for having OpenVPN fail if it detects problems in a config 1140 file. Having said that, there are valid reasons for wanting new 1141 software features to gracefully degrade when encountered by older 1142 software versions. 1143 1144 --setenv-safe name value 1145 Set a custom environmental variable OPENVPN_name=value to pass to 1165 1146 script. 1166 1147 1167 --setenv FORWARD_COMPATIBLE 1 1168 Relax config file syntax checking so that unknown directives 1169 will trigger a warning but not a fatal error, on the assumption 1170 that a given unknown directive might be valid in future OpenVPN 1171 versions. 1172 1173 This option should be used with caution, as there are good secu‐ 1174 rity reasons for having OpenVPN fail if it detects problems in a 1175 config file. Having said that, there are valid reasons for 1176 wanting new software features to gracefully degrade when encoun‐ 1177 tered by older software versions. 1178 1179 --setenv-safe name value 1180 Set a custom environmental variable OPENVPN_name=value to pass 1181 to script. 1182 1183 This directive is designed to be pushed by the server to 1184 clients, and the prepending of "OPENVPN_" to the environmental 1185 variable is a safety precaution to prevent a LD_PRELOAD style 1186 attack from a malicious or compromised server. 1148 This directive is designed to be pushed by the server to clients, 1149 and the prepending of "OPENVPN_" to the environmental variable is a 1150 safety precaution to prevent a LD_PRELOAD style attack from a mali‐ 1151 cious or compromised server. 1187 1152 1188 1153 --script-security level 1189 This directive offers policy-level control over OpenVPN's usage1190 of external programs and scripts. Lower levelvalues are more1191 restrictive, higher values are more permissive. Settingsfor1154 This directive offers policy-level control over OpenVPN's usage of 1155 external programs and scripts. Lower level values are more 1156 restrictive, higher values are more permissive. Settings for 1192 1157 level: 1193 1158 1194 1159 0 -- Strictly no calling of external programs. 1195 1 -- (Default) Only call built-in executables such as ifconfig,1196 ip,route, or netsh.1197 2 -- Allow calling of built-in executables anduser-defined1160 1 -- (Default) Only call built-in executables such as ifconfig, ip, 1161 route, or netsh. 1162 2 -- Allow calling of built-in executables and user-defined 1198 1163 scripts. 1199 3 -- Allow passwords to be passed to scripts viaenvironmental1164 3 -- Allow passwords to be passed to scripts via environmental 1200 1165 variables (potentially unsafe). 1201 1166 1202 OpenVPN releases before v2.3 also supported a method flagwhich1203 indicated how OpenVPNshould call external commands and scripts.1204 This could be either execve or system. As of OpenVPN v2.3,this1205 flag is no longer accepted. In most *nix environments the1206 execve()approach has been used without any issues.1207 1208 To run scripts in Windows in earlier OpenVPN versions you needed 1209 to either add a full path to the script interpreter which can1210 parse the script or use the system flag to run these scripts.1211 As of OpenVPN v2.3 it is now a strict requirement to have full1212 path to the script interpreter when running non-executables1213 files. This is not needed for executable files, such as .exe,1214 .com, .bat or .cmd files. For example, if you have a Visual1215 Basic script, you mustuse this syntax now:1167 OpenVPN releases before v2.3 also supported a method flag which 1168 indicated how OpenVPN should call external commands and scripts. 1169 This could be either execve or system. As of OpenVPN v2.3, this 1170 flag is no longer accepted. In most *nix environments the execve() 1171 approach has been used without any issues. 1172 1173 To run scripts in Windows in earlier OpenVPN versions you needed to 1174 either add a full path to the script interpreter which can parse 1175 the script or use the system flag to run these scripts. As of 1176 OpenVPN v2.3 it is now a strict requirement to have full path to 1177 the script interpreter when running non-executables files. This is 1178 not needed for executable files, such as .exe, .com, .bat or .cmd 1179 files. For example, if you have a Visual Basic script, you must 1180 use this syntax now: 1216 1181 1217 1182 --up 'C:\\Windows\\System32\\wscript.exe C:\\Program\ Files\\OpenVPN\\config\\my-up-script.vbs' 1218 1183 1219 Please note thesingle quote marks and the escaping of the back‐1184 Please note the single quote marks and the escaping of the back‐ 1220 1185 slashes (\) and the space character. 1221 1186 1222 The reason the support for the system flag was removed is dueto1223 the security implications with shell expansions whenexecuting1187 The reason the support for the system flag was removed is due to 1188 the security implications with shell expansions when executing 1224 1189 scripts via the system() call. 1225 1190 1226 1191 --disable-occ 1227 Don't output a warning message if option inconsistenciesare1228 detected between peers. An example of an optioninconsistency1229 would be where one peer uses --dev tun while the other peeruses1192 Don't output a warning message if option inconsistencies are 1193 detected between peers. An example of an option inconsistency 1194 would be where one peer uses --dev tun while the other peer uses 1230 1195 --dev tap. 1231 1196 1232 Use of this option is discouraged, but is provided as a tempo‐1233 rary fix in situations where a recent version of OpenVPN must1234 connect toan old version.1197 Use of this option is discouraged, but is provided as a temporary 1198 fix in situations where a recent version of OpenVPN must connect to 1199 an old version. 1235 1200 1236 1201 --user user 1237 Change the user ID of the OpenVPN process to user after initial‐ 1238 ization, dropping privileges in the process. This option is 1239 useful to protect the system in the event that some hostile 1240 party was able to gain control of an OpenVPN session. Though 1241 OpenVPN's security features make this unlikely, it is provided 1242 as a second line of defense. 1243 1244 By setting user to nobody or somebody similarly unprivileged, 1245 the hostile party would be limited in what damage they could 1246 cause. Of course once you take away privileges, you cannot 1247 return them to an OpenVPN session. This means, for example, 1248 that if you want to reset an OpenVPN daemon with a SIGUSR1 sig‐ 1249 nal (for example in response to a DHCP reset), you should make 1250 use of one or more of the --persist options to ensure that Open‐ 1251 VPN doesn't need to execute any privileged operations in order 1252 to restart (such as re-reading key files or running ifconfig on 1253 the TUN device). 1202 Change the user ID of the OpenVPN process to user after initializa‐ 1203 tion, dropping privileges in the process. This option is useful to 1204 protect the system in the event that some hostile party was able to 1205 gain control of an OpenVPN session. Though OpenVPN's security fea‐ 1206 tures make this unlikely, it is provided as a second line of 1207 defense. 1208 1209 By setting user to nobody or somebody similarly unprivileged, the 1210 hostile party would be limited in what damage they could cause. Of 1211 course once you take away privileges, you cannot return them to an 1212 OpenVPN session. This means, for example, that if you want to 1213 reset an OpenVPN daemon with a SIGUSR1 signal (for example in 1214 response to a DHCP reset), you should make use of one or more of 1215 the --persist options to ensure that OpenVPN doesn't need to exe‐ 1216 cute any privileged operations in order to restart (such as re- 1217 reading key files or running ifconfig on the TUN device). 1254 1218 1255 1219 --group group 1256 Similar to the --user option, this option changes the group ID1257 ofthe OpenVPN process to group after initialization.1220 Similar to the --user option, this option changes the group ID of 1221 the OpenVPN process to group after initialization. 1258 1222 1259 1223 --cd dir 1260 Change directory to dir prior to reading any files such as con‐1261 figuration files, key files, scripts, etc. dir should be an1262 absolute path, with a leading "/", and without any references to1263 the currentdirectory such as "." or "..".1264 1265 This option is useful when you are runningOpenVPN in --daemon1266 mode, and you want to consolidate all of your OpenVPN control1267 filesin one location.1224 Change directory to dir prior to reading any files such as configu‐ 1225 ration files, key files, scripts, etc. dir should be an absolute 1226 path, with a leading "/", and without any references to the current 1227 directory such as "." or "..". 1228 1229 This option is useful when you are running OpenVPN in --daemon 1230 mode, and you want to consolidate all of your OpenVPN control files 1231 in one location. 1268 1232 1269 1233 --chroot dir 1270 Chroot to dir after initialization. --chroot essentially rede‐1271 fines dir as being the top level directory tree (/). OpenVPN1272 will therefore be unable to access any files outside this tree.1273 This can bedesirable from a security standpoint.1274 1275 Since the chroot operation is delayed until after initializa‐1276 tion, most OpenVPN options that reference files will operate in1277 a pre-chroot context.1278 1279 In many cases, the dir parameter can point to an empty direc‐1280 tory, however complications can result when scripts or restarts1281 are executed after the chroot operation.1234 Chroot to dir after initialization. --chroot essentially redefines 1235 dir as being the top level directory tree (/). OpenVPN will there‐ 1236 fore be unable to access any files outside this tree. This can be 1237 desirable from a security standpoint. 1238 1239 Since the chroot operation is delayed until after initialization, 1240 most OpenVPN options that reference files will operate in a pre- 1241 chroot context. 1242 1243 In many cases, the dir parameter can point to an empty directory, 1244 however complications can result when scripts or restarts are exe‐ 1245 cuted after the chroot operation. 1282 1246 1283 1247 --setcon context 1284 Apply SELinux context after initialization. This essentially 1285 provides the ability to restrict OpenVPN's rights to only net‐ 1286 work I/O operations, thanks to SELinux. This goes further than 1287 --user and --chroot in that those two, while being great secu‐ 1288 rity features, unfortunately do not protect against privilege 1289 escalation by exploitation of a vulnerable system call. You can 1290 of course combine all three, but please note that since setcon 1291 requires access to /proc you will have to provide it inside the 1292 chroot directory (e.g. with mount --bind). 1293 1294 Since the setcon operation is delayed until after initializa‐ 1295 tion, OpenVPN can be restricted to just network-related system 1296 calls, whereas by applying the context before startup (such as 1297 the OpenVPN one provided in the SELinux Reference Policies) you 1298 will have to allow many things required only during initializa‐ 1299 tion. 1300 1301 Like with chroot, complications can result when scripts or 1302 restarts are executed after the setcon operation, which is why 1303 you should really consider using the --persist-key and --per‐ 1304 sist-tun options. 1248 Apply SELinux context after initialization. This essentially pro‐ 1249 vides the ability to restrict OpenVPN's rights to only network I/O 1250 operations, thanks to SELinux. This goes further than --user and 1251 --chroot in that those two, while being great security features, 1252 unfortunately do not protect against privilege escalation by 1253 exploitation of a vulnerable system call. You can of course combine 1254 all three, but please note that since setcon requires access to 1255 /proc you will have to provide it inside the chroot directory (e.g. 1256 with mount --bind). 1257 1258 Since the setcon operation is delayed until after initialization, 1259 OpenVPN can be restricted to just network-related system calls, 1260 whereas by applying the context before startup (such as the OpenVPN 1261 one provided in the SELinux Reference Policies) you will have to 1262 allow many things required only during initialization. 1263 1264 Like with chroot, complications can result when scripts or restarts 1265 are executed after the setcon operation, which is why you should 1266 really consider using the --persist-key and --persist-tun options. 1305 1267 1306 1268 --daemon [progname] 1307 Become a daemon after all initialization functions are com‐ 1308 pleted. This option will cause all message and error output to 1309 be sent to the syslog file (such as /var/log/messages), except 1310 for the output of scripts and ifconfig commands, which will go 1311 to /dev/null unless otherwise redirected. The syslog redirect‐ 1312 ion occurs immediately at the point that --daemon is parsed on 1313 the command line even though the daemonization point occurs 1314 later. If one of the --log options is present, it will 1315 supercede syslog redirection. 1316 1317 The optional progname parameter will cause OpenVPN to report its 1318 program name to the system logger as progname. This can be use‐ 1319 ful in linking OpenVPN messages in the syslog file with specific 1320 tunnels. When unspecified, progname defaults to "openvpn". 1321 1322 When OpenVPN is run with the --daemon option, it will try to 1323 delay daemonization until the majority of initialization func‐ 1324 tions which are capable of generating fatal errors are complete. 1325 This means that initialization scripts can test the return sta‐ 1326 tus of the openvpn command for a fairly reliable indication of 1327 whether the command has correctly initialized and entered the 1328 packet forwarding event loop. 1329 1330 In OpenVPN, the vast majority of errors which occur after ini‐ 1331 tialization are non-fatal. 1269 Become a daemon after all initialization functions are completed. 1270 This option will cause all message and error output to be sent to 1271 the syslog file (such as /var/log/messages), except for the output 1272 of scripts and ifconfig commands, which will go to /dev/null unless 1273 otherwise redirected. The syslog redirection occurs immediately at 1274 the point that --daemon is parsed on the command line even though 1275 the daemonization point occurs later. If one of the --log options 1276 is present, it will supercede syslog redirection. 1277 1278 The optional progname parameter will cause OpenVPN to report its 1279 program name to the system logger as progname. This can be useful 1280 in linking OpenVPN messages in the syslog file with specific tun‐ 1281 nels. When unspecified, progname defaults to "openvpn". 1282 1283 When OpenVPN is run with the --daemon option, it will try to delay 1284 daemonization until the majority of initialization functions which 1285 are capable of generating fatal errors are complete. This means 1286 that initialization scripts can test the return status of the open‐ 1287 vpn command for a fairly reliable indication of whether the command 1288 has correctly initialized and entered the packet forwarding event 1289 loop. 1290 1291 In OpenVPN, the vast majority of errors which occur after initial‐ 1292 ization are non-fatal. 1332 1293 1333 1294 --syslog [progname] 1334 Direct log output to system logger, but do not become a daemon. 1335 See --daemon directive above for description of progname parame‐ 1336 ter. 1295 Direct log output to system logger, but do not become a daemon. 1296 See --daemon directive above for description of progname parameter. 1337 1297 1338 1298 --errors-to-stderr 1339 Output errors to stderr insteadof stdout unless log output is1299 Output errors to stderr instead of stdout unless log output is 1340 1300 redirected by one of the --log options. 1341 1301 1342 1302 --passtos 1343 Set the TOS field of the tunnel packet to what the payload'sTOS1303 Set the TOS field of the tunnel packet to what the payload's TOS 1344 1304 is. 1345 1305 1346 1306 --inetd [wait|nowait] [progname] 1347 Use this option when OpenVPN is being runfrom the inetd or1307 Use this option when OpenVPN is being run from the inetd or 1348 1308 xinetd(8) server. 1349 1309 1350 The wait/nowait option must match what is specified in the 1351 inetd/xinetd config file. The nowait mode can only be used with 1352 --proto tcp-server. The default is wait. The nowait mode can 1353 be used to instantiate the OpenVPN daemon as a classic TCP 1354 server, where client connection requests are serviced on a sin‐ 1355 gle port number. For additional information on this kind of 1356 configuration, see the OpenVPN FAQ: http://open‐ 1357 vpn.net/faq.html#oneport 1358 1359 This option precludes the use of --daemon, --local, or --remote. 1360 Note that this option causes message and error output to be han‐ 1361 dled in the same way as the --daemon option. The optional prog‐ 1362 name parameter is also handled exactly as in --daemon. 1363 1364 Also note that in wait mode, each OpenVPN tunnel requires a sep‐ 1365 arate TCP/UDP port and a separate inetd or xinetd entry. See 1366 the OpenVPN 1.x HOWTO for an example on using OpenVPN with 1367 xinetd: http://openvpn.net/1xhowto.html 1310 The wait/nowait option must match what is specified in the 1311 inetd/xinetd config file. The nowait mode can only be used with 1312 --proto tcp-server. The default is wait. The nowait mode can be 1313 used to instantiate the OpenVPN daemon as a classic TCP server, 1314 where client connection requests are serviced on a single port num‐ 1315 ber. For additional information on this kind of configuration, see 1316 the OpenVPN FAQ: http://openvpn.net/faq.html#oneport 1317 1318 This option precludes the use of --daemon, --local, or --remote. 1319 Note that this option causes message and error output to be handled 1320 in the same way as the --daemon option. The optional progname 1321 parameter is also handled exactly as in --daemon. 1322 1323 Also note that in wait mode, each OpenVPN tunnel requires a sepa‐ 1324 rate TCP/UDP port and a separate inetd or xinetd entry. See the 1325 OpenVPN 1.x HOWTO for an example on using OpenVPN with xinetd: 1326 http://openvpn.net/1xhowto.html 1368 1327 1369 1328 --log file 1370 Output logging messages to file, including output to std‐ 1371 out/stderr which is generated by called scripts. If file 1372 already exists it will be truncated. This option takes effect 1373 immediately when it is parsed in the command line and will 1374 supercede syslog output if --daemon or --inetd is also speci‐ 1375 fied. This option is persistent over the entire course of an 1376 OpenVPN instantiation and will not be reset by SIGHUP, SIGUSR1, 1377 or --ping-restart. 1378 1379 Note that on Windows, when OpenVPN is started as a service, log‐ 1380 ging occurs by default without the need to specify this option. 1329 Output logging messages to file, including output to stdout/stderr 1330 which is generated by called scripts. If file already exists it 1331 will be truncated. This option takes effect immediately when it is 1332 parsed in the command line and will supercede syslog output if 1333 --daemon or --inetd is also specified. This option is persistent 1334 over the entire course of an OpenVPN instantiation and will not be 1335 reset by SIGHUP, SIGUSR1, or --ping-restart. 1336 1337 Note that on Windows, when OpenVPN is started as a service, logging 1338 occurs by default without the need to specify this option. 1381 1339 1382 1340 --log-append file 1383 Append logging messages to file. If file does not exist, it1384 will be created. This option behaves exactly like --log except1385 that itappends to rather than truncating the log file.1341 Append logging messages to file. If file does not exist, it will 1342 be created. This option behaves exactly like --log except that it 1343 appends to rather than truncating the log file. 1386 1344 1387 1345 --suppress-timestamps 1388 Avoid writing timestamps to log messages, even when they other ‐1389 w ise would be prepended. In particular, this applies to log mes‐1390 s ages sent to stdout.1346 Avoid writing timestamps to log messages, even when they otherwise 1347 would be prepended. In particular, this applies to log messages 1348 sent to stdout. 1391 1349 1392 1350 --writepid file … … 1394 1352 1395 1353 --nice n 1396 Change process priority after initialization ( n greater than 0 1397 islower priority, n less than zero is higher priority).1354 Change process priority after initialization ( n greater than 0 is 1355 lower priority, n less than zero is higher priority). 1398 1356 1399 1357 --fast-io 1400 (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a1401 call to poll/epoll/select prior to the write operation. The1402 purpose of such a call would normally be to block until the1403 device or socket is ready to accept the write. Such blocking is1404 unnecessary on some platforms which don't support write blocking1405 on UDP sockets or TUN/TAP devices. In such cases, one can opti‐1406 mize the event loop by avoiding the poll/epoll/select call,1407 improving CPU efficiency by 5%to 10%.1408 1409 This option can only be used on non-Windows systems, when1410 --protoudp is specified, and when --shaper is NOT specified.1358 (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call 1359 to poll/epoll/select prior to the write operation. The purpose of 1360 such a call would normally be to block until the device or socket 1361 is ready to accept the write. Such blocking is unnecessary on some 1362 platforms which don't support write blocking on UDP sockets or 1363 TUN/TAP devices. In such cases, one can optimize the event loop by 1364 avoiding the poll/epoll/select call, improving CPU efficiency by 5% 1365 to 10%. 1366 1367 This option can only be used on non-Windows systems, when --proto 1368 udp is specified, and when --shaper is NOT specified. 1411 1369 1412 1370 --multihome 1413 Configure a multi-homed UDP server. This option can be used 1414 when OpenVPN has been configured to listen on all interfaces, 1415 and will attempt to bind client sessions to the interface on 1416 which packets are being received, so that outgoing packets will 1417 be sent out of the same interface. Note that this option is 1418 only relevant for UDP servers and currently is only implemented 1419 on Linux. 1420 1421 Note: clients connecting to a --multihome server should always 1422 use the --nobind option. 1371 Configure a multi-homed UDP server. This option can be used when 1372 OpenVPN has been configured to listen on all interfaces, and will 1373 attempt to bind client sessions to the interface on which packets 1374 are being received, so that outgoing packets will be sent out of 1375 the same interface. Note that this option is only relevant for UDP 1376 servers and currently is only implemented on Linux. 1377 1378 Note: clients connecting to a --multihome server should always use 1379 the --nobind option. 1423 1380 1424 1381 --echo [parms...] 1425 1382 Echo parms to log output. 1426 1383 1427 Designed to be used to send messages to a controlling applica‐1428 tionwhich is receiving the OpenVPN log output.1384 Designed to be used to send messages to a controlling application 1385 which is receiving the OpenVPN log output. 1429 1386 1430 1387 --remap-usr1 signal 1431 Control whether internally or externally generated SIGUSR1 sig‐1432 nals are remapped to SIGHUP (restart without persisting state)1433 orSIGTERM (exit).1434 1435 signal can be set to "SIGHUP" or "SIGTERM". By default, no1436 remapping occurs.1388 Control whether internally or externally generated SIGUSR1 signals 1389 are remapped to SIGHUP (restart without persisting state) or 1390 SIGTERM (exit). 1391 1392 signal can be set to "SIGHUP" or "SIGTERM". By default, no remap‐ 1393 ping occurs. 1437 1394 1438 1395 --verb n 1439 Set output verbosity to n (default=1). Each level shows all 1440 info from the previous levels. Level 3 is recommended if you 1441 want a good summary of what's happening without being swamped by 1442 output. 1396 Set output verbosity to n (default=1). Each level shows all info 1397 from the previous levels. Level 3 is recommended if you want a 1398 good summary of what's happening without being swamped by output. 1443 1399 1444 1400 0 -- No output except fatal errors. 1445 1401 1 to 4 -- Normal usage range. 1446 5 -- Output R and W characters to the console for each packet1447 read and write, uppercase is used for TCP/UDP packets and lower‐1448 case isused for TUN/TAP packets.1449 6 to 11 -- Debug info range (see errlevel.h for additional1450 information on debug levels).1402 5 -- Output R and W characters to the console for each packet read 1403 and write, uppercase is used for TCP/UDP packets and lowercase is 1404 used for TUN/TAP packets. 1405 6 to 11 -- Debug info range (see errlevel.h for additional informa‐ 1406 tion on debug levels). 1451 1407 1452 1408 --status file [n] 1453 1409 Write operational status to file every n seconds. 1454 1410 1455 Status can also be written to the syslog by sending a SIGUSR21456 signal.1411 Status can also be written to the syslog by sending a SIGUSR2 sig‐ 1412 nal. 1457 1413 1458 1414 --status-version [n] 1459 Choose the status file format version number. Currently n can1460 be1, 2, or 3 and defaults to 1.1415 Choose the status file format version number. Currently n can be 1416 1, 2, or 3 and defaults to 1. 1461 1417 1462 1418 --mute n 1463 Log at most n consecutive messages in the same category. This 1464 isuseful to limit repetitive logging of similar message types.1419 Log at most n consecutive messages in the same category. This is 1420 useful to limit repetitive logging of similar message types. 1465 1421 1466 1422 --comp-lzo [mode] 1467 Use fast LZO compression -- may add up to 1 byte perpacket for1468 incompressible data. mode may be "yes", "no",or "adaptive"1423 Use fast LZO compression -- may add up to 1 byte per packet for 1424 incompressible data. mode may be "yes", "no", or "adaptive" 1469 1425 (default). 1470 1426 1471 In a server mode setup, it is possible to selectively turn com‐1472 pression on or off for individual clients.1473 1474 First, make sure the client-side config file enables selective1475 compression by having at least one --comp-lzo directive, suchas1476 --comp-lzo no. This will turnoff compression by default, but1477 allow a future directive push from the server to dynamically1478 changethe on/off/adaptive setting.1479 1480 Next in a --client-config-dir file, specify the compression set ‐1481 tingfor the client, for example:1427 In a server mode setup, it is possible to selectively turn compres‐ 1428 sion on or off for individual clients. 1429 1430 First, make sure the client-side config file enables selective com‐ 1431 pression by having at least one --comp-lzo directive, such as 1432 --comp-lzo no. This will turn off compression by default, but 1433 allow a future directive push from the server to dynamically change 1434 the on/off/adaptive setting. 1435 1436 Next in a --client-config-dir file, specify the compression setting 1437 for the client, for example: 1482 1438 1483 1439 comp-lzo yes 1484 1440 push "comp-lzo yes" 1485 1441 1486 The first line sets the comp-lzo setting for the server side of1487 thelink, the second sets the client side.1442 The first line sets the comp-lzo setting for the server side of the 1443 link, the second sets the client side. 1488 1444 1489 1445 --comp-noadapt 1490 When used in conjunction with --comp-lzo, this option will dis ‐1491 able OpenVPN's adaptive compression algorithm. Normally, adap‐1492 tive compression is enabled with --comp-lzo.1493 1494 Adaptive compression tries to optimize the case where you have1495 compression enabled, but you are sending predominantly uncom‐1496 pressible (or pre-compressed) packets over the tunnel, such as1497 an FTP or rsync transfer of a large, compressed file. With1498 adaptive compression, OpenVPN will periodically sample the com‐1499 pression process to measure its efficiency. If the data being1500 sent over the tunnel is already compressed, the compression1501 efficiency will be very low, triggering openvpn to disable com‐1502 pression for a period of timeuntil the next re-sample test.1446 When used in conjunction with --comp-lzo, this option will disable 1447 OpenVPN's adaptive compression algorithm. Normally, adaptive com‐ 1448 pression is enabled with --comp-lzo. 1449 1450 Adaptive compression tries to optimize the case where you have com‐ 1451 pression enabled, but you are sending predominantly uncompressible 1452 (or pre-compressed) packets over the tunnel, such as an FTP or 1453 rsync transfer of a large, compressed file. With adaptive compres‐ 1454 sion, OpenVPN will periodically sample the compression process to 1455 measure its efficiency. If the data being sent over the tunnel is 1456 already compressed, the compression efficiency will be very low, 1457 triggering openvpn to disable compression for a period of time 1458 until the next re-sample test. 1503 1459 1504 1460 --management IP port [pw-file] 1505 Enable a TCPserver on IP:port to handle daemon management func‐1506 tions. pw-file, if specified, is a passwordfile (password on1507 first line) or "stdin" to prompt from standard input. The pass ‐1508 word provided will set the password which TCP clients will need1509 to provide in order to access management functions.1510 1511 The management interface can also listen on a unix domain1512 socket, for those platforms that support it. To use a unix1513 domain socket, specify the unix socket pathname in place of IP1514 and set port to 'unix'. While the default behavior is to create1515 a unix domain socket that may be connected to by any process,1516 the --management-client-user and --management-client-group1517 directives can be used torestrict access.1518 1519 The management interface provides a special mode where the TCP1520 management link can operate over the tunnel itself. To enable1521 this mode, set IP = "tunnel". Tunnel mode will cause the man‐1522 agement interface to listen for a TCP connection on the local1523 VPN addressof the TUN/TAP interface.1524 1525 While the management port is designed for programmatic control 1526 of OpenVPN by other applications, it is possible to telnet to1527 the port, using a telnet client in "raw" mode. Once connected,1528 type"help" for a list of commands.1529 1530 For detailed documentation on the management interface,see the1531 management-notes.txt file in the management folder of the Open‐1532 VPNsource distribution.1533 1534 It is strongly recommended that IP be set to 127.0.0.1 (local‐1535 host) to restrict accessibility of the management server to1536 localclients.1461 Enable a TCP server on IP:port to handle daemon management func‐ 1462 tions. pw-file, if specified, is a password file (password on 1463 first line) or "stdin" to prompt from standard input. The password 1464 provided will set the password which TCP clients will need to pro‐ 1465 vide in order to access management functions. 1466 1467 The management interface can also listen on a unix domain socket, 1468 for those platforms that support it. To use a unix domain socket, 1469 specify the unix socket pathname in place of IP and set port to 1470 'unix'. While the default behavior is to create a unix domain 1471 socket that may be connected to by any process, the --management- 1472 client-user and --management-client-group directives can be used to 1473 restrict access. 1474 1475 The management interface provides a special mode where the TCP man‐ 1476 agement link can operate over the tunnel itself. To enable this 1477 mode, set IP = "tunnel". Tunnel mode will cause the management 1478 interface to listen for a TCP connection on the local VPN address 1479 of the TUN/TAP interface. 1480 1481 While the management port is designed for programmatic control of 1482 OpenVPN by other applications, it is possible to telnet to the 1483 port, using a telnet client in "raw" mode. Once connected, type 1484 "help" for a list of commands. 1485 1486 For detailed documentation on the management interface, see the 1487 management-notes.txt file in the management folder of the OpenVPN 1488 source distribution. 1489 1490 It is strongly recommended that IP be set to 127.0.0.1 (localhost) 1491 to restrict accessibility of the management server to local 1492 clients. 1537 1493 1538 1494 --management-client 1539 Management interface will connect as a TCP/unix domain clientto1540 IP:port specified by --management rather thanlisten as a TCP1495 Management interface will connect as a TCP/unix domain client to 1496 IP:port specified by --management rather than listen as a TCP 1541 1497 server or on a unix domain socket. 1542 1498 1543 If the client connection fails to connect or isdisconnected, a1499 If the client connection fails to connect or is disconnected, a 1544 1500 SIGTERM signal will be generated causing OpenVPN to quit. 1545 1501 1546 1502 --management-query-passwords 1547 Query management channel for private key password and --auth- 1548 user-pass username/password. Only query the management channel 1549 for inputs which ordinarily would have been queried from the 1550 console. 1503 Query management channel for private key password and --auth-user- 1504 pass username/password. Only query the management channel for 1505 inputs which ordinarily would have been queried from the console. 1551 1506 1552 1507 --management-query-proxy 1553 Query management channelfor proxy server information for a spe‐1508 Query management channel for proxy server information for a spe‐ 1554 1509 cific --remote (client-only). 1555 1510 1556 1511 --management-query-remote 1557 Allow management interface to override --remote directives1558 (client-only). --management-external-key Allows usage for1559 external privatekey file instead of --key option (client-only).1512 Allow management interface to override --remote directives (client- 1513 only). --management-external-key Allows usage for external private 1514 key file instead of --key option (client-only). 1560 1515 1561 1516 --management-forget-disconnect 1562 Make OpenVPN forget passwords when management session discon‐ 1563 nects. 1564 1565 This directive does not affect the --http-proxy username/pass‐ 1566 word. It is always cached. 1517 Make OpenVPN forget passwords when management session disconnects. 1518 1519 This directive does not affect the --http-proxy username/password. 1520 It is always cached. 1567 1521 1568 1522 --management-hold 1569 Start OpenVPN in a hibernating state, until a client of the man‐ 1570 agement interface explicitly starts it with the hold release 1571 command. 1523 Start OpenVPN in a hibernating state, until a client of the manage‐ 1524 ment interface explicitly starts it with the hold release command. 1572 1525 1573 1526 --management-signal 1574 Send SIGUSR1 signal to OpenVPN if management session discon‐1575 nects. This is useful when you wish to disconnect an OpenVPN1576 session on user logoff. For --management-client this option is1577 not neededsince a disconnect will always generate a SIGTERM.1527 Send SIGUSR1 signal to OpenVPN if management session disconnects. 1528 This is useful when you wish to disconnect an OpenVPN session on 1529 user logoff. For --management-client this option is not needed 1530 since a disconnect will always generate a SIGTERM. 1578 1531 1579 1532 --management-log-cache n 1580 Cache the most recent n lines of log file history for usage by1581 themanagement channel.1533 Cache the most recent n lines of log file history for usage by the 1534 management channel. 1582 1535 1583 1536 --management-up-down … … 1585 1538 1586 1539 --management-client-auth 1587 Gives management interface client the responsibility to authen‐ 1588 ticate clients after their client certificate has been verified. 1589 See management-notes.txt in OpenVPN distribution for detailed 1590 notes. 1540 Gives management interface client the responsibility to authenti‐ 1541 cate clients after their client certificate has been verified. See 1542 management-notes.txt in OpenVPN distribution for detailed notes. 1591 1543 1592 1544 --management-client-pf 1593 Management interface clients must specify a packet filter file1594 for each connecting client. See management-notes.txt in OpenVPN1595 distribution for detailed notes.1545 Management interface clients must specify a packet filter file for 1546 each connecting client. See management-notes.txt in OpenVPN dis‐ 1547 tribution for detailed notes. 1596 1548 1597 1549 --management-client-user u 1598 When the management interface is listening on a unix domain1599 socket,only allow connections from user u.1550 When the management interface is listening on a unix domain socket, 1551 only allow connections from user u. 1600 1552 1601 1553 --management-client-group g 1602 When the management interface is listening on a unix domain1603 socket,only allow connections from group g.1554 When the management interface is listening on a unix domain socket, 1555 only allow connections from group g. 1604 1556 1605 1557 --plugin module-pathname [init-string] 1606 Load plug-in module from the file module-pathname, passing init- 1607 string as an argument to the module initialization function. 1608 Multiple plugin modules may be loaded into one OpenVPN process. 1609 1610 For more information and examples on how to build OpenVPN plug- 1611 in modules, see the README file in the plugin folder of the 1612 OpenVPN source distribution. 1613 1614 If you are using an RPM install of OpenVPN, see /usr/share/open‐ 1615 vpn/plugin. The documentation is in doc and the actual plugin 1616 modules are in lib. 1617 1618 Multiple plugin modules can be cascaded, and modules can be used 1619 in tandem with scripts. The modules will be called by OpenVPN 1620 in the order that they are declared in the config file. If both 1621 a plugin and script are configured for the same callback, the 1622 script will be called last. If the return code of the mod‐ 1623 ule/script controls an authentication function (such as tls-ver‐ 1624 ify, auth-user-pass-verify, or client-connect), then every mod‐ 1625 ule and script must return success (0) in order for the connec‐ 1626 tion to be authenticated. 1558 Load plug-in module from the file module-pathname, passing init- 1559 string as an argument to the module initialization function. Mul‐ 1560 tiple plugin modules may be loaded into one OpenVPN process. 1561 1562 For more information and examples on how to build OpenVPN plug-in 1563 modules, see the README file in the plugin folder of the OpenVPN 1564 source distribution. 1565 1566 If you are using an RPM install of OpenVPN, see /usr/share/open‐ 1567 vpn/plugin. The documentation is in doc and the actual plugin mod‐ 1568 ules are in lib. 1569 1570 Multiple plugin modules can be cascaded, and modules can be used in 1571 tandem with scripts. The modules will be called by OpenVPN in the 1572 order that they are declared in the config file. If both a plugin 1573 and script are configured for the same callback, the script will be 1574 called last. If the return code of the module/script controls an 1575 authentication function (such as tls-verify, auth-user-pass-verify, 1576 or client-connect), then every module and script must return suc‐ 1577 cess (0) in order for the connection to be authenticated. 1627 1578 1628 1579 Server Mode 1629 Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode issup‐1630 ported, and can be enabled with the --mode server option. In server1631 mode, OpenVPN will listen on a single port for incoming client connec‐1632 tions. All client connections will be routed through a single tun or1633 tap interface. This mode is designed for scalability and should be1634 able to support hundreds or even thousands of clients on sufficiently1635 fast hardware. SSL/TLSauthentication must be used in this mode.1580 Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is sup‐ 1581 ported, and can be enabled with the --mode server option. In server mode, 1582 OpenVPN will listen on a single port for incoming client connections. All 1583 client connections will be routed through a single tun or tap interface. 1584 This mode is designed for scalability and should be able to support hun‐ 1585 dreds or even thousands of clients on sufficiently fast hardware. SSL/TLS 1586 authentication must be used in this mode. 1636 1587 1637 1588 --server network netmask 1638 A helper directive designed to simplify the configuration of1639 OpenVPN's server mode. This directive will set up an OpenVPN1640 server which will allocate addresses to clients out of the given1641 network/netmask. The server itself will take the ".1" address1642 of the given network for use as the server-side endpoint of the1643 localTUN/TAP interface.1589 A helper directive designed to simplify the configuration of Open‐ 1590 VPN's server mode. This directive will set up an OpenVPN server 1591 which will allocate addresses to clients out of the given net‐ 1592 work/netmask. The server itself will take the ".1" address of the 1593 given network for use as the server-side endpoint of the local 1594 TUN/TAP interface. 1644 1595 1645 1596 For example, --server 10.8.0.0 255.255.255.0 expands as follows: … … 1665 1616 push "route-gateway 10.8.0.1" 1666 1617 1667 Don't use --server if you are ethernet bridging. Use--server-1618 Don't use --server if you are ethernet bridging. Use --server- 1668 1619 bridge instead. 1669 1620 … … 1672 1623 --server-bridge ['nogw'] 1673 1624 1674 A helper directive similar to --server which is designed to sim‐ 1675 plify the configuration of OpenVPN's server mode in ethernet 1676 bridging configurations. 1677 1678 If --server-bridge is used without any parameters, it will 1679 enable a DHCP-proxy mode, where connecting OpenVPN clients will 1680 receive an IP address for their TAP adapter from the DHCP server 1681 running on the OpenVPN server-side LAN. Note that only clients 1682 that support the binding of a DHCP client with the TAP adapter 1683 (such as Windows) can support this mode. The optional nogw flag 1684 (advanced) indicates that gateway information should not be 1685 pushed to the client. 1686 1687 To configure ethernet bridging, you must first use your OS's 1688 bridging capability to bridge the TAP interface with the ether‐ 1689 net NIC interface. For example, on Linux this is done with the 1690 brctl tool, and with Windows XP it is done in the Network Con‐ 1691 nections Panel by selecting the ethernet and TAP adapters and 1692 right-clicking on "Bridge Connections". 1693 1694 Next you you must manually set the IP/netmask on the bridge 1695 interface. The gateway and netmask parameters to --server- 1696 bridge can be set to either the IP/netmask of the bridge inter‐ 1697 face, or the IP/netmask of the default gateway/router on the 1698 bridged subnet. 1699 1700 Finally, set aside a IP range in the bridged subnet, denoted by 1701 pool-start-IP and pool-end-IP, for OpenVPN to allocate to con‐ 1702 necting clients. 1703 1704 For example, server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 1625 A helper directive similar to --server which is designed to sim‐ 1626 plify the configuration of OpenVPN's server mode in ethernet bridg‐ 1627 ing configurations. 1628 1629 If --server-bridge is used without any parameters, it will enable a 1630 DHCP-proxy mode, where connecting OpenVPN clients will receive an 1631 IP address for their TAP adapter from the DHCP server running on 1632 the OpenVPN server-side LAN. Note that only clients that support 1633 the binding of a DHCP client with the TAP adapter (such as Windows) 1634 can support this mode. The optional nogw flag (advanced) indicates 1635 that gateway information should not be pushed to the client. 1636 1637 To configure ethernet bridging, you must first use your OS's bridg‐ 1638 ing capability to bridge the TAP interface with the ethernet NIC 1639 interface. For example, on Linux this is done with the brctl tool, 1640 and with Windows XP it is done in the Network Connections Panel by 1641 selecting the ethernet and TAP adapters and right-clicking on 1642 "Bridge Connections". 1643 1644 Next you you must manually set the IP/netmask on the bridge inter‐ 1645 face. The gateway and netmask parameters to --server-bridge can be 1646 set to either the IP/netmask of the bridge interface, or the 1647 IP/netmask of the default gateway/router on the bridged subnet. 1648 1649 Finally, set aside a IP range in the bridged subnet, denoted by 1650 pool-start-IP and pool-end-IP, for OpenVPN to allocate to connect‐ 1651 ing clients. 1652 1653 For example, server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 1705 1654 10.8.0.254 expands as follows: 1706 1655 … … 1711 1660 push "route-gateway 10.8.0.4" 1712 1661 1713 In another example, --server-bridge (without parameters) expands 1714 asfollows:1662 In another example, --server-bridge (without parameters) expands as 1663 follows: 1715 1664 1716 1665 mode server … … 1725 1674 1726 1675 --push option 1727 Push a config file option back to the client for remote execu‐ 1728 tion. Note that option must be enclosed in double quotes (""). 1729 The client must specify --pull in its config file. The set of 1730 options which can be pushed is limited by both feasibility and 1731 security. Some options such as those which would execute 1732 scripts are banned, since they would effectively allow a compro‐ 1733 mised server to execute arbitrary code on the client. Other 1734 options such as TLS or MTU parameters cannot be pushed because 1735 the client needs to know them before the connection to the 1736 server can be initiated. 1737 1738 This is a partial list of options which can currently be pushed: 1739 --route, --route-gateway, --route-delay, --redirect-gateway, 1740 --ip-win32, --dhcp-option, --inactive, --ping, --ping-exit, 1741 --ping-restart, --setenv, --persist-key, --persist-tun, --echo, 1742 --comp-lzo, --socket-flags, --sndbuf, --rcvbuf 1676 Push a config file option back to the client for remote execution. 1677 Note that option must be enclosed in double quotes (""). The 1678 client must specify --pull in its config file. The set of options 1679 which can be pushed is limited by both feasibility and security. 1680 Some options such as those which would execute scripts are banned, 1681 since they would effectively allow a compromised server to execute 1682 arbitrary code on the client. Other options such as TLS or MTU 1683 parameters cannot be pushed because the client needs to know them 1684 before the connection to the server can be initiated. 1685 1686 This is a partial list of options which can currently be pushed: 1687 --route, --route-gateway, --route-delay, --redirect-gateway, --ip- 1688 win32, --dhcp-option, --inactive, --ping, --ping-exit, --ping- 1689 restart, --setenv, --persist-key, --persist-tun, --echo, --comp- 1690 lzo, --socket-flags, --sndbuf, --rcvbuf 1743 1691 1744 1692 --push-reset 1745 Don't inherit the global push list for a specific client1746 instance. Specify this option in a client-specific context such1747 as with a --client-config-dir configuration file. This option1748 will ignore--push options at the global config file level.1693 Don't inherit the global push list for a specific client instance. 1694 Specify this option in a client-specific context such as with a 1695 --client-config-dir configuration file. This option will ignore 1696 --push options at the global config file level. 1749 1697 1750 1698 --push-peer-info 1751 Push additional information about the client to server. The1752 additional information consists of the following data:1699 Push additional information about the client to server. The addi‐ 1700 tional information consists of the following data: 1753 1701 1754 1702 IV_VER=<version> -- the client OpenVPN version 1755 1703 1756 IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win] --the1704 IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win] -- the 1757 1705 client OS platform 1758 1706 1759 IV_HWADDR=<mac address> -- the MAC address of clients default1760 gateway1707 IV_HWADDR=<mac address> -- the MAC address of clients default gate‐ 1708 way 1761 1709 1762 1710 IV_LZO_STUB=1 -- if client was built with LZO stub capability 1763 1711 1764 UV_<name>=<value> -- client environment variables whose names1765 startwith "UV_"1712 UV_<name>=<value> -- client environment variables whose names start 1713 with "UV_" 1766 1714 1767 1715 --disable 1768 Disable a particular client (based on the common name) fromcon‐1769 necting. Don't use this option to disable a client due to key 1770 or password compromise. Use a CRL (certificate revocationlist)1716 Disable a particular client (based on the common name) from con‐ 1717 necting. Don't use this option to disable a client due to key or 1718 password compromise. Use a CRL (certificate revocation list) 1771 1719 instead (see the --crl-verify option). 1772 1720 1773 This option must beassociated with a specific client instance,1774 which means that it must be specified either in a client1775 instance config file using --client-config-dir or dynamically1776 generatedusing a --client-connect script.1721 This option must be associated with a specific client instance, 1722 which means that it must be specified either in a client instance 1723 config file using --client-config-dir or dynamically generated 1724 using a --client-connect script. 1777 1725 1778 1726 --ifconfig-pool start-IP end-IP [netmask] 1779 Set aside a pool of subnets to be dynamically allocated to con‐1780 necting clients, similar to a DHCP server. For tun-style tun‐1781 nels, each client will be given a /30 subnet (for interoperabil‐1782 ity with Windows clients). For tap-style tunnels, individual1783 a ddresses will be allocated, and the optional netmask parameter1784 will also be pushedto clients.1727 Set aside a pool of subnets to be dynamically allocated to connect‐ 1728 ing clients, similar to a DHCP server. For tun-style tunnels, each 1729 client will be given a /30 subnet (for interoperability with Win‐ 1730 dows clients). For tap-style tunnels, individual addresses will be 1731 allocated, and the optional netmask parameter will also be pushed 1732 to clients. 1785 1733 1786 1734 1787 1735 --ifconfig-pool-persist file [seconds] 1788 Persist/unpersist ifconfig-pool data to file, at seconds inter ‐1789 vals(default=600), as well as on program startup and shutdown.1790 1791 The goal of this option is toprovide a long-term association1792 between clients (denoted by their common name) and the virtual 1793 IP address assigned to them from the ifconfig-pool. Maintaining1794 a long-term association is good for clients because it allows1795 them toeffectively use the --persist-tun option.1796 1797 file is acomma-delimited ASCII file, formatted as <Common-1736 Persist/unpersist ifconfig-pool data to file, at seconds intervals 1737 (default=600), as well as on program startup and shutdown. 1738 1739 The goal of this option is to provide a long-term association 1740 between clients (denoted by their common name) and the virtual IP 1741 address assigned to them from the ifconfig-pool. Maintaining a 1742 long-term association is good for clients because it allows them to 1743 effectively use the --persist-tun option. 1744 1745 file is a comma-delimited ASCII file, formatted as <Common- 1798 1746 Name>,<IP-address>. 1799 1747 1800 If seconds = 0, file will be treated as read-only. This is use‐1801 fulif you would like to treat file as a configuration file.1802 1803 Note that the entries in this file are treated by OpenVPN as1804 suggestions only, based on past associations between a common1805 name and IP address. They do not guarantee that the given com‐1806 mon name will always receive the given IP address. If you want1807 guaranteedassignment, use --ifconfig-push1748 If seconds = 0, file will be treated as read-only. This is useful 1749 if you would like to treat file as a configuration file. 1750 1751 Note that the entries in this file are treated by OpenVPN as sug‐ 1752 gestions only, based on past associations between a common name and 1753 IP address. They do not guarantee that the given common name will 1754 always receive the given IP address. If you want guaranteed 1755 assignment, use --ifconfig-push 1808 1756 1809 1757 --ifconfig-pool-linear 1810 Modifies the --ifconfig-pool directive to allocate individual1811 TUN interface addresses for clients rather than /30 subnets.1812 NOTE:This option is incompatible with Windows clients.1813 1814 This option is deprecated, and should be replaced with --topol‐1815 ogyp2p which is functionally equivalent.1758 Modifies the --ifconfig-pool directive to allocate individual TUN 1759 interface addresses for clients rather than /30 subnets. NOTE: 1760 This option is incompatible with Windows clients. 1761 1762 This option is deprecated, and should be replaced with --topology 1763 p2p which is functionally equivalent. 1816 1764 1817 1765 --ifconfig-push local remote-netmask [alias] 1818 Push virtual IP endpoints for client tunnel, overridingthe1766 Push virtual IP endpoints for client tunnel, overriding the 1819 1767 --ifconfig-pool dynamic allocation. 1820 1768 1821 The parameters local and remote-netmask are set according to the 1822 --ifconfig directive which you want to execute on the client 1823 machine to configure the remote end of the tunnel. Note that 1824 the parameters local and remote-netmask are from the perspective 1825 of the client, not the server. They may be DNS names rather 1826 than IP addresses, in which case they will be resolved on the 1827 server at the time of client connection. 1828 1829 The optional alias parameter may be used in cases where NAT 1830 causes the client view of its local endpoint to differ from the 1831 server view. In this case local/remote-netmask will refer to 1832 the server view while alias/remote-netmask will refer to the 1833 client view. 1834 1835 This option must be associated with a specific client instance, 1836 which means that it must be specified either in a client 1837 instance config file using --client-config-dir or dynamically 1838 generated using a --client-connect script. 1839 1840 Remember also to include a --route directive in the main OpenVPN 1841 config file which encloses local, so that the kernel will know 1842 to route it to the server's TUN/TAP interface. 1843 1844 OpenVPN's internal client IP address selection algorithm works 1845 as follows: 1846 1847 1 -- Use --client-connect script generated file for static IP 1769 The parameters local and remote-netmask are set according to the 1770 --ifconfig directive which you want to execute on the client 1771 machine to configure the remote end of the tunnel. Note that the 1772 parameters local and remote-netmask are from the perspective of the 1773 client, not the server. They may be DNS names rather than IP 1774 addresses, in which case they will be resolved on the server at the 1775 time of client connection. 1776 1777 The optional alias parameter may be used in cases where NAT causes 1778 the client view of its local endpoint to differ from the server 1779 view. In this case local/remote-netmask will refer to the server 1780 view while alias/remote-netmask will refer to the client view. 1781 1782 This option must be associated with a specific client instance, 1783 which means that it must be specified either in a client instance 1784 config file using --client-config-dir or dynamically generated 1785 using a --client-connect script. 1786 1787 Remember also to include a --route directive in the main OpenVPN 1788 config file which encloses local, so that the kernel will know to 1789 route it to the server's TUN/TAP interface. 1790 1791 OpenVPN's internal client IP address selection algorithm works as 1792 follows: 1793 1794 1 -- Use --client-connect script generated file for static IP 1848 1795 (first choice). 1849 1796 2 -- Use --client-config-dir file for static IP (next choice). 1850 3 -- Use --ifconfig-pool allocation for dynamic IP (last 1851 choice). 1797 3 -- Use --ifconfig-pool allocation for dynamic IP (last choice). 1852 1798 1853 1799 --iroute network [netmask] 1854 Generate an internal route to a specific client. The netmask 1855 parameter, if omitted, defaults to 255.255.255.255. 1856 1857 This directive can be used to route a fixed subnet from the 1858 server to a particular client, regardless of where the client is 1859 connecting from. Remember that you must also add the route to 1860 the system routing table as well (such as by using the --route 1861 directive). The reason why two routes are needed is that the 1862 --route directive routes the packet from the kernel to OpenVPN. 1863 Once in OpenVPN, the --iroute directive routes to the specific 1864 client. 1865 1866 This option must be specified either in a client instance config 1867 file using --client-config-dir or dynamically generated using a 1800 Generate an internal route to a specific client. The netmask param‐ 1801 eter, if omitted, defaults to 255.255.255.255. 1802 1803 This directive can be used to route a fixed subnet from the server 1804 to a particular client, regardless of where the client is connect‐ 1805 ing from. Remember that you must also add the route to the system 1806 routing table as well (such as by using the --route directive). 1807 The reason why two routes are needed is that the --route directive 1808 routes the packet from the kernel to OpenVPN. Once in OpenVPN, the 1809 --iroute directive routes to the specific client. 1810 1811 This option must be specified either in a client instance config 1812 file using --client-config-dir or dynamically generated using a 1868 1813 --client-connect script. 1869 1814 1870 The --iroute directive also has an important interaction with 1871 --push "route ...". --iroute essentially defines a subnet which 1872 is owned by a particular client (we will call this client A). 1873 If you would like other clients to be able to reach A's subnet, 1874 you can use --push "route ..." together with --client-to-client 1875 to effect this. In order for all clients to see A's subnet, 1876 OpenVPN must push this route to all clients EXCEPT for A, since 1877 the subnet is already owned by A. OpenVPN accomplishes this by 1878 not not pushing a route to a client if it matches one of the 1879 client's iroutes. 1815 The --iroute directive also has an important interaction with 1816 --push "route ...". --iroute essentially defines a subnet which is 1817 owned by a particular client (we will call this client A). If you 1818 would like other clients to be able to reach A's subnet, you can 1819 use --push "route ..." together with --client-to-client to effect 1820 this. In order for all clients to see A's subnet, OpenVPN must 1821 push this route to all clients EXCEPT for A, since the subnet is 1822 already owned by A. OpenVPN accomplishes this by not not pushing a 1823 route to a client if it matches one of the client's iroutes. 1880 1824 1881 1825 --client-to-client 1882 Because the OpenVPN server mode handles multiple clients through1883 a single tun or tap interface, it is effectively arouter. The1884 --client-to-client flag tells OpenVPN to internally route1885 client-to-client traffic rather than pushing all client-origi‐1886 nating traffic to the TUN/TAP interface.1887 1888 When this option is used, each client will "see" the other1889 clients which are currently connected. Otherwise, each client1890 will only see the server. Don't use this option if you want to1891 firewall tunnel traffic using custom, per-client rules.1826 Because the OpenVPN server mode handles multiple clients through a 1827 single tun or tap interface, it is effectively a router. The 1828 --client-to-client flag tells OpenVPN to internally route client- 1829 to-client traffic rather than pushing all client-originating traf‐ 1830 fic to the TUN/TAP interface. 1831 1832 When this option is used, each client will "see" the other clients 1833 which are currently connected. Otherwise, each client will only 1834 see the server. Don't use this option if you want to firewall tun‐ 1835 nel traffic using custom, per-client rules. 1892 1836 1893 1837 --duplicate-cn 1894 Allow multiple clients with the same common name toconcurrently1895 connect. In the absence of this option, OpenVPN will disconnect1896 a client instance upon connection of a new client having the1897 samecommon name.1838 Allow multiple clients with the same common name to concurrently 1839 connect. In the absence of this option, OpenVPN will disconnect a 1840 client instance upon connection of a new client having the same 1841 common name. 1898 1842 1899 1843 --client-connect cmd 1900 1844 Run command cmd on client connection. 1901 1845 1902 cmd consists of a path to script (or executable program), 1903 optionally followed by arguments. The path and arguments may be 1904 single- or double-quoted and/or escaped using a backslash, and 1905 should be separated by one or more spaces. 1906 1907 The command is passed the common name and IP address of the 1908 just-authenticated client as environmental variables (see envi‐ 1909 ronmental variable section below). The command is also passed 1910 the pathname of a freshly created temporary file as the last 1911 argument (after any arguments specified in cmd ), to be used by 1912 the command to pass dynamically generated config file directives 1913 back to OpenVPN. 1914 1915 If the script wants to generate a dynamic config file to be 1916 applied on the server when the client connects, it should write 1917 it to the file named by the last argument. 1918 1919 See the --client-config-dir option below for options which can 1920 be legally used in a dynamically generated config file. 1921 1922 Note that the return value of script is significant. If script 1923 returns a non-zero error status, it will cause the client to be 1846 cmd consists of a path to script (or executable program), option‐ 1847 ally followed by arguments. The path and arguments may be single- 1848 or double-quoted and/or escaped using a backslash, and should be 1849 separated by one or more spaces. 1850 1851 The command is passed the common name and IP address of the just- 1852 authenticated client as environmental variables (see environmental 1853 variable section below). The command is also passed the pathname 1854 of a freshly created temporary file as the last argument (after any 1855 arguments specified in cmd ), to be used by the command to pass 1856 dynamically generated config file directives back to OpenVPN. 1857 1858 If the script wants to generate a dynamic config file to be applied 1859 on the server when the client connects, it should write it to the 1860 file named by the last argument. 1861 1862 See the --client-config-dir option below for options which can be 1863 legally used in a dynamically generated config file. 1864 1865 Note that the return value of script is significant. If script 1866 returns a non-zero error status, it will cause the client to be 1924 1867 disconnected. 1925 1868 1926 1869 --client-disconnect cmd 1927 Like --client-connect but called on client instance shutdown.1928 Will not be called unless the --client-connect script and plug‐1929 ins (if defined) were previously called on this instance with1930 successful(0) status returns.1931 1932 The exception to this rule is if the --client-disconnect command 1933 or plugins are cascaded, and at least one client-connect func‐1934 tion succeeded, then ALL of the client-disconnect functions for1935 scripts and plugins will be called on client instance object1936 deletion, even in cases where some of the related client-connect1937 functions returnedan error status.1938 1939 The --client-disconnect command is passed the same pathname as1940 the corresponding --client-connect command as its last argument.1941 (afterany arguments specified in cmd ).1870 Like --client-connect but called on client instance shutdown. Will 1871 not be called unless the --client-connect script and plugins (if 1872 defined) were previously called on this instance with successful 1873 (0) status returns. 1874 1875 The exception to this rule is if the --client-disconnect command or 1876 plugins are cascaded, and at least one client-connect function suc‐ 1877 ceeded, then ALL of the client-disconnect functions for scripts and 1878 plugins will be called on client instance object deletion, even in 1879 cases where some of the related client-connect functions returned 1880 an error status. 1881 1882 The --client-disconnect command is passed the same pathname as the 1883 corresponding --client-connect command as its last argument. (after 1884 any arguments specified in cmd ). 1942 1885 1943 1886 --client-config-dir dir 1944 Specify a directory dir for custom client config files. After a 1945 connecting client has been authenticated, OpenVPN will look in 1946 this directory for a file having the same name as the client's 1947 X509 common name. If a matching file exists, it will be opened 1948 and parsed for client-specific configuration options. If no 1949 matching file is found, OpenVPN will instead try to open and 1950 parse a default file called "DEFAULT", which may be provided but 1951 is not required. Note that the configuration files must be read‐ 1952 able by the OpenVPN process after it has dropped it's root priv‐ 1953 ileges. 1954 1955 This file can specify a fixed IP address for a given client 1956 using --ifconfig-push, as well as fixed subnets owned by the 1957 client using --iroute. 1958 1959 One of the useful properties of this option is that it allows 1960 client configuration files to be conveniently created, edited, 1961 or removed while the server is live, without needing to restart 1962 the server. 1963 1964 The following options are legal in a client-specific context: 1887 Specify a directory dir for custom client config files. After a 1888 connecting client has been authenticated, OpenVPN will look in this 1889 directory for a file having the same name as the client's X509 com‐ 1890 mon name. If a matching file exists, it will be opened and parsed 1891 for client-specific configuration options. If no matching file is 1892 found, OpenVPN will instead try to open and parse a default file 1893 called "DEFAULT", which may be provided but is not required. Note 1894 that the configuration files must be readable by the OpenVPN 1895 process after it has dropped it's root privileges. 1896 1897 This file can specify a fixed IP address for a given client using 1898 --ifconfig-push, as well as fixed subnets owned by the client using 1899 --iroute. 1900 1901 One of the useful properties of this option is that it allows 1902 client configuration files to be conveniently created, edited, or 1903 removed while the server is live, without needing to restart the 1904 server. 1905 1906 The following options are legal in a client-specific context: 1965 1907 --push, --push-reset, --iroute, --ifconfig-push, and --config. 1966 1908 1967 1909 --ccd-exclusive 1968 Require, as a condition of authentication, that a connecting1969 clienthas a --client-config-dir file.1910 Require, as a condition of authentication, that a connecting client 1911 has a --client-config-dir file. 1970 1912 1971 1913 --tmp-dir dir 1972 Specify a directory dir for temporary files. This directory1973 will be used by openvpn processes and script to communicate tem‐1974 porary data with openvpn main process. Note that the directory1975 must be writable by the OpenVPN process after it has dropped1976 it's rootprivileges.1914 Specify a directory dir for temporary files. This directory will 1915 be used by openvpn processes and script to communicate temporary 1916 data with openvpn main process. Note that the directory must be 1917 writable by the OpenVPN process after it has dropped it's root 1918 privileges. 1977 1919 1978 1920 This directory will be used by in the following cases: 1979 1921 1980 * --client-connect scripts to dynamically generate client-spe‐ 1981 cific configuration files. 1982 1983 * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin hook to return 1984 success/failure via auth_control_file when using deferred auth 1985 method 1986 1987 * OPENVPN_PLUGIN_ENABLE_PF plugin hook to pass filtering rules 1988 via pf_file 1922 * --client-connect scripts to dynamically generate client-specific 1923 configuration files. 1924 1925 * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin hook to return suc‐ 1926 cess/failure via auth_control_file when using deferred auth method 1927 1928 * OPENVPN_PLUGIN_ENABLE_PF plugin hook to pass filtering rules via 1929 pf_file 1989 1930 1990 1931 --hash-size r v 1991 Set the size of the real address hash table to r and thevirtual1992 address table to v. By default, both tables are sized at 2561993 buckets.1932 Set the size of the real address hash table to r and the virtual 1933 address table to v. By default, both tables are sized at 256 buck‐ 1934 ets. 1994 1935 1995 1936 --bcast-buffers n … … 1999 1940 Maximum number of output packets queued before TCP (default=64). 2000 1941 2001 When OpenVPN is tunneling data from a TUN/TAP device to aremote2002 client over a TCP connection, it is possible that theTUN/TAP2003 device might produce data at a faster rate than the TCP connec‐2004 tion can support. When the number of output packets queued2005 before sending to the TCP socket reaches this limit for a given2006 client connection, OpenVPN will start to drop outgoing packets2007 directed at thisclient.1942 When OpenVPN is tunneling data from a TUN/TAP device to a remote 1943 client over a TCP connection, it is possible that the TUN/TAP 1944 device might produce data at a faster rate than the TCP connection 1945 can support. When the number of output packets queued before send‐ 1946 ing to the TCP socket reaches this limit for a given client connec‐ 1947 tion, OpenVPN will start to drop outgoing packets directed at this 1948 client. 2008 1949 2009 1950 --tcp-nodelay 2010 This macro sets the TCP_NODELAY socket flag on the server as2011 well as pushes it to connecting clients. The TCP_NODELAY flag2012 disables the Nagle algorithm on TCP sockets causing packets to2013 be transmitted immediately with low latency, rather than waiting2014 a short period of time in order to aggregate several packets2015 into a larger containing packet. In VPN applications over TCP,2016 TCP_NODELAY isgenerally a good latency optimization.1951 This macro sets the TCP_NODELAY socket flag on the server as well 1952 as pushes it to connecting clients. The TCP_NODELAY flag disables 1953 the Nagle algorithm on TCP sockets causing packets to be transmit‐ 1954 ted immediately with low latency, rather than waiting a short 1955 period of time in order to aggregate several packets into a larger 1956 containing packet. In VPN applications over TCP, TCP_NODELAY is 1957 generally a good latency optimization. 2017 1958 2018 1959 The macro expands as follows: … … 2026 1967 2027 1968 --max-routes-per-client n 2028 Allow a maximum of n internal routes per client (default=256). 2029 This is designed to help contain DoS attacks where an authenti‐ 2030 cated client floods the server with packets appearing to come 2031 from many unique MAC addresses, forcing the server to deplete 2032 virtual memory as its internal routing table expands. This 2033 directive can be used in a --client-config-dir file or auto-gen‐ 2034 erated by a --client-connect script to override the global value 2035 for a particular client. 2036 2037 Note that this directive affects OpenVPN's internal routing ta‐ 2038 ble, not the kernel routing table. 1969 Allow a maximum of n internal routes per client (default=256). 1970 This is designed to help contain DoS attacks where an authenticated 1971 client floods the server with packets appearing to come from many 1972 unique MAC addresses, forcing the server to deplete virtual memory 1973 as its internal routing table expands. This directive can be used 1974 in a --client-config-dir file or auto-generated by a --client-con‐ 1975 nect script to override the global value for a particular client. 1976 1977 Note that this directive affects OpenVPN's internal routing table, 1978 not the kernel routing table. 2039 1979 2040 1980 --stale-routes-check n [t] 2041 Remove routes haven't had activity for n seconds (i.e. the age‐2042 ingtime).1981 Remove routes haven't had activity for n seconds (i.e. the ageing 1982 time). 2043 1983 2044 1984 This check is ran every t seconds (i.e. check interval). … … 2046 1986 If t is not present it defaults to n 2047 1987 2048 This option helps to keep the dynamic routing tablesmall. See1988 This option helps to keep the dynamic routing table small. See 2049 1989 also --max-routes-per-client 2050 1990 2051 1991 --connect-freq n sec 2052 Allow a maximum of n new connections per sec seconds from2053 clients. This is designed to contain DoS attacks which flood2054 the server with connection requests using certificates which2055 will ultimately failto authenticate.2056 2057 This is an imperfect solution however, because in a real DoS2058 scenario, legitimate connections might also be refused.2059 2060 For the best protectionagainst DoS attacks in server mode, use1992 Allow a maximum of n new connections per sec seconds from clients. 1993 This is designed to contain DoS attacks which flood the server with 1994 connection requests using certificates which will ultimately fail 1995 to authenticate. 1996 1997 This is an imperfect solution however, because in a real DoS sce‐ 1998 nario, legitimate connections might also be refused. 1999 2000 For the best protection against DoS attacks in server mode, use 2061 2001 --proto udp and --tls-auth. 2062 2002 … … 2064 2004 Run command cmd to validate client virtual addresses or routes. 2065 2005 2066 cmd consists of a path to script (or executable program),2067 optionally followed by arguments. The path and arguments may be2068 single- or double-quoted and/or escaped using a backslash, and2069 s hould be separated by one or more spaces.2070 2071 Three arguments willbe appended to any arguments in cmd as fol‐2006 cmd consists of a path to script (or executable program), option‐ 2007 ally followed by arguments. The path and arguments may be single- 2008 or double-quoted and/or escaped using a backslash, and should be 2009 separated by one or more spaces. 2010 2011 Three arguments will be appended to any arguments in cmd as fol‐ 2072 2012 lows: 2073 2013 2074 [1] operation -- "add", "update", or "delete" based on whether2075 or not the address is being added to, modified, or deleted from2076 OpenVPN's internal routing table.2077 [2] address -- The address being learned or unlearned. This can 2078 be an IPv4 address such as "198.162.10.14", an IPv4 subnet such2079 as "198.162.10.0/24", or an ethernet MAC address (when --dev tap2080 isbeing used) such as "00:FF:01:02:03:04".2081 [3] common name-- The common name on the certificate associated2082 with the client linked to this address. Only present for "add"2083 or"update" operations, not "delete".2084 2085 On "add" or "update" methods, if the script returns a failure2086 code (non-zero), OpenVPN will reject the address and will not2087 modify itsinternal routing table.2088 2089 Normally, the cmd script will use the information provided above 2090 to set appropriate firewall entries on the VPN TUN/TAP inter‐2091 face. Since OpenVPN provides the association between virtual IP2092 or MAC address and the client's authenticated common name, it2093 allows a user-defined script to configure firewall access poli‐2094 cies with regard to the client's high-level common name, rather2095 than the lowlevel client virtual addresses.2014 [1] operation -- "add", "update", or "delete" based on whether or 2015 not the address is being added to, modified, or deleted from Open‐ 2016 VPN's internal routing table. 2017 [2] address -- The address being learned or unlearned. This can be 2018 an IPv4 address such as "198.162.10.14", an IPv4 subnet such as 2019 "198.162.10.0/24", or an ethernet MAC address (when --dev tap is 2020 being used) such as "00:FF:01:02:03:04". 2021 [3] common name -- The common name on the certificate associated 2022 with the client linked to this address. Only present for "add" or 2023 "update" operations, not "delete". 2024 2025 On "add" or "update" methods, if the script returns a failure code 2026 (non-zero), OpenVPN will reject the address and will not modify its 2027 internal routing table. 2028 2029 Normally, the cmd script will use the information provided above to 2030 set appropriate firewall entries on the VPN TUN/TAP interface. 2031 Since OpenVPN provides the association between virtual IP or MAC 2032 address and the client's authenticated common name, it allows a 2033 user-defined script to configure firewall access policies with 2034 regard to the client's high-level common name, rather than the low 2035 level client virtual addresses. 2096 2036 2097 2037 --auth-user-pass-verify cmd method 2098 Require the client to providea username/password (possibly in2038 Require the client to provide a username/password (possibly in 2099 2039 addition to a client certificate) for authentication. 2100 2040 2101 OpenVPN will run command cmd to validate the username/password 2102 provided by the client. 2103 2104 cmd consists of a path to script (or executable program), 2105 optionally followed by arguments. The path and arguments may be 2106 single- or double-quoted and/or escaped using a backslash, and 2107 should be separated by one or more spaces. 2108 2109 If method is set to "via-env", OpenVPN will call script with the 2110 environmental variables username and password set to the user‐ 2111 name/password strings provided by the client. Be aware that 2112 this method is insecure on some platforms which make the envi‐ 2113 ronment of a process publicly visible to other unprivileged pro‐ 2114 cesses. 2115 2116 If method is set to "via-file", OpenVPN will write the username 2117 and password to the first two lines of a temporary file. The 2118 filename will be passed as an argument to script, and the file 2119 will be automatically deleted by OpenVPN after the script 2120 returns. The location of the temporary file is controlled by 2121 the --tmp-dir option, and will default to the current directory 2122 if unspecified. For security, consider setting --tmp-dir to a 2123 volatile storage medium such as /dev/shm (if available) to pre‐ 2124 vent the username/password file from touching the hard drive. 2125 2126 The script should examine the username and password, returning a 2127 success exit code (0) if the client's authentication request is 2128 to be accepted, or a failure code (1) to reject the client. 2129 2130 This directive is designed to enable a plugin-style interface 2131 for extending OpenVPN's authentication capabilities. 2132 2133 To protect against a client passing a maliciously formed user‐ 2134 name or password string, the username string must consist only 2135 of these characters: alphanumeric, underbar ('_'), dash ('-'), 2136 dot ('.'), or at ('@'). The password string can consist of any 2137 printable characters except for CR or LF. Any illegal charac‐ 2138 ters in either the username or password string will be converted 2139 to underbar ('_'). 2140 2141 Care must be taken by any user-defined scripts to avoid creating 2142 a security vulnerability in the way that these strings are han‐ 2143 dled. Never use these strings in such a way that they might be 2144 escaped or evaluated by a shell interpreter. 2145 2146 For a sample script that performs PAM authentication, see sam‐ 2147 ple-scripts/auth-pam.pl in the OpenVPN source distribution. 2041 OpenVPN will run command cmd to validate the username/password pro‐ 2042 vided by the client. 2043 2044 cmd consists of a path to script (or executable program), option‐ 2045 ally followed by arguments. The path and arguments may be single- 2046 or double-quoted and/or escaped using a backslash, and should be 2047 separated by one or more spaces. 2048 2049 If method is set to "via-env", OpenVPN will call script with the 2050 environmental variables username and password set to the user‐ 2051 name/password strings provided by the client. Be aware that this 2052 method is insecure on some platforms which make the environment of 2053 a process publicly visible to other unprivileged processes. 2054 2055 If method is set to "via-file", OpenVPN will write the username and 2056 password to the first two lines of a temporary file. The filename 2057 will be passed as an argument to script, and the file will be auto‐ 2058 matically deleted by OpenVPN after the script returns. The loca‐ 2059 tion of the temporary file is controlled by the --tmp-dir option, 2060 and will default to the current directory if unspecified. For 2061 security, consider setting --tmp-dir to a volatile storage medium 2062 such as /dev/shm (if available) to prevent the username/password 2063 file from touching the hard drive. 2064 2065 The script should examine the username and password, returning a 2066 success exit code (0) if the client's authentication request is to 2067 be accepted, or a failure code (1) to reject the client. 2068 2069 This directive is designed to enable a plugin-style interface for 2070 extending OpenVPN's authentication capabilities. 2071 2072 To protect against a client passing a maliciously formed username 2073 or password string, the username string must consist only of these 2074 characters: alphanumeric, underbar ('_'), dash ('-'), dot ('.'), or 2075 at ('@'). The password string can consist of any printable charac‐ 2076 ters except for CR or LF. Any illegal characters in either the 2077 username or password string will be converted to underbar ('_'). 2078 2079 Care must be taken by any user-defined scripts to avoid creating a 2080 security vulnerability in the way that these strings are handled. 2081 Never use these strings in such a way that they might be escaped or 2082 evaluated by a shell interpreter. 2083 2084 For a sample script that performs PAM authentication, see sample- 2085 scripts/auth-pam.pl in the OpenVPN source distribution. 2148 2086 2149 2087 --opt-verify 2150 Clients that connect with options that are incompatible with2151 thoseof the server will be disconnected.2152 2153 Options that will be compared for compatibility include dev-2154 type, link-mtu, tun-mtu, proto, tun-ipv6, ifconfig, comp-lzo,2155 fragment, keydir, cipher, auth, keysize, secret, no-replay, no-2156 iv, tls-auth,key-method, tls-server, and tls-client.2088 Clients that connect with options that are incompatible with those 2089 of the server will be disconnected. 2090 2091 Options that will be compared for compatibility include dev-type, 2092 link-mtu, tun-mtu, proto, tun-ipv6, ifconfig, comp-lzo, fragment, 2093 keydir, cipher, auth, keysize, secret, no-replay, no-iv, tls-auth, 2094 key-method, tls-server, and tls-client. 2157 2095 2158 2096 This option requires that --disable-occ NOT be used. 2159 2097 2160 2098 --auth-user-pass-optional 2161 Allow connections by clients that do not specify a user‐ 2162 name/password. Normally, when --auth-user-pass-verify or --man‐ 2163 agement-client-auth is specified (or an authentication plugin 2164 module), the OpenVPN server daemon will require connecting 2165 clients to specify a username and password. This option makes 2166 the submission of a username/password by clients optional, pass‐ 2167 ing the responsibility to the user-defined authentication mod‐ 2168 ule/script to accept or deny the client based on other factors 2169 (such as the setting of X509 certificate fields). When this 2170 option is used, and a connecting client does not submit a user‐ 2171 name/password, the user-defined authentication module/script 2172 will see the username and password as being set to empty strings 2173 (""). The authentication module/script MUST have logic to 2174 detect this condition and respond accordingly. 2099 Allow connections by clients that do not specify a username/pass‐ 2100 word. Normally, when --auth-user-pass-verify or --management- 2101 client-auth is specified (or an authentication plugin module), the 2102 OpenVPN server daemon will require connecting clients to specify a 2103 username and password. This option makes the submission of a user‐ 2104 name/password by clients optional, passing the responsibility to 2105 the user-defined authentication module/script to accept or deny the 2106 client based on other factors (such as the setting of X509 certifi‐ 2107 cate fields). When this option is used, and a connecting client 2108 does not submit a username/password, the user-defined authentica‐ 2109 tion module/script will see the username and password as being set 2110 to empty strings (""). The authentication module/script MUST have 2111 logic to detect this condition and respond accordingly. 2175 2112 2176 2113 --client-cert-not-required 2177 Don't require client certificate, client will authenticateusing2178 username/password only. Be aware that using this directive is2179 lesssecure than requiring certificates from all clients.2180 2181 If you use this directive, the entire responsibility of authen‐2182 ti cation will rest on your --auth-user-pass-verify script, so2183 keep in mind that bugs in your script could potentially compro‐2184 mise thesecurity of your VPN.2185 2186 If you don'tuse this directive, but you also specify an --auth-2187 user-pass-verify script, then OpenVPN will perform double2188 authentication. The client certificate verification AND the2189 --auth-user-pass-verify script will need to succeed in order for2190 a client to be authenticated and accepted onto the VPN.2114 Don't require client certificate, client will authenticate using 2115 username/password only. Be aware that using this directive is less 2116 secure than requiring certificates from all clients. 2117 2118 If you use this directive, the entire responsibility of authentica‐ 2119 tion will rest on your --auth-user-pass-verify script, so keep in 2120 mind that bugs in your script could potentially compromise the 2121 security of your VPN. 2122 2123 If you don't use this directive, but you also specify an --auth- 2124 user-pass-verify script, then OpenVPN will perform double authenti‐ 2125 cation. The client certificate verification AND the --auth-user- 2126 pass-verify script will need to succeed in order for a client to be 2127 authenticated and accepted onto the VPN. 2191 2128 2192 2129 --username-as-common-name 2193 For --auth-user-pass-verify authentication, use the authenti‐2194 cated username as the common name, rather than the common name2195 from theclient cert.2196 2197 --compat-names [no-remapping] 2198 Until OpenVPN v2.3 the format of the X.509 Subject fields was2199 formatted like this:2130 For --auth-user-pass-verify authentication, use the authenticated 2131 username as the common name, rather than the common name from the 2132 client cert. 2133 2134 --compat-names [no-remapping] (DEPRECATED) 2135 Until OpenVPN v2.3 the format of the X.509 Subject fields was for‐ 2136 matted like this: 2200 2137 2201 2138 /C=US/L=Somewhere/CN=John Doe/emailAddress=john@example.com 2202 2139 2203 In addition the old behavivour was to remap any characterother2204 than alphanumeric, underscore ('_'), dash ('-'), dot ('.'),and2205 slash ('/') to underscore ('_'). The X.509 Subject stringas2206 returned by the tls_id environmental variable, could addition‐2207 allycontain colon (':') or equal ('=').2208 2209 When using the --compat-names option, this old formattingand2210 remapping will be re-enabled again. This is purely implemented2211 for compatibility reasons when using older plug-ins or scripts2212 whichdoes not handle the new formatting or UTF-8 characters.2213 2214 In OpenVPN v2.3 the formatting of these fields changed into a2215 morestandardised format. It now looks like:2140 In addition the old behavivour was to remap any character other 2141 than alphanumeric, underscore ('_'), dash ('-'), dot ('.'), and 2142 slash ('/') to underscore ('_'). The X.509 Subject string as 2143 returned by the tls_id environmental variable, could additionally 2144 contain colon (':') or equal ('='). 2145 2146 When using the --compat-names option, this old formatting and 2147 remapping will be re-enabled again. This is purely implemented for 2148 compatibility reasons when using older plug-ins or scripts which 2149 does not handle the new formatting or UTF-8 characters. 2150 2151 In OpenVPN v2.3 the formatting of these fields changed into a more 2152 standardised format. It now looks like: 2216 2153 2217 2154 C=US, L=Somewhere, CN=John Doe, emailAddress=john@example.com 2218 2155 2219 The new default format in OpenVPN v2.3 also does not do the 2220 character remapping which happened earlier. This new format 2221 enables proper support for UTF-8 characters in the usernames, 2222 X.509 Subject fields and Common Name variables and it complies 2223 to the RFC 2253, UTF-8 String Representation of Distinguished 2224 Names. 2225 2226 As a backwards compatibility for the removed --no-name-remapping 2227 feature in older OpenVPN versions, the no-remapping mode flag 2228 can be used with the --compat-names option. When this mode flag 2229 is used, the Common Name, Subject, and username strings are 2230 allowed to include any printable character including space, but 2231 excluding control characters such as tab, newline, and carriage- 2232 return. It ensures compatibility with the --no-name-remapping 2233 option of OpenVPN versions before v2.3. 2234 2235 Please note: This option will not be around for a long time. It 2236 is only implemented to make the transition to the new formatting 2237 less intrusive. It will be removed either in OpenVPN v2.4 or 2238 v2.5. So please make sure you start the process to support the 2239 new formatting as soon as possible. 2156 The new default format in OpenVPN v2.3 also does not do the charac‐ 2157 ter remapping which happened earlier. This new format enables 2158 proper support for UTF-8 characters in the usernames, X.509 Subject 2159 fields and Common Name variables and it complies to the RFC 2253, 2160 UTF-8 String Representation of Distinguished Names. 2161 2162 The no-remapping mode flag can be used with the --compat-names 2163 option to be compatible with the now deprecated --no-name-remapping 2164 option. It is only available at the server. When this mode flag is 2165 used, the Common Name, Subject, and username strings are allowed to 2166 include any printable character including space, but excluding con‐ 2167 trol characters such as tab, newline, and carriage-return. no- 2168 remapping is only available on the server side. 2169 2170 Please note: This option is immediately deprecated. It is only 2171 implemented to make the transition to the new formatting less 2172 intrusive. It will be removed either in OpenVPN v2.4 or v2.5. So 2173 please make sure you use the --verify-x509-name option instead of 2174 --tls-remote as soon as possible and update your scripts where nec‐ 2175 essary. 2176 2177 --no-name-remapping (DEPRECATED) 2178 The --no-name-remapping option is an alias for --com‐ 2179 pat-names no-remapping. It ensures compatibility with server con‐ 2180 figurations using the --no-name-remapping option. 2181 2182 Please note: This option is now deprecated. It will be removed 2183 either in OpenVPN v2.4 or v2.5. So please make sure you support 2184 the new X.509 name formatting described with the --compat-names 2185 option as soon as possible. 2240 2186 2241 2187 --port-share host port [dir] 2242 When run in TCP server mode, share the OpenVPN port withanother2243 application, such as an HTTPS server. If OpenVPN senses a con‐2244 nection to its port which is using a non-OpenVPN protocol, it2245 will proxy the connection to the server at host:port. Currently2246 only designed to work with HTTP/HTTPS, though it would be theo‐2247 reticallypossible to extend to other protocols such as ssh.2248 2249 dir specifies an optional directory where a temporary filewith2250 name N containing content C will be dynamically generated for2251 each proxy connection, where N is the source IP:port of the2252 client connection and C is the source IP:port of the connection2253 to the proxy receiver. This directory can be used as a dictio‐2254 nary by the proxy receiver to determine the origin of the con‐2255 nection. Each generated file will be automatically deleted when2256 t he proxied connection is torn down.2188 When run in TCP server mode, share the OpenVPN port with another 2189 application, such as an HTTPS server. If OpenVPN senses a connec‐ 2190 tion to its port which is using a non-OpenVPN protocol, it will 2191 proxy the connection to the server at host:port. Currently only 2192 designed to work with HTTP/HTTPS, though it would be theoretically 2193 possible to extend to other protocols such as ssh. 2194 2195 dir specifies an optional directory where a temporary file with 2196 name N containing content C will be dynamically generated for each 2197 proxy connection, where N is the source IP:port of the client con‐ 2198 nection and C is the source IP:port of the connection to the proxy 2199 receiver. This directory can be used as a dictionary by the proxy 2200 receiver to determine the origin of the connection. Each generated 2201 file will be automatically deleted when the proxied connection is 2202 torn down. 2257 2203 2258 2204 Not implemented on Windows. 2259 2205 2260 2206 Client Mode 2261 Use client mode when connecting to an OpenVPN server which has2262 --server , --server-bridge, or --mode server in it's configuration.2207 Use client mode when connecting to an OpenVPN server which has --server, 2208 --server-bridge, or --mode server in it's configuration. 2263 2209 2264 2210 --client 2265 A helper directive designed to simplify the configuration of2266 OpenVPN's client mode. This directive is equivalent to:2211 A helper directive designed to simplify the configuration of Open‐ 2212 VPN's client mode. This directive is equivalent to: 2267 2213 2268 2214 pull 2269 2215 tls-client 2270 2216 2271 --pull This option must be used on a client which is connecting toa2272 multi-client server. It indicates to OpenVPN that it should2273 accept options pushed by the server, provided they are part of2274 the legal set of pushable options (note that the --pull option2275 is implied by--client ).2276 2277 In particular, --pull allows the server to push routes tothe2278 client, so you should not use --pull or --client insituations2279 where you don't trust the server to have control over the2280 client'srouting table.2217 --pull This option must be used on a client which is connecting to a 2218 multi-client server. It indicates to OpenVPN that it should accept 2219 options pushed by the server, provided they are part of the legal 2220 set of pushable options (note that the --pull option is implied by 2221 --client ). 2222 2223 In particular, --pull allows the server to push routes to the 2224 client, so you should not use --pull or --client in situations 2225 where you don't trust the server to have control over the client's 2226 routing table. 2281 2227 2282 2228 --auth-user-pass [up] 2283 Authenticate with server using username/password. up is afile2284 containing username/password on 2 lines (Note: OpenVPN willonly2285 read passwords from a file if it has been built with the2286 --enable-password-save configure option, or on Windows by defin‐2287 ingENABLE_PASSWORD_SAVE in win/settings.in).2288 2289 If up is omitted, username/password will be prompted from the2290 console.2291 2292 The server configuration must specify an--auth-user-pass-verify2229 Authenticate with server using username/password. up is a file 2230 containing username/password on 2 lines (Note: OpenVPN will only 2231 read passwords from a file if it has been built with the --enable- 2232 password-save configure option, or on Windows by defining 2233 ENABLE_PASSWORD_SAVE in win/settings.in). 2234 2235 If up is omitted, username/password will be prompted from the con‐ 2236 sole. 2237 2238 The server configuration must specify an --auth-user-pass-verify 2293 2239 script to verify the username/password provided by the client. 2294 2240 2295 2241 --auth-retry type 2296 Controls how OpenVPN responds to username/password verification 2297 errors such as the client-side response to an AUTH_FAILED mes‐ 2298 sage from the server or verification failure of the private key 2299 password. 2300 2301 Normally used to prevent auth errors from being fatal on the 2302 client side, and to permit username/password requeries in case 2303 of error. 2304 2305 An AUTH_FAILED message is generated by the server if the client 2306 fails --auth-user-pass authentication, or if the server-side 2307 --client-connect script returns an error status when the client 2242 Controls how OpenVPN responds to username/password verification 2243 errors such as the client-side response to an AUTH_FAILED message 2244 from the server or verification failure of the private key pass‐ 2245 word. 2246 2247 Normally used to prevent auth errors from being fatal on the client 2248 side, and to permit username/password requeries in case of error. 2249 2250 An AUTH_FAILED message is generated by the server if the client 2251 fails --auth-user-pass authentication, or if the server-side 2252 --client-connect script returns an error status when the client 2308 2253 tries to connect. 2309 2254 2310 2255 type can be one of: 2311 2256 2312 none -- Client will exit with a fatal error (this is the 2313 default). 2314 nointeract -- Client will retry the connection without requery‐ 2315 ing for an --auth-user-pass username/password. Use this option 2316 for unattended clients. 2317 interact -- Client will requery for an --auth-user-pass user‐ 2318 name/password and/or private key password before attempting a 2257 none -- Client will exit with a fatal error (this is the default). 2258 nointeract -- Client will retry the connection without requerying 2259 for an --auth-user-pass username/password. Use this option for 2260 unattended clients. 2261 interact -- Client will requery for an --auth-user-pass user‐ 2262 name/password and/or private key password before attempting a 2319 2263 reconnection. 2320 2264 2321 Note that while this option cannot be pushed, it can be con‐2322 trolledfrom the management interface.2265 Note that while this option cannot be pushed, it can be controlled 2266 from the management interface. 2323 2267 2324 2268 --static-challenge t e 2325 Enable static challenge/response protocol using challenge text2326 t,with echo flag given by e (0|1).2327 2328 The echo flag indicates whether or not the user's response to2329 thechallenge should be echoed.2330 2331 See management-notes.txt in the OpenVPN distribution for a2332 description of the OpenVPN challenge/response protocol.2269 Enable static challenge/response protocol using challenge text t, 2270 with echo flag given by e (0|1). 2271 2272 The echo flag indicates whether or not the user's response to the 2273 challenge should be echoed. 2274 2275 See management-notes.txt in the OpenVPN distribution for a descrip‐ 2276 tion of the OpenVPN challenge/response protocol. 2333 2277 2334 2278 --server-poll-timeout n 2335 when polling possible remote servers to connect to in a round-2336 robin fashion, spend no more than n seconds waiting for a2337 response beforetrying the next server.2279 when polling possible remote servers to connect to in a round-robin 2280 fashion, spend no more than n seconds waiting for a response before 2281 trying the next server. 2338 2282 2339 2283 --explicit-exit-notify [n] 2340 In UDP client mode or point-to-point mode, send server/peer an2341 exit notification if tunnel is restarted or OpenVPN process is2342 exited. In client mode, on exit/restart, this option will tell2343 t he server to immediately close its client instance object2344 rather than waiting for a timeout. The n parameter (default=1)2345 controls the maximum number of attempts that the client will try2346 to resend the exit notification message. OpenVPN will not send2347 any exit notificationsunless this option is enabled.2284 In UDP client mode or point-to-point mode, send server/peer an exit 2285 notification if tunnel is restarted or OpenVPN process is exited. 2286 In client mode, on exit/restart, this option will tell the server 2287 to immediately close its client instance object rather than waiting 2288 for a timeout. The n parameter (default=1) controls the maximum 2289 number of attempts that the client will try to resend the exit 2290 notification message. OpenVPN will not send any exit notifications 2291 unless this option is enabled. 2348 2292 2349 2293 Data Channel Encryption Options: 2350 These options aremeaningful for both Static & TLS-negotiated key modes2294 These options are meaningful for both Static & TLS-negotiated key modes 2351 2295 (must be compatible between peers). 2352 2296 2353 2297 --secret file [direction] 2354 Enable Static Key encryption mode (non-TLS). Use pre-shared 2355 secret file which was generated with --genkey. 2356 2357 The optional direction parameter enables the use of 4 distinct 2358 keys (HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), 2359 so that each data flow direction has a different set of HMAC and 2360 cipher keys. This has a number of desirable security properties 2361 including eliminating certain kinds of DoS and message replay 2362 attacks. 2363 2364 When the direction parameter is omitted, 2 keys are used bidi‐ 2365 rectionally, one for HMAC and the other for encryption/decryp‐ 2366 tion. 2367 2368 The direction parameter should always be complementary on either 2369 side of the connection, i.e. one side should use "0" and the 2370 other should use "1", or both sides should omit it altogether. 2371 2372 The direction parameter requires that file contains a 2048 bit 2373 key. While pre-1.5 versions of OpenVPN generate 1024 bit key 2374 files, any version of OpenVPN which supports the direction 2375 parameter, will also support 2048 bit key file generation using 2376 the --genkey option. 2377 2378 Static key encryption mode has certain advantages, the primary 2298 Enable Static Key encryption mode (non-TLS). Use pre-shared secret 2299 file which was generated with --genkey. 2300 2301 The optional direction parameter enables the use of 4 distinct keys 2302 (HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that 2303 each data flow direction has a different set of HMAC and cipher 2304 keys. This has a number of desirable security properties including 2305 eliminating certain kinds of DoS and message replay attacks. 2306 2307 When the direction parameter is omitted, 2 keys are used bidirec‐ 2308 tionally, one for HMAC and the other for encryption/decryption. 2309 2310 The direction parameter should always be complementary on either 2311 side of the connection, i.e. one side should use "0" and the other 2312 should use "1", or both sides should omit it altogether. 2313 2314 The direction parameter requires that file contains a 2048 bit key. 2315 While pre-1.5 versions of OpenVPN generate 1024 bit key files, any 2316 version of OpenVPN which supports the direction parameter, will 2317 also support 2048 bit key file generation using the --genkey 2318 option. 2319 2320 Static key encryption mode has certain advantages, the primary 2379 2321 being ease of configuration. 2380 2322 2381 There are no certificates or certificate authorities or compli‐2382 cated negotiation handshakes and protocols. The only require‐2383 ment is that you have a pre-existing secure channel with your2384 peer (such as ssh ) to initially copy the key. This require‐2385 ment, along with the fact that your key never changes unless you2386 ma nually generate a new one, makes it somewhat less secure than2387 TLS mode (see below). If an attacker manages to steal your key,2388 e verything that was ever encrypted with it is compromised. Con‐2389 trast that to the perfect forward secrecy features of TLS mode2390 (using Diffie Hellman key exchange), where even if an attacker2391 was able to steal your private key, he would gain no information2392 to help him decrypt past sessions.2393 2394 Another advantageous aspect of Static Key encryption mode is2395 that it is a handshake-free protocol without any distinguishing2396 signature or feature (such as a header or protocol handshake2397 sequence) that would mark the ciphertext packets as being gener‐2398 ated by OpenVPN. Anyone eavesdropping on the wire would see2399 nothing but random-looking data.2323 There are no certificates or certificate authorities or complicated 2324 negotiation handshakes and protocols. The only requirement is that 2325 you have a pre-existing secure channel with your peer (such as ssh 2326 ) to initially copy the key. This requirement, along with the fact 2327 that your key never changes unless you manually generate a new one, 2328 makes it somewhat less secure than TLS mode (see below). If an 2329 attacker manages to steal your key, everything that was ever 2330 encrypted with it is compromised. Contrast that to the perfect 2331 forward secrecy features of TLS mode (using Diffie Hellman key 2332 exchange), where even if an attacker was able to steal your private 2333 key, he would gain no information to help him decrypt past ses‐ 2334 sions. 2335 2336 Another advantageous aspect of Static Key encryption mode is that 2337 it is a handshake-free protocol without any distinguishing signa‐ 2338 ture or feature (such as a header or protocol handshake sequence) 2339 that would mark the ciphertext packets as being generated by Open‐ 2340 VPN. Anyone eavesdropping on the wire would see nothing but ran‐ 2341 dom-looking data. 2400 2342 2401 2343 --key-direction 2402 Alternative way of specifying the optional direction parameter2403 for the --tls-auth and --secret options. Useful when using2404 inline files(See section on inline files).2344 Alternative way of specifying the optional direction parameter for 2345 the --tls-auth and --secret options. Useful when using inline files 2346 (See section on inline files). 2405 2347 2406 2348 --auth alg 2407 Authenticate packets with HMAC using message digest algorithm2408 alg. (The default is SHA1 ). HMAC is a commonly used message2409 authentication algorithm (MAC) that uses a data string, a secure2410 hash algorithm, and a key, to produce a digital signature.2411 2412 OpenVPN's usage of HMAC is to first encrypt a packet, then HMAC2413 theresulting ciphertext.2414 2415 In static-key encryption mode, the HMAC key is included in the2416 key file generated by --genkey. In TLS mode, the HMAC key is2417 dynamically generated and shared between peers via the TLS con‐2418 trol channel. If OpenVPN receives a packet with a bad HMAC it2419 will drop the packet. HMAC usually adds 16 or 20 bytes per2420 packet. Set alg=noneto disable authentication.2421 2422 For more information on HMACsee2349 Authenticate packets with HMAC using message digest algorithm alg. 2350 (The default is SHA1 ). HMAC is a commonly used message authenti‐ 2351 cation algorithm (MAC) that uses a data string, a secure hash algo‐ 2352 rithm, and a key, to produce a digital signature. 2353 2354 OpenVPN's usage of HMAC is to first encrypt a packet, then HMAC the 2355 resulting ciphertext. 2356 2357 In static-key encryption mode, the HMAC key is included in the key 2358 file generated by --genkey. In TLS mode, the HMAC key is dynami‐ 2359 cally generated and shared between peers via the TLS control chan‐ 2360 nel. If OpenVPN receives a packet with a bad HMAC it will drop the 2361 packet. HMAC usually adds 16 or 20 bytes per packet. Set alg=none 2362 to disable authentication. 2363 2364 For more information on HMAC see 2423 2365 http://www.cs.ucsd.edu/users/mihir/papers/hmac.html 2424 2366 2425 2367 --cipher alg 2426 Encrypt packets with cipher algorithm alg. The default is BF-2427 CBC, an abbreviation for Blowfish in Cipher Block Chaining mode.2428 Blowfish has the advantages of being fast, very secure, and2429 allowing key sizes of up to 448 bits. Blowfish is designed to2430 be used insituations where keys are changed infrequently.2431 2432 For more information on blowfish, seehttp://www.counter‐2368 Encrypt packets with cipher algorithm alg. The default is BF-CBC, 2369 an abbreviation for Blowfish in Cipher Block Chaining mode. Blow‐ 2370 fish has the advantages of being fast, very secure, and allowing 2371 key sizes of up to 448 bits. Blowfish is designed to be used in 2372 situations where keys are changed infrequently. 2373 2374 For more information on blowfish, see http://www.counter‐ 2433 2375 pane.com/blowfish.html 2434 2376 2435 To see other ciphers that are available with OpenVPN, usethe2377 To see other ciphers that are available with OpenVPN, use the 2436 2378 --show-ciphers option. 2437 2379 2438 OpenVPN supports the CBC, CFB, and OFB cipher modes, however CBC 2439 is recommended and CFB and OFB should be considered advanced 2440 modes. 2380 OpenVPN supports the CBC, CFB, and OFB cipher modes, however CBC is 2381 recommended and CFB and OFB should be considered advanced modes. 2441 2382 2442 2383 Set alg=none to disable encryption. 2443 2384 2444 2385 --keysize n 2445 Size of cipher key in bits (optional). If unspecified, defaults 2446 to cipher-specific default. The --show-ciphers option (see2447 below) shows all available OpenSSL ciphers, their default key2448 sizes, and whether the key size can be changed. Use care in2449 c hanging a cipher's default key size. Many ciphers have not2450 been extensively cryptanalyzed with non-standard key lengths,2451 and a larger key may offer no real guarantee of greater secu‐2452 rity, or may even reducesecurity.2386 Size of cipher key in bits (optional). If unspecified, defaults to 2387 cipher-specific default. The --show-ciphers option (see below) 2388 shows all available OpenSSL ciphers, their default key sizes, and 2389 whether the key size can be changed. Use care in changing a 2390 cipher's default key size. Many ciphers have not been extensively 2391 cryptanalyzed with non-standard key lengths, and a larger key may 2392 offer no real guarantee of greater security, or may even reduce 2393 security. 2453 2394 2454 2395 --prng alg [nsl] 2455 (Advanced) For PRNG (Pseudo-random number generator), use digest 2456 algorithm alg (default=sha1), and set nsl (default=16) to the 2457 size in bytes of the nonce secret length (between 16 and 64). 2458 2459 Set alg=none to disable the PRNG and use the OpenSSL RAND_bytes 2460 function instead for all of OpenVPN's pseudo-random number 2461 needs. 2396 (Advanced) For PRNG (Pseudo-random number generator), use digest 2397 algorithm alg (default=sha1), and set nsl (default=16) to the size 2398 in bytes of the nonce secret length (between 16 and 64). 2399 2400 Set alg=none to disable the PRNG and use the OpenSSL RAND_bytes 2401 function instead for all of OpenVPN's pseudo-random number needs. 2462 2402 2463 2403 --engine [engine-name] 2464 2404 Enable OpenSSL hardware-based crypto engine functionality. 2465 2405 2466 If engine-name is specified, use a specific crypto engine. Use2467 the --show-engines standalone option to list the crypto engines2468 whichare supported by OpenSSL.2406 If engine-name is specified, use a specific crypto engine. Use the 2407 --show-engines standalone option to list the crypto engines which 2408 are supported by OpenSSL. 2469 2409 2470 2410 --no-replay 2471 (Advanced) Disable OpenVPN's protection against replayattacks.2472 Don't use this option unless you are prepared to make a tradeoff 2473 ofgreater efficiency in exchange for less security.2411 (Advanced) Disable OpenVPN's protection against replay attacks. 2412 Don't use this option unless you are prepared to make a tradeoff of 2413 greater efficiency in exchange for less security. 2474 2414 2475 2415 OpenVPN provides datagram replay protection by default. 2476 2416 2477 Replay protection is accomplished by tagging each outgoing data ‐2478 gram with an identifier that is guaranteed to be unique for the2479 key being used. The peer that receives the datagram will check2480 for the uniqueness of the identifier. If the identifier was2481 already received in a previous datagram, OpenVPN will drop the2482 packet. Replay protection is important to defeat attacks such2483 as a SYN flood attack, where the attacker listens in the wire,2484 intercepts a TCP SYN packet (identifying it by the contextin2485 which it occurs in relation to other packets), then floods the2486 receiving peer withcopies of this packet.2487 2488 OpenVPN's replay protectionis implemented in slightly different2417 Replay protection is accomplished by tagging each outgoing datagram 2418 with an identifier that is guaranteed to be unique for the key 2419 being used. The peer that receives the datagram will check for the 2420 uniqueness of the identifier. If the identifier was already 2421 received in a previous datagram, OpenVPN will drop the packet. 2422 Replay protection is important to defeat attacks such as a SYN 2423 flood attack, where the attacker listens in the wire, intercepts a 2424 TCP SYN packet (identifying it by the context in which it occurs in 2425 relation to other packets), then floods the receiving peer with 2426 copies of this packet. 2427 2428 OpenVPN's replay protection is implemented in slightly different 2489 2429 ways, depending on the key management mode you have selected. 2490 2430 2491 In Static Key mode or when using an CFB or OFB mode cipher,2492 OpenVPN uses a 64 bit unique identifier that combines a time2493 stamp with anincrementing sequence number.2494 2495 When using TLS mode for key exchange and a CBC cipher mode,2496 OpenVPN uses only a 32 bit sequence number without a time stamp,2497 since OpenVPN can guarantee the uniqueness of this value for2498 each key. As in IPSec, if the sequence number is close to wrap‐2499 ping back tozero, OpenVPN will trigger a new key exchange.2500 2501 To check for replays, OpenVPN uses the sliding windowalgorithm2431 In Static Key mode or when using an CFB or OFB mode cipher, OpenVPN 2432 uses a 64 bit unique identifier that combines a time stamp with an 2433 incrementing sequence number. 2434 2435 When using TLS mode for key exchange and a CBC cipher mode, OpenVPN 2436 uses only a 32 bit sequence number without a time stamp, since 2437 OpenVPN can guarantee the uniqueness of this value for each key. 2438 As in IPSec, if the sequence number is close to wrapping back to 2439 zero, OpenVPN will trigger a new key exchange. 2440 2441 To check for replays, OpenVPN uses the sliding window algorithm 2502 2442 used by IPSec. 2503 2443 2504 2444 --replay-window n [t] 2505 Use a replay protection sliding-window of size n and a time win‐2506 dowof t seconds.2445 Use a replay protection sliding-window of size n and a time window 2446 of t seconds. 2507 2447 2508 2448 By default n is 64 (the IPSec default) and t is 15 seconds. 2509 2449 2510 This option is only relevant in UDP mode, i.e. when either 2511 --proto udp is specifed, or no --proto option is specified. 2512 2513 When OpenVPN tunnels IP packets over UDP, there is the possibil‐ 2514 ity that packets might be dropped or delivered out of order. 2515 Because OpenVPN, like IPSec, is emulating the physical network 2516 layer, it will accept an out-of-order packet sequence, and will 2517 deliver such packets in the same order they were received to the 2518 TCP/IP protocol stack, provided they satisfy several con‐ 2519 straints. 2520 2521 (a) The packet cannot be a replay (unless --no-replay is speci‐ 2522 fied, which disables replay protection altogether). 2523 2524 (b) If a packet arrives out of order, it will only be accepted 2525 if the difference between its sequence number and the highest 2526 sequence number received so far is less than n. 2527 2528 (c) If a packet arrives out of order, it will only be accepted 2529 if it arrives no later than t seconds after any packet contain‐ 2530 ing a higher sequence number. 2531 2532 If you are using a network link with a large pipeline (meaning 2533 that the product of bandwidth and latency is high), you may want 2534 to use a larger value for n. Satellite links in particular 2535 often require this. 2536 2537 If you run OpenVPN at --verb 4, you will see the message 2538 "Replay-window backtrack occurred [x]" every time the maximum 2539 sequence number backtrack seen thus far increases. This can be 2540 used to calibrate n. 2541 2542 There is some controversy on the appropriate method of handling 2450 This option is only relevant in UDP mode, i.e. when either --proto 2451 udp is specifed, or no --proto option is specified. 2452 2453 When OpenVPN tunnels IP packets over UDP, there is the possibility 2454 that packets might be dropped or delivered out of order. Because 2455 OpenVPN, like IPSec, is emulating the physical network layer, it 2456 will accept an out-of-order packet sequence, and will deliver such 2457 packets in the same order they were received to the TCP/IP protocol 2458 stack, provided they satisfy several constraints. 2459 2460 (a) The packet cannot be a replay (unless --no-replay is specified, 2461 which disables replay protection altogether). 2462 2463 (b) If a packet arrives out of order, it will only be accepted if 2464 the difference between its sequence number and the highest sequence 2465 number received so far is less than n. 2466 2467 (c) If a packet arrives out of order, it will only be accepted if 2468 it arrives no later than t seconds after any packet containing a 2469 higher sequence number. 2470 2471 If you are using a network link with a large pipeline (meaning that 2472 the product of bandwidth and latency is high), you may want to use 2473 a larger value for n. Satellite links in particular often require 2474 this. 2475 2476 If you run OpenVPN at --verb 4, you will see the message "Replay- 2477 window backtrack occurred [x]" every time the maximum sequence num‐ 2478 ber backtrack seen thus far increases. This can be used to cali‐ 2479 brate n. 2480 2481 There is some controversy on the appropriate method of handling 2543 2482 packet reordering at the security layer. 2544 2483 2545 Namely, to what extent should the security layer protect the 2546 encapsulated protocol from attacks which masquerade as the kinds 2547 of normal packet loss and reordering that occur over IP net‐ 2548 works? 2549 2550 The IPSec and OpenVPN approach is to allow packet reordering 2551 within a certain fixed sequence number window. 2552 2553 OpenVPN adds to the IPSec model by limiting the window size in 2554 time as well as sequence space. 2555 2556 OpenVPN also adds TCP transport as an option (not offered by 2557 IPSec) in which case OpenVPN can adopt a very strict attitude 2558 towards message deletion and reordering: Don't allow it. Since 2559 TCP guarantees reliability, any packet loss or reordering event 2560 can be assumed to be an attack. 2561 2562 In this sense, it could be argued that TCP tunnel transport is 2563 preferred when tunneling non-IP or UDP application protocols 2564 which might be vulnerable to a message deletion or reordering 2565 attack which falls within the normal operational parameters of 2566 IP networks. 2567 2568 So I would make the statement that one should never tunnel a 2569 non-IP protocol or UDP application protocol over UDP, if the 2570 protocol might be vulnerable to a message deletion or reordering 2571 attack that falls within the normal operating parameters of what 2572 is to be expected from the physical IP layer. The problem is 2573 easily fixed by simply using TCP as the VPN transport layer. 2484 Namely, to what extent should the security layer protect the encap‐ 2485 sulated protocol from attacks which masquerade as the kinds of nor‐ 2486 mal packet loss and reordering that occur over IP networks? 2487 2488 The IPSec and OpenVPN approach is to allow packet reordering within 2489 a certain fixed sequence number window. 2490 2491 OpenVPN adds to the IPSec model by limiting the window size in time 2492 as well as sequence space. 2493 2494 OpenVPN also adds TCP transport as an option (not offered by IPSec) 2495 in which case OpenVPN can adopt a very strict attitude towards mes‐ 2496 sage deletion and reordering: Don't allow it. Since TCP guaran‐ 2497 tees reliability, any packet loss or reordering event can be 2498 assumed to be an attack. 2499 2500 In this sense, it could be argued that TCP tunnel transport is pre‐ 2501 ferred when tunneling non-IP or UDP application protocols which 2502 might be vulnerable to a message deletion or reordering attack 2503 which falls within the normal operational parameters of IP net‐ 2504 works. 2505 2506 So I would make the statement that one should never tunnel a non-IP 2507 protocol or UDP application protocol over UDP, if the protocol 2508 might be vulnerable to a message deletion or reordering attack that 2509 falls within the normal operating parameters of what is to be 2510 expected from the physical IP layer. The problem is easily fixed 2511 by simply using TCP as the VPN transport layer. 2574 2512 2575 2513 --mute-replay-warnings 2576 Silence the output of replay warnings, which are a commonfalse2577 alarm on WiFi networks. This option preserves the security of2578 the replay protection code without the verbosity associated with2579 warnings about duplicate packets.2514 Silence the output of replay warnings, which are a common false 2515 alarm on WiFi networks. This option preserves the security of the 2516 replay protection code without the verbosity associated with warn‐ 2517 ings about duplicate packets. 2580 2518 2581 2519 --replay-persist file 2582 Persist replay-protection state across sessions using file to2583 saveand reload the state.2584 2585 This option will strengthen protection against replayattacks,2586 especially when you are using OpenVPN in a dynamic context (such 2587 as with --inetd) when OpenVPN sessions are frequently started2588 andstopped.2589 2590 This option will keep a disk copy of the current replay protec‐2591 tion state (i.e. the most recent packet timestamp and sequence2592 number received from the remote peer), so that if an OpenVPN2593 s ession is stopped and restarted, it will reject any replays of2594 packets whichwere already received by the prior session.2595 2596 This option only makes sense when replay protection is enabled2597 (the default) and you are using either --secret (shared-secret2598 key mode)or TLS mode with --tls-auth.2520 Persist replay-protection state across sessions using file to save 2521 and reload the state. 2522 2523 This option will strengthen protection against replay attacks, 2524 especially when you are using OpenVPN in a dynamic context (such as 2525 with --inetd) when OpenVPN sessions are frequently started and 2526 stopped. 2527 2528 This option will keep a disk copy of the current replay protection 2529 state (i.e. the most recent packet timestamp and sequence number 2530 received from the remote peer), so that if an OpenVPN session is 2531 stopped and restarted, it will reject any replays of packets which 2532 were already received by the prior session. 2533 2534 This option only makes sense when replay protection is enabled (the 2535 default) and you are using either --secret (shared-secret key mode) 2536 or TLS mode with --tls-auth. 2599 2537 2600 2538 --no-iv 2601 (Advanced) Disable OpenVPN's use of IV (cipher initialization2602 vector). Don't use this option unless you are prepared to make2603 atradeoff of greater efficiency in exchange for less security.2604 2605 OpenVPN uses an IV by default, and requires it for CFB andOFB2606 cipher modes (which are totally insecure without it). Using an2607 IV is important for security when multiple messages arebeing2539 (Advanced) Disable OpenVPN's use of IV (cipher initialization vec‐ 2540 tor). Don't use this option unless you are prepared to make a 2541 tradeoff of greater efficiency in exchange for less security. 2542 2543 OpenVPN uses an IV by default, and requires it for CFB and OFB 2544 cipher modes (which are totally insecure without it). Using an IV 2545 is important for security when multiple messages are being 2608 2546 encrypted/decrypted with the same key. 2609 2547 … … 2612 2550 In CBC mode, OpenVPN uses a pseudo-random IV for each packet. 2613 2551 2614 In CFB/OFB mode, OpenVPN uses a unique sequence number andtime2615 stamp as the IV. In fact, in CFB/OFB mode, OpenVPN uses a data ‐2616 gram space-saving optimization that uses the unique identifier2617 for datagram replay protection as the IV.2552 In CFB/OFB mode, OpenVPN uses a unique sequence number and time 2553 stamp as the IV. In fact, in CFB/OFB mode, OpenVPN uses a datagram 2554 space-saving optimization that uses the unique identifier for data‐ 2555 gram replay protection as the IV. 2618 2556 2619 2557 --use-prediction-resistance 2620 2558 Enable prediction resistance on PolarSSL's RNG. 2621 2559 2622 Enabling prediction resistance causes the RNG to reseed ineach2623 call for random. Reseeding this often can quickly deplete the2624 kernel entropy pool.2625 2626 If you need this option, please consider running a daemon that2627 addsentropy to the kernel pool.2628 2629 Note that this option only works with PolarSSL versionsgreater2560 Enabling prediction resistance causes the RNG to reseed in each 2561 call for random. Reseeding this often can quickly deplete the ker‐ 2562 nel entropy pool. 2563 2564 If you need this option, please consider running a daemon that adds 2565 entropy to the kernel pool. 2566 2567 Note that this option only works with PolarSSL versions greater 2630 2568 than 1.1. 2631 2569 2632 2570 --test-crypto 2633 Do a self-test of OpenVPN's crypto options by encrypting and 2634 decrypting test packets using the data channel encryption 2635 options specified above. This option does not require a peer to 2636 function, and therefore can be specified without --dev or 2637 --remote. 2571 Do a self-test of OpenVPN's crypto options by encrypting and 2572 decrypting test packets using the data channel encryption options 2573 specified above. This option does not require a peer to function, 2574 and therefore can be specified without --dev or --remote. 2638 2575 2639 2576 The typical usage of --test-crypto would be something like this: … … 2645 2582 openvpn --test-crypto --secret key --verb 9 2646 2583 2647 This option is very useful to test OpenVPN after it has been2648 ported to a new platform, or to isolate problems in the com‐2649 piler, OpenSSL crypto library, or OpenVPN's crypto code. Since2650 it is a self-test mode, problems with encryption and authentica‐2651 tion can be debuggedindependently of network and tunnel issues.2584 This option is very useful to test OpenVPN after it has been ported 2585 to a new platform, or to isolate problems in the compiler, OpenSSL 2586 crypto library, or OpenVPN's crypto code. Since it is a self-test 2587 mode, problems with encryption and authentication can be debugged 2588 independently of network and tunnel issues. 2652 2589 2653 2590 TLS Mode Options: 2654 TLS mode is the most powerful crypto mode of OpenVPN in both security 2655 and flexibility. TLS mode works by establishing control and data chan‐ 2656 nels which are multiplexed over a single TCP/UDP port. OpenVPN initi‐ 2657 ates a TLS session over the control channel and uses it to exchange 2658 cipher and HMAC keys to protect the data channel. TLS mode uses a 2659 robust reliability layer over the UDP connection for all control chan‐ 2660 nel communication, while the data channel, over which encrypted tunnel 2661 data passes, is forwarded without any mediation. The result is the 2662 best of both worlds: a fast data channel that forwards over UDP with 2663 only the overhead of encrypt, decrypt, and HMAC functions, and a con‐ 2664 trol channel that provides all of the security features of TLS, includ‐ 2665 ing certificate-based authentication and Diffie Hellman forward 2666 secrecy. 2667 2668 To use TLS mode, each peer that runs OpenVPN should have its own local 2669 certificate/key pair ( --cert and --key ), signed by the root certifi‐ 2670 cate which is specified in --ca. 2671 2672 When two OpenVPN peers connect, each presents its local certificate to 2673 the other. Each peer will then check that its partner peer presented a 2674 certificate which was signed by the master root certificate as speci‐ 2675 fied in --ca. 2676 2677 If that check on both peers succeeds, then the TLS negotiation will 2678 succeed, both OpenVPN peers will exchange temporary session keys, and 2679 the tunnel will begin passing data. 2680 2681 The OpenVPN distribution contains a set of scripts for managing RSA 2682 certificates & keys, located in the easy-rsa subdirectory. 2683 2684 The easy-rsa package is also rendered in web form here: http://open‐ 2591 TLS mode is the most powerful crypto mode of OpenVPN in both security and 2592 flexibility. TLS mode works by establishing control and data channels 2593 which are multiplexed over a single TCP/UDP port. OpenVPN initiates a TLS 2594 session over the control channel and uses it to exchange cipher and HMAC 2595 keys to protect the data channel. TLS mode uses a robust reliability 2596 layer over the UDP connection for all control channel communication, while 2597 the data channel, over which encrypted tunnel data passes, is forwarded 2598 without any mediation. The result is the best of both worlds: a fast data 2599 channel that forwards over UDP with only the overhead of encrypt, decrypt, 2600 and HMAC functions, and a control channel that provides all of the secu‐ 2601 rity features of TLS, including certificate-based authentication and 2602 Diffie Hellman forward secrecy. 2603 2604 To use TLS mode, each peer that runs OpenVPN should have its own local 2605 certificate/key pair ( --cert and --key ), signed by the root certificate 2606 which is specified in --ca. 2607 2608 When two OpenVPN peers connect, each presents its local certificate to the 2609 other. Each peer will then check that its partner peer presented a cer‐ 2610 tificate which was signed by the master root certificate as specified in 2611 --ca. 2612 2613 If that check on both peers succeeds, then the TLS negotiation will suc‐ 2614 ceed, both OpenVPN peers will exchange temporary session keys, and the 2615 tunnel will begin passing data. 2616 2617 The OpenVPN distribution contains a set of scripts for managing RSA cer‐ 2618 tificates & keys, located in the easy-rsa subdirectory. 2619 2620 The easy-rsa package is also rendered in web form here: http://open‐ 2685 2621 vpn.net/easyrsa.html 2686 2622 2687 2623 --tls-server 2688 Enable TLS and assume server role during TLS handshake. Note2689 that OpenVPN is designed as a peer-to-peer application. The2690 designation of client or server is only for the purpose of nego‐2691 tiating the TLScontrol channel.2624 Enable TLS and assume server role during TLS handshake. Note that 2625 OpenVPN is designed as a peer-to-peer application. The designation 2626 of client or server is only for the purpose of negotiating the TLS 2627 control channel. 2692 2628 2693 2629 --tls-client … … 2695 2631 2696 2632 --ca file 2697 Certificate authority (CA) file in .pem format, also referred to 2698 as the root certificate. This file can have multiple certifi‐2699 cates in .pem format, concatenated together. You can construct2700 your own certificate authority certificate and private key by2701 using a command such as:2633 Certificate authority (CA) file in .pem format, also referred to as 2634 the root certificate. This file can have multiple certificates in 2635 .pem format, concatenated together. You can construct your own 2636 certificate authority certificate and private key by using a com‐ 2637 mand such as: 2702 2638 2703 2639 openssl req -nodes -new -x509 -keyout ca.key -out ca.crt 2704 2640 2705 Then edit your openssl.cnf file and edit the certificate vari‐2706 ableto point to your new root certificate ca.crt.2707 2708 For testing purposes only, the OpenVPN distribution includes a2709 sample CA certificate (ca.crt). Of course you should never use2710 t he test certificates and test keys distributed with OpenVPN in2711 a production environment, since by virtue of the fact that they2712 are distributed with OpenVPN, they are totally insecure.2641 Then edit your openssl.cnf file and edit the certificate variable 2642 to point to your new root certificate ca.crt. 2643 2644 For testing purposes only, the OpenVPN distribution includes a sam‐ 2645 ple CA certificate (ca.crt). Of course you should never use the 2646 test certificates and test keys distributed with OpenVPN in a pro‐ 2647 duction environment, since by virtue of the fact that they are dis‐ 2648 tributed with OpenVPN, they are totally insecure. 2713 2649 2714 2650 --capath dir 2715 Directory containing trusted certificates (CAs and CRLs).2716 Available with OpenSSL version >= 0.9.7 dev. Not availablewith2651 Directory containing trusted certificates (CAs and CRLs). Avail‐ 2652 able with OpenSSL version >= 0.9.7 dev. Not available with 2717 2653 PolarSSL. 2718 2654 2719 2655 --dh file 2720 File containing Diffie Hellman parameters in .pem format2721 (requiredfor --tls-server only). Use2656 File containing Diffie Hellman parameters in .pem format (required 2657 for --tls-server only). Use 2722 2658 2723 2659 openssl dhparam -out dh1024.pem 1024 2724 2660 2725 to generate your own, or use the existing dh1024.pem file2726 included with the OpenVPN distribution. Diffie Hellman parame‐2727 ters may beconsidered public.2661 to generate your own, or use the existing dh1024.pem file included 2662 with the OpenVPN distribution. Diffie Hellman parameters may be 2663 considered public. 2728 2664 2729 2665 --cert file 2730 Local peer's signed certificate in .pem format -- must be signed 2731 by a certificate authority whose certificate is in --ca file. 2732 Each peer in an OpenVPN link running in TLS mode should have its 2733 own certificate and private key file. In addition, each cer‐ 2734 tificate should have been signed by the key of a certificate 2735 authority whose public key resides in the --ca certificate 2736 authority file. You can easily make your own certificate 2737 authority (see above) or pay money to use a commercial service 2738 such as thawte.com (in which case you will be helping to finance 2739 the world's second space tourist :). To generate a certificate, 2740 you can use a command such as: 2666 Local peer's signed certificate in .pem format -- must be signed by 2667 a certificate authority whose certificate is in --ca file. Each 2668 peer in an OpenVPN link running in TLS mode should have its own 2669 certificate and private key file. In addition, each certificate 2670 should have been signed by the key of a certificate authority whose 2671 public key resides in the --ca certificate authority file. You can 2672 easily make your own certificate authority (see above) or pay money 2673 to use a commercial service such as thawte.com (in which case you 2674 will be helping to finance the world's second space tourist :). To 2675 generate a certificate, you can use a command such as: 2741 2676 2742 2677 openssl req -nodes -new -keyout mycert.key -out mycert.csr 2743 2678 2744 If your certificate authority private key lives on another 2745 machine, copy the certificate signing request (mycert.csr) to 2746 this other machine (this can be done over an insecure channel 2747 such as email). Now sign the certificate with a command such 2748 as: 2679 If your certificate authority private key lives on another machine, 2680 copy the certificate signing request (mycert.csr) to this other 2681 machine (this can be done over an insecure channel such as email). 2682 Now sign the certificate with a command such as: 2749 2683 2750 2684 openssl ca -out mycert.crt -in mycert.csr 2751 2685 2752 Now copy the certificate (mycert.crt) back to the peer which2753 initially generated the .csr file (this can be over a public2754 medium). Note that the openssl ca command reads the location of2755 the certificate authority key from its configuration file such2756 as /usr/share/ssl/openssl.cnf -- note also that forcertificate2757 authority functions, youmust set up the files index.txt (may be2686 Now copy the certificate (mycert.crt) back to the peer which ini‐ 2687 tially generated the .csr file (this can be over a public medium). 2688 Note that the openssl ca command reads the location of the certifi‐ 2689 cate authority key from its configuration file such as 2690 /usr/share/ssl/openssl.cnf -- note also that for certificate 2691 authority functions, you must set up the files index.txt (may be 2758 2692 empty) and serial (initialize to 01 ). 2759 2693 2760 2694 --extra-certs file 2761 Specify a file containing one or more PEM certs(concatenated2695 Specify a file containing one or more PEM certs (concatenated 2762 2696 together) that complete the local certificate chain. 2763 2697 2764 This option is useful for "split" CAs, where the CA for server 2765 certs is different than the CA for client certs. Putting certs 2766 in this file allows them to be used to complete the local cer‐ 2767 tificate chain without trusting them to verify the peer-submit‐ 2768 ted certificate, as would be the case if the certs were placed 2769 in the ca file. 2698 This option is useful for "split" CAs, where the CA for server 2699 certs is different than the CA for client certs. Putting certs in 2700 this file allows them to be used to complete the local certificate 2701 chain without trusting them to verify the peer-submitted certifi‐ 2702 cate, as would be the case if the certs were placed in the ca file. 2770 2703 2771 2704 --key file 2772 Local peer's private key in .pem format. Use the private key2773 w hich was generated when you built your peer's certificate (see2774 -certfile above).2705 Local peer's private key in .pem format. Use the private key which 2706 was generated when you built your peer's certificate (see -cert 2707 file above). 2775 2708 2776 2709 --pkcs12 file 2777 Specify a PKCS #12 file containing local private key, local cer‐ 2778 tificate, and root CA certificate. This option can be used 2779 instead of --ca, --cert, and --key. Not available with 2780 PolarSSL. 2710 Specify a PKCS #12 file containing local private key, local cer‐ 2711 tificate, and root CA certificate. This option can be used instead 2712 of --ca, --cert, and --key. Not available with PolarSSL. 2781 2713 2782 2714 --verify-hash hash 2783 Specify SHA1 fingerprint for level-1 cert. The level-1 cert is2784 the CA (or intermediate cert) that signs the leaf certificate,2785 and is one removed from the leaf certificate in the direction of2786 the root. When accepting a connection from a peer, the level-12787 cert fingerprint must match hash or certificate verification2788 will fail. Hash is specified as XX:XX:... Forexample:2715 Specify SHA1 fingerprint for level-1 cert. The level-1 cert is the 2716 CA (or intermediate cert) that signs the leaf certificate, and is 2717 one removed from the leaf certificate in the direction of the root. 2718 When accepting a connection from a peer, the level-1 cert finger‐ 2719 print must match hash or certificate verification will fail. Hash 2720 is specified as XX:XX:... For example: 2789 2721 AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16 2790 2722 2791 2723 --pkcs11-cert-private [0|1]... 2792 Set if access to certificate object should be performedafter2724 Set if access to certificate object should be performed after 2793 2725 login. Every provider has its own setting. 2794 2726 2795 2727 --pkcs11-id name 2796 Specify the serialized certificate id to be used. The id canbe2728 Specify the serialized certificate id to be used. The id can be 2797 2729 gotten by the standalone --show-pkcs11-ids option. 2798 2730 2799 2731 --pkcs11-id-management 2800 Acquire PKCS#11 id from management interface. In this case a2801 NEED-STR 'pkcs11-id-request' real-time message will be trig‐2802 gered, application may use pkcs11-id-count command to retrieve2803 available number of certificates, and pkcs11-id-get command to2804 retrieve certificateid and certificate body.2732 Acquire PKCS#11 id from management interface. In this case a NEED- 2733 STR 'pkcs11-id-request' real-time message will be triggered, appli‐ 2734 cation may use pkcs11-id-count command to retrieve available number 2735 of certificates, and pkcs11-id-get command to retrieve certificate 2736 id and certificate body. 2805 2737 2806 2738 --pkcs11-pin-cache seconds 2807 Specify how many seconds the PIN can be cached, the defaultis2739 Specify how many seconds the PIN can be cached, the default is 2808 2740 until the token is removed. 2809 2741 2810 2742 --pkcs11-protected-authentication [0|1]... 2811 Use PKCS#11 protected authentication path, useful for biometric 2812 and external keypad devices. Every provider has its own set‐ 2813 ting. 2743 Use PKCS#11 protected authentication path, useful for biometric and 2744 external keypad devices. Every provider has its own setting. 2814 2745 2815 2746 --pkcs11-providers provider... 2816 Specify a RSA Security Inc. PKCS #11 Cryptographic Token Inter ‐2817 face (Cryptoki) providers to load. This option can be used2818 instead of--cert, --key, and --pkcs12.2747 Specify a RSA Security Inc. PKCS #11 Cryptographic Token Interface 2748 (Cryptoki) providers to load. This option can be used instead of 2749 --cert, --key, and --pkcs12. 2819 2750 2820 2751 --pkcs11-private-mode mode... 2821 Specify which method to use in order to perform private key 2822 operations. A different mode can be specified for each 2823 provider. Mode is encoded as hex number, and can be a mask one 2824 of the following: 2752 Specify which method to use in order to perform private key opera‐ 2753 tions. A different mode can be specified for each provider. Mode 2754 is encoded as hex number, and can be a mask one of the following: 2825 2755 2826 2756 0 (default) -- Try to determind automatically. … … 2831 2761 2832 2762 --cryptoapicert select-string 2833 Load the certificate and private key from the Windows Certifi‐2834 cateSystem Store (Windows/OpenSSL Only).2763 Load the certificate and private key from the Windows Certificate 2764 System Store (Windows/OpenSSL Only). 2835 2765 2836 2766 Use this option instead of --cert and --key. 2837 2767 2838 This makes it possible to use any smart card, supported by Win‐2839 dows, but also any kind of certificate, residing in the Cert2840 Store, where you have access to the private key. This option2841 has been tested with a couple of different smart cards (GemSAFE,2842 Cryptoflex, and Swedish Post Office eID) on the client side, and2843 also an importedPKCS12 software certificate on the server side.2844 2845 To select acertificate, based on a substring search in the cer‐2768 This makes it possible to use any smart card, supported by Windows, 2769 but also any kind of certificate, residing in the Cert Store, where 2770 you have access to the private key. This option has been tested 2771 with a couple of different smart cards (GemSAFE, Cryptoflex, and 2772 Swedish Post Office eID) on the client side, and also an imported 2773 PKCS12 software certificate on the server side. 2774 2775 To select a certificate, based on a substring search in the cer‐ 2846 2776 tificate's subject: 2847 2777 … … 2852 2782 cryptoapicert "THUMB:f6 49 24 41 01 b4 ..." 2853 2783 2854 The thumbprint hex string can easily be copy-and-pasted fromthe2784 The thumbprint hex string can easily be copy-and-pasted from the 2855 2785 Windows Certificate Store GUI. 2856 2786 2857 2787 2858 2788 --key-method m 2859 Use data channel key negotiation method m. The key methodmust2789 Use data channel key negotiation method m. The key method must 2860 2790 match on both sides of the connection. 2861 2791 2862 After OpenVPN negotiates a TLS session, a new set of keys for2863 protecting the tunnel data channel is generated and exchanged2864 over theTLS session.2865 2866 In method 1 (the default for OpenVPN 1.x), both sides generate2867 random encrypt and HMAC-send keys which are forwarded to the2868 otherhost over the TLS channel.2869 2870 In method 2, (the default for OpenVPN 2.0) the client generates2871 a random key. Both client and server also generate some random2872 seed material. All key source material is exchanged over the2873 TLS channel. The actual keys are generated using the TLS PRF2874 function, taking source entropy from both client and server.2875 Method 2 is designed to closely parallel the key generation2876 process used by TLS1.0.2792 After OpenVPN negotiates a TLS session, a new set of keys for pro‐ 2793 tecting the tunnel data channel is generated and exchanged over the 2794 TLS session. 2795 2796 In method 1 (the default for OpenVPN 1.x), both sides generate ran‐ 2797 dom encrypt and HMAC-send keys which are forwarded to the other 2798 host over the TLS channel. 2799 2800 In method 2, (the default for OpenVPN 2.0) the client generates a 2801 random key. Both client and server also generate some random seed 2802 material. All key source material is exchanged over the TLS chan‐ 2803 nel. The actual keys are generated using the TLS PRF function, tak‐ 2804 ing source entropy from both client and server. Method 2 is 2805 designed to closely parallel the key generation process used by TLS 2806 1.0. 2877 2807 2878 2808 Note that in TLS mode, two separate levels of keying occur: 2879 2809 2880 (1) The TLS connection is initially negotiated, with both sides2881 of the connection producing certificates and verifying the cer‐2882 tificate (or other authentication info provided) of the other2883 side. The--key-method parameter has no effect on this process.2884 2885 (2) After the TLS connection is established, the tunnelsession2886 keys are separately negotiated over the existing secure TLS2887 channel. Here, --key-method determines the derivation of the2888 tunnelsession keys.2810 (1) The TLS connection is initially negotiated, with both sides of 2811 the connection producing certificates and verifying the certificate 2812 (or other authentication info provided) of the other side. The 2813 --key-method parameter has no effect on this process. 2814 2815 (2) After the TLS connection is established, the tunnel session 2816 keys are separately negotiated over the existing secure TLS chan‐ 2817 nel. Here, --key-method determines the derivation of the tunnel 2818 session keys. 2889 2819 2890 2820 --tls-cipher l 2891 A list l of allowable TLS ciphers delimited by a colon (":").2892 If you require a high level of security, you may want to set2893 this parameter manually, to prevent a version rollback attack2894 where a man-in-the-middle attacker tries to force two peersto2895 negotiate to the lowest level of security they both support.2896 Use --show-tls tosee a list of supported TLS ciphers.2821 A list l of allowable TLS ciphers delimited by a colon (":"). If 2822 you require a high level of security, you may want to set this 2823 parameter manually, to prevent a version rollback attack where a 2824 man-in-the-middle attacker tries to force two peers to negotiate to 2825 the lowest level of security they both support. Use --show-tls to 2826 see a list of supported TLS ciphers. 2897 2827 2898 2828 --tls-timeout n 2899 Packet retransmit timeout on TLS control channel if no acknowl‐2900 edgment from remote within n seconds (default=2). When OpenVPN2901 sends a control packet to its peer, it will expect to receive an2902 acknowledgement within n seconds or it will retransmit the2903 packet, subject to a TCP-like exponential backoff algorithm.2904 This parameter only applies to control channel packets. Data2905 c hannel packets (which carry encrypted tunnel data) are never2906 acknowledged, sequenced, or retransmitted by OpenVPN because the2907 higher level network protocols running on top of the tunnel such2908 as TCP expect this role to beleft to them.2829 Packet retransmit timeout on TLS control channel if no acknowledg‐ 2830 ment from remote within n seconds (default=2). When OpenVPN sends 2831 a control packet to its peer, it will expect to receive an acknowl‐ 2832 edgement within n seconds or it will retransmit the packet, subject 2833 to a TCP-like exponential backoff algorithm. This parameter only 2834 applies to control channel packets. Data channel packets (which 2835 carry encrypted tunnel data) are never acknowledged, sequenced, or 2836 retransmitted by OpenVPN because the higher level network protocols 2837 running on top of the tunnel such as TCP expect this role to be 2838 left to them. 2909 2839 2910 2840 --reneg-bytes n 2911 Renegotiate data channel key after n bytes sent or received2912 (disabled by default). OpenVPN allows the lifetime of a key to2913 be expressed as a number of bytes encrypted/decrypted, a number2914 of packets, or a number of seconds.A key renegotiation will be2841 Renegotiate data channel key after n bytes sent or received (dis‐ 2842 abled by default). OpenVPN allows the lifetime of a key to be 2843 expressed as a number of bytes encrypted/decrypted, a number of 2844 packets, or a number of seconds. A key renegotiation will be 2915 2845 forced if any of these three criteria are met by either peer. 2916 2846 2917 2847 --reneg-pkts n 2918 Renegotiate data channel key after n packets sent andreceived2848 Renegotiate data channel key after n packets sent and received 2919 2849 (disabled by default). 2920 2850 … … 2922 2852 Renegotiate data channel key after n seconds (default=3600). 2923 2853 2924 When using dual-factor authentication, note that this default 2925 value may cause the end user to be challenged to reauthorize 2926 once per hour. 2927 2928 Also, keep in mind that this option can be used on both the 2929 client and server, and whichever uses the lower value will be 2930 the one to trigger the renegotiation. A common mistake is to 2931 set --reneg-sec to a higher value on either the client or 2932 server, while the other side of the connection is still using 2933 the default value of 3600 seconds, meaning that the renegotia‐ 2934 tion will still occur once per 3600 seconds. The solution is to 2935 increase --reneg-sec on both the client and server, or set it to 2936 0 on one side of the connection (to disable), and to your chosen 2937 value on the other side. 2854 When using dual-factor authentication, note that this default value 2855 may cause the end user to be challenged to reauthorize once per 2856 hour. 2857 2858 Also, keep in mind that this option can be used on both the client 2859 and server, and whichever uses the lower value will be the one to 2860 trigger the renegotiation. A common mistake is to set --reneg-sec 2861 to a higher value on either the client or server, while the other 2862 side of the connection is still using the default value of 3600 2863 seconds, meaning that the renegotiation will still occur once per 2864 3600 seconds. The solution is to increase --reneg-sec on both the 2865 client and server, or set it to 0 on one side of the connection (to 2866 disable), and to your chosen value on the other side. 2938 2867 2939 2868 --hand-window n 2940 Handshake Window -- the TLS-based key exchange must finalize 2941 within n seconds of handshake initiation by any peer (default = 2942 60 seconds). If the handshake fails we will attempt to reset 2943 our connection with our peer and try again. Even in the event 2944 of handshake failure we will still use our expiring key for up 2945 to --tran-window seconds to maintain continuity of transmission 2946 of tunnel data. 2869 Handshake Window -- the TLS-based key exchange must finalize within 2870 n seconds of handshake initiation by any peer (default = 60 sec‐ 2871 onds). If the handshake fails we will attempt to reset our connec‐ 2872 tion with our peer and try again. Even in the event of handshake 2873 failure we will still use our expiring key for up to --tran-window 2874 seconds to maintain continuity of transmission of tunnel data. 2947 2875 2948 2876 --tran-window n 2949 Transition window -- our old key can live this many seconds2950 after a new a key renegotiation begins (default = 3600 seconds).2951 This feature allows for a graceful transition from old to new2952 key, and removes the key renegotiation sequence from the criti‐2953 cal path oftunnel data forwarding.2877 Transition window -- our old key can live this many seconds after a 2878 new a key renegotiation begins (default = 3600 seconds). This fea‐ 2879 ture allows for a graceful transition from old to new key, and 2880 removes the key renegotiation sequence from the critical path of 2881 tunnel data forwarding. 2954 2882 2955 2883 --single-session 2956 After initially connecting to a remote peer, disallow any new2957 connections. Using this option means that a remote peer cannot2958 connect, disconnect, and then reconnect.2959 2960 If the daemon is reset by a signal or --ping-restart, it will2961 allowone new connection.2962 2963 --single-session can be used with --ping-exit or --inactive to2964 create a single dynamic session that will exit when finished.2884 After initially connecting to a remote peer, disallow any new con‐ 2885 nections. Using this option means that a remote peer cannot con‐ 2886 nect, disconnect, and then reconnect. 2887 2888 If the daemon is reset by a signal or --ping-restart, it will allow 2889 one new connection. 2890 2891 --single-session can be used with --ping-exit or --inactive to cre‐ 2892 ate a single dynamic session that will exit when finished. 2965 2893 2966 2894 --tls-exit … … 2968 2896 2969 2897 --tls-auth file [direction] 2970 Add an additional layer of HMAC authentication on top of theTLS2898 Add an additional layer of HMAC authentication on top of the TLS 2971 2899 control channel to protect against DoS attacks. 2972 2900 2973 In a nutshell, --tls-auth enables a kind of "HMAC firewall" on 2974 OpenVPN's TCP/UDP port, where TLS control channel packets bear‐ 2975 ing an incorrect HMAC signature can be dropped immediately with‐ 2976 out response. 2977 2978 file (required) is a key file which can be in one of two for‐ 2979 mats: 2980 2981 (1) An OpenVPN static key file generated by --genkey (required 2982 if direction parameter is used). 2983 2984 (2) A freeform passphrase file. In this case the HMAC key will 2985 be derived by taking a secure hash of this file, similar to the 2901 In a nutshell, --tls-auth enables a kind of "HMAC firewall" on 2902 OpenVPN's TCP/UDP port, where TLS control channel packets bearing 2903 an incorrect HMAC signature can be dropped immediately without 2904 response. 2905 2906 file (required) is a key file which can be in one of two formats: 2907 2908 (1) An OpenVPN static key file generated by --genkey (required if 2909 direction parameter is used). 2910 2911 (2) A freeform passphrase file. In this case the HMAC key will be 2912 derived by taking a secure hash of this file, similar to the 2986 2913 md5sum(1) or sha1sum(1) commands. 2987 2914 2988 OpenVPN will first try format (1), and if the file fails to 2989 parse as a static key file, format (2) will be used. 2990 2991 See the --secret option for more information on the optional 2992 direction parameter. 2993 2994 --tls-auth is recommended when you are running OpenVPN in a mode 2995 where it is listening for packets from any IP address, such as 2996 when --remote is not specified, or --remote is specified with 2997 --float. 2998 2999 The rationale for this feature is as follows. TLS requires a 3000 multi-packet exchange before it is able to authenticate a peer. 3001 During this time before authentication, OpenVPN is allocating 3002 resources (memory and CPU) to this potential peer. The poten‐ 3003 tial peer is also exposing many parts of OpenVPN and the OpenSSL 3004 library to the packets it is sending. Most successful network 3005 attacks today seek to either exploit bugs in programs (such as 3006 buffer overflow attacks) or force a program to consume so many 3007 resources that it becomes unusable. Of course the first line of 3008 defense is always to produce clean, well-audited code. OpenVPN 3009 has been written with buffer overflow attack prevention as a top 3010 priority. But as history has shown, many of the most widely 3011 used network applications have, from time to time, fallen to 3012 buffer overflow attacks. 3013 3014 So as a second line of defense, OpenVPN offers this special 3015 layer of authentication on top of the TLS control channel so 3016 that every packet on the control channel is authenticated by an 3017 HMAC signature and a unique ID for replay protection. This sig‐ 3018 nature will also help protect against DoS (Denial of Service) 3019 attacks. An important rule of thumb in reducing vulnerability 3020 to DoS attacks is to minimize the amount of resources a poten‐ 3021 tial, but as yet unauthenticated, client is able to consume. 3022 3023 --tls-auth does this by signing every TLS control channel packet 3024 with an HMAC signature, including packets which are sent before 3025 the TLS level has had a chance to authenticate the peer. The 3026 result is that packets without the correct signature can be 3027 dropped immediately upon reception, before they have a chance to 3028 consume additional system resources such as by initiating a TLS 3029 handshake. --tls-auth can be strengthened by adding the 3030 --replay-persist option which will keep OpenVPN's replay protec‐ 3031 tion state in a file so that it is not lost across restarts. 3032 3033 It should be emphasized that this feature is optional and that 3034 the passphrase/key file used with --tls-auth gives a peer noth‐ 3035 ing more than the power to initiate a TLS handshake. It is not 3036 used to encrypt or authenticate any tunnel data. 2915 OpenVPN will first try format (1), and if the file fails to parse 2916 as a static key file, format (2) will be used. 2917 2918 See the --secret option for more information on the optional direc‐ 2919 tion parameter. 2920 2921 --tls-auth is recommended when you are running OpenVPN in a mode 2922 where it is listening for packets from any IP address, such as when 2923 --remote is not specified, or --remote is specified with --float. 2924 2925 The rationale for this feature is as follows. TLS requires a 2926 multi-packet exchange before it is able to authenticate a peer. 2927 During this time before authentication, OpenVPN is allocating 2928 resources (memory and CPU) to this potential peer. The potential 2929 peer is also exposing many parts of OpenVPN and the OpenSSL library 2930 to the packets it is sending. Most successful network attacks 2931 today seek to either exploit bugs in programs (such as buffer over‐ 2932 flow attacks) or force a program to consume so many resources that 2933 it becomes unusable. Of course the first line of defense is always 2934 to produce clean, well-audited code. OpenVPN has been written with 2935 buffer overflow attack prevention as a top priority. But as his‐ 2936 tory has shown, many of the most widely used network applications 2937 have, from time to time, fallen to buffer overflow attacks. 2938 2939 So as a second line of defense, OpenVPN offers this special layer 2940 of authentication on top of the TLS control channel so that every 2941 packet on the control channel is authenticated by an HMAC signature 2942 and a unique ID for replay protection. This signature will also 2943 help protect against DoS (Denial of Service) attacks. An important 2944 rule of thumb in reducing vulnerability to DoS attacks is to mini‐ 2945 mize the amount of resources a potential, but as yet unauthenti‐ 2946 cated, client is able to consume. 2947 2948 --tls-auth does this by signing every TLS control channel packet 2949 with an HMAC signature, including packets which are sent before the 2950 TLS level has had a chance to authenticate the peer. The result is 2951 that packets without the correct signature can be dropped immedi‐ 2952 ately upon reception, before they have a chance to consume addi‐ 2953 tional system resources such as by initiating a TLS handshake. 2954 --tls-auth can be strengthened by adding the --replay-persist 2955 option which will keep OpenVPN's replay protection state in a file 2956 so that it is not lost across restarts. 2957 2958 It should be emphasized that this feature is optional and that the 2959 passphrase/key file used with --tls-auth gives a peer nothing more 2960 than the power to initiate a TLS handshake. It is not used to 2961 encrypt or authenticate any tunnel data. 3037 2962 3038 2963 --askpass [file] 3039 Get certificate password from console or file before we daemo‐ 3040 nize. 3041 3042 For the extremely security conscious, it is possible to protect 3043 your private key with a password. Of course this means that 3044 every time the OpenVPN daemon is started you must be there to 3045 type the password. The --askpass option allows you to start 3046 OpenVPN from the command line. It will query you for a password 3047 before it daemonizes. To protect a private key with a password 3048 you should omit the -nodes option when you use the openssl com‐ 3049 mand line tool to manage certificates and private keys. 3050 3051 If file is specified, read the password from the first line of 3052 file. Keep in mind that storing your password in a file to a 3053 certain extent invalidates the extra security provided by using 3054 an encrypted key (Note: OpenVPN will only read passwords from a 3055 file if it has been built with the --enable-password-save con‐ 3056 figure option, or on Windows by defining ENABLE_PASSWORD_SAVE in 3057 win/settings.in). 2964 Get certificate password from console or file before we daemonize. 2965 2966 For the extremely security conscious, it is possible to protect 2967 your private key with a password. Of course this means that every 2968 time the OpenVPN daemon is started you must be there to type the 2969 password. The --askpass option allows you to start OpenVPN from 2970 the command line. It will query you for a password before it dae‐ 2971 monizes. To protect a private key with a password you should omit 2972 the -nodes option when you use the openssl command line tool to 2973 manage certificates and private keys. 2974 2975 If file is specified, read the password from the first line of 2976 file. Keep in mind that storing your password in a file to a cer‐ 2977 tain extent invalidates the extra security provided by using an 2978 encrypted key (Note: OpenVPN will only read passwords from a file 2979 if it has been built with the --enable-password-save configure 2980 option, or on Windows by defining ENABLE_PASSWORD_SAVE in win/set‐ 2981 tings.in). 3058 2982 3059 2983 --auth-nocache 3060 Don't cache --askpass or --auth-user-pass username/passwordsin2984 Don't cache --askpass or --auth-user-pass username/passwords in 3061 2985 virtual memory. 3062 2986 3063 If specified, this directive will cause OpenVPN to immediately3064 forget username/password inputs after they are used. As a3065 result, when OpenVPN needs a username/password, it will prompt3066 f or input from stdin, which may be multiple times during the3067 duration of anOpenVPN session.3068 3069 This directive does not affect the --http-proxy username/pass‐3070 word.It is always cached.2987 If specified, this directive will cause OpenVPN to immediately for‐ 2988 get username/password inputs after they are used. As a result, 2989 when OpenVPN needs a username/password, it will prompt for input 2990 from stdin, which may be multiple times during the duration of an 2991 OpenVPN session. 2992 2993 This directive does not affect the --http-proxy username/password. 2994 It is always cached. 3071 2995 3072 2996 --tls-verify cmd 3073 Run command cmd to verify the X509 name of a pending TLS connec ‐3074 t ion that has otherwise passed all other tests of certification3075 (except for revocation via --crl-verify directive; the revoca‐3076 tion testoccurs after the --tls-verify test).3077 3078 cmd should return 0 to allow the TLS handshake to proceed, or 13079 tofail.3080 3081 cmd consists of a path to script (or executable program),3082 optionally followed by arguments. The path and arguments may be3083 single- or double-quoted and/or escaped using a backslash, and3084 s hould be separated by one or more spaces.3085 3086 When cmd is executed two arguments are appended after any argu‐3087 mentsspecified in cmd , as follows:2997 Run command cmd to verify the X509 name of a pending TLS connection 2998 that has otherwise passed all other tests of certification (except 2999 for revocation via --crl-verify directive; the revocation test 3000 occurs after the --tls-verify test). 3001 3002 cmd should return 0 to allow the TLS handshake to proceed, or 1 to 3003 fail. 3004 3005 cmd consists of a path to script (or executable program), option‐ 3006 ally followed by arguments. The path and arguments may be single- 3007 or double-quoted and/or escaped using a backslash, and should be 3008 separated by one or more spaces. 3009 3010 When cmd is executed two arguments are appended after any arguments 3011 specified in cmd , as follows: 3088 3012 3089 3013 cmd certificate_depth subject 3090 3014 3091 These arguments are, respectively, the current certificatedepth3015 These arguments are, respectively, the current certificate depth 3092 3016 and the X509 common name (cn) of the peer. 3093 3017 3094 This feature is useful if the peer you want to trust has a cer‐3095 tificate which was signed by a certificate authority who also3096 signed many other certificates, where you don't necessarily want3097 to trust all of them, but rather be selective about which peer3098 certificate you will accept. This feature allows you to write a3099 script which will test the X509 name on a certificate and decide3100 whether or not it should be accepted. For a simple perl script3101 which will test the common name field on the certificate, see3102 the file verify-cn in theOpenVPN distribution.3103 3104 See the "Environmental Variables" section below foradditional3018 This feature is useful if the peer you want to trust has a certifi‐ 3019 cate which was signed by a certificate authority who also signed 3020 many other certificates, where you don't necessarily want to trust 3021 all of them, but rather be selective about which peer certificate 3022 you will accept. This feature allows you to write a script which 3023 will test the X509 name on a certificate and decide whether or not 3024 it should be accepted. For a simple perl script which will test 3025 the common name field on the certificate, see the file verify-cn in 3026 the OpenVPN distribution. 3027 3028 See the "Environmental Variables" section below for additional 3105 3029 parameters passed as environmental variables. 3106 3030 3107 3031 --tls-export-cert directory 3108 Store the certificates the clients uses upon connection tothis3109 directory. This willbe done before --tls-verify is called. The3110 certificates will use a temporary name and will be deleted when3111 t he tls-verify script returns. The file name used for the cer‐3112 tificateis available via the peer_cert environment variable.3032 Store the certificates the clients uses upon connection to this 3033 directory. This will be done before --tls-verify is called. The 3034 certificates will use a temporary name and will be deleted when the 3035 tls-verify script returns. The file name used for the certificate 3036 is available via the peer_cert environment variable. 3113 3037 3114 3038 --x509-username-field fieldname 3115 Field in x509 certificate subject to be used asusername3116 (default=CN). Fieldname will be uppercased before matching.3117 When this option is used, the --tls-remote option willmatch3039 Field in x509 certificate subject to be used as username 3040 (default=CN). Fieldname will be uppercased before matching. When 3041 this option is used, the --verify-x509-username option will match 3118 3042 against the chosen fieldname instead of the CN. 3119 3043 3120 --tls-remote name 3121 Accept connections only from a host with X509 name or common 3122 name equal to name. The remote host must also pass all other 3123 tests of verification. 3124 3125 NOTE: Because tls-remote may test against a common name prefix, 3126 only use this option when you are using OpenVPN with a custom CA 3127 certificate that is under your control. Never use this option 3128 when your client certificates are signed by a third party, such 3129 as a commercial web CA. 3130 3131 Name can also be a common name prefix, for example if you want a 3132 client to only accept connections to "Server-1", "Server-2", 3133 etc., you can simply use --tls-remote Server 3134 3135 Using a common name prefix is a useful alternative to managing a 3136 CRL (Certificate Revocation List) on the client, since it allows 3137 the client to refuse all certificates except for those associ‐ 3138 ated with designated servers. 3139 3140 --tls-remote is a useful replacement for the --tls-verify option 3141 to verify the remote host, because --tls-remote works in a 3142 --chroot environment too. 3044 --tls-remote name (DEPRECATED) 3045 Accept connections only from a host with X509 name or common name 3046 equal to name. The remote host must also pass all other tests of 3047 verification. 3048 3049 NOTE: Because tls-remote may test against a common name prefix, 3050 only use this option when you are using OpenVPN with a custom CA 3051 certificate that is under your control. Never use this option when 3052 your client certificates are signed by a third party, such as a 3053 commercial web CA. 3054 3055 Name can also be a common name prefix, for example if you want a 3056 client to only accept connections to "Server-1", "Server-2", etc., 3057 you can simply use --tls-remote Server 3058 3059 Using a common name prefix is a useful alternative to managing a 3060 CRL (Certificate Revocation List) on the client, since it allows 3061 the client to refuse all certificates except for those associated 3062 with designated servers. 3063 3064 --tls-remote is a useful replacement for the --tls-verify option to 3065 verify the remote host, because --tls-remote works in a --chroot 3066 environment too. 3067 3068 Please also note: This option is now deprecated. It will be 3069 removed either in OpenVPN v2.4 or v2.5. So please make sure you 3070 support the new X.509 name formatting described with the --compat- 3071 names option as soon as possible by updating your configurations to 3072 use --verify-x509-name instead. 3073 3074 --verify-x509-name name type 3075 Accept connections only if a host's X.509 name is equal to name. 3076 The remote host must also pass all other tests of verification. 3077 3078 Which X.509 name is compared to name depends on the setting of 3079 type. type can be "subject" to match the complete subject DN 3080 (default), "name" to match a subject RDN or "name-prefix" to match 3081 a subject RDN prefix. Which RDN is verified as name depends on the 3082 --x509-username-field option. But it defaults to the common name 3083 (CN), e.g. a certificate with a subject DN "C=KG, ST=NA, L=Bishkek, 3084 CN=Server-1" would be matched by: 3085 3086 --verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1' and --ver‐ 3087 ify-x509-name Server-1 name or you could use --verify-x509-name 3088 Server- name-prefix if you want a client to only accept connections 3089 to "Server-1", "Server-2", etc. 3090 3091 --verify-x509-name is a useful replacement for the --tls-verify 3092 option to verify the remote host, because --verify-x509-name works 3093 in a --chroot environment without any dependencies. 3094 3095 Using a name prefix is a useful alternative to managing a CRL (Cer‐ 3096 tificate Revocation List) on the client, since it allows the client 3097 to refuse all certificates except for those associated with desig‐ 3098 nated servers. 3099 3100 NOTE: Test against a name prefix only when you are using OpenVPN 3101 with a custom CA certificate that is under your control. Never use 3102 this option with type "name-prefix" when your client certificates 3103 are signed by a third party, such as a commercial web CA. 3143 3104 3144 3105 --x509-track attribute 3145 Save peer X509 attribute value in environment for use byplugins3146 and management interface. Prepend a '+' to attribute to save3147 values from full cert chain. Values will be encodedas3148 X509_<depth>_<attribute>=<value>. Multiple --x509-trackoptions3149 can be defined to track multiple attributes. Not availablewith3106 Save peer X509 attribute value in environment for use by plugins 3107 and management interface. Prepend a '+' to attribute to save val‐ 3108 ues from full cert chain. Values will be encoded as 3109 X509_<depth>_<attribute>=<value>. Multiple --x509-track options 3110 can be defined to track multiple attributes. Not available with 3150 3111 PolarSSL. 3151 3112 3152 3113 --ns-cert-type client|server 3153 Require that peer certificate was signed with an explicit3154 nsCertType designation of "client" or "server".3155 3156 This is a useful security option for clients, to ensure thatthe3114 Require that peer certificate was signed with an explicit nsCert‐ 3115 Type designation of "client" or "server". 3116 3117 This is a useful security option for clients, to ensure that the 3157 3118 host they connect with is a designated server. 3158 3119 3159 See the easy-rsa/build-key-server script for an example of how 3160 to generate a certificate with the nsCertType field set to 3161 "server". 3162 3163 If the server certificate's nsCertType field is set to "server", 3120 See the easy-rsa/build-key-server script for an example of how to 3121 generate a certificate with the nsCertType field set to "server". 3122 3123 If the server certificate's nsCertType field is set to "server", 3164 3124 then the clients can verify this with --ns-cert-type server. 3165 3125 3166 This is an important security precaution to protect against a 3167 man-in-the-middle attack where an authorized client attempts to 3168 connect to another client by impersonating the server. The 3169 attack is easily prevented by having clients verify the server 3170 certificate using any one of --ns-cert-type, --tls-remote, or 3171 --tls-verify. 3126 This is an important security precaution to protect against a man- 3127 in-the-middle attack where an authorized client attempts to connect 3128 to another client by impersonating the server. The attack is eas‐ 3129 ily prevented by having clients verify the server certificate using 3130 any one of --ns-cert-type, --verify-x509-name, or --tls-verify. 3172 3131 3173 3132 --remote-cert-ku v... 3174 Require that peer certificate was signed with an explicitkey3133 Require that peer certificate was signed with an explicit key 3175 3134 usage. 3176 3135 3177 This is a useful security option for clients, to ensure thatthe3136 This is a useful security option for clients, to ensure that the 3178 3137 host they connect to is a designated server. 3179 3138 3180 The key usage should be encoded in hex, more than one key usage3181 canbe specified.3139 The key usage should be encoded in hex, more than one key usage can 3140 be specified. 3182 3141 3183 3142 --remote-cert-eku oid 3184 Require that peer certificate was signed with an explicit3185 extendedkey usage.3186 3187 This is auseful security option for clients, to ensure that the3143 Require that peer certificate was signed with an explicit extended 3144 key usage. 3145 3146 This is a useful security option for clients, to ensure that the 3188 3147 host they connect to is a designated server. 3189 3148 3190 The extended key usage should be encoded in oid notation,or3149 The extended key usage should be encoded in oid notation, or 3191 3150 OpenSSL symbolic representation. 3192 3151 3193 3152 --remote-cert-tls client|server 3194 Require that peer certificate was signed with an explicit key3195 usageand extended key usage based on RFC3280 TLS rules.3196 3197 This is a useful security option for clients, to ensure thatthe3153 Require that peer certificate was signed with an explicit key usage 3154 and extended key usage based on RFC3280 TLS rules. 3155 3156 This is a useful security option for clients, to ensure that the 3198 3157 host they connect to is a designated server. 3199 3158 3200 The --remote-cert-tls client option is equivalent to --remote- 3201 cert-ku 80 08 88 --remote-cert-eku "TLS Web Client Authentica‐ 3202 tion" 3159 The --remote-cert-tls client option is equivalent to --remote-cert- 3160 ku 80 08 88 --remote-cert-eku "TLS Web Client Authentication" 3203 3161 3204 3162 The key usage is digitalSignature and/or keyAgreement. 3205 3163 3206 The --remote-cert-tls server option is equivalent to --remote-3207 cert-ku a0 88 --remote-cert-eku "TLS Web Server Authentication"3208 3209 The key usageis digitalSignature and ( keyEncipherment or keyA‐3164 The --remote-cert-tls server option is equivalent to --remote-cert- 3165 ku a0 88 --remote-cert-eku "TLS Web Server Authentication" 3166 3167 The key usage is digitalSignature and ( keyEncipherment or keyA‐ 3210 3168 greement ). 3211 3169 3212 This is an important security precaution to protect against a 3213 man-in-the-middle attack where an authorized client attempts to 3214 connect to another client by impersonating the server. The 3215 attack is easily prevented by having clients verify the server 3216 certificate using any one of --remote-cert-tls, --tls-remote, or 3217 --tls-verify. 3170 This is an important security precaution to protect against a man- 3171 in-the-middle attack where an authorized client attempts to connect 3172 to another client by impersonating the server. The attack is eas‐ 3173 ily prevented by having clients verify the server certificate using 3174 any one of --remote-cert-tls, --verify-x509-name, or --tls-verify. 3218 3175 3219 3176 --crl-verify crl ['dir'] 3220 3177 Check peer certificate against the file crl in PEM format. 3221 3178 3222 A CRL (certificate revocation list) is used when a particular3223 keyis compromised but when the overall PKI is still intact.3224 3225 Suppose you had a PKI consisting of a CA, root certificate, and3226 a number of client certificates. Suppose a laptop computer con‐3227 taining a client key and certificate was stolen. By adding the3228 stolen certificate to the CRL file, you could reject any connec‐3229 tion which attempts to use it, while preserving the overall3230 integrity of thePKI.3231 3232 The only time when it would be necessary to rebuild the entire3233 PKI from scratch would be if the root certificate key itself was3234 compromised.3235 3236 If the optional dir flag is specified, enable a differentmode3237 where crl is a directory containing files named as revoked3238 serial numbers (the files may be empty, the contents are never3239 read). If a client requests a connection, where the client cer‐3240 tificate serial number (decimal string) is the name of a file3241 present in the directory, it will be rejected.3179 A CRL (certificate revocation list) is used when a particular key 3180 is compromised but when the overall PKI is still intact. 3181 3182 Suppose you had a PKI consisting of a CA, root certificate, and a 3183 number of client certificates. Suppose a laptop computer contain‐ 3184 ing a client key and certificate was stolen. By adding the stolen 3185 certificate to the CRL file, you could reject any connection which 3186 attempts to use it, while preserving the overall integrity of the 3187 PKI. 3188 3189 The only time when it would be necessary to rebuild the entire PKI 3190 from scratch would be if the root certificate key itself was com‐ 3191 promised. 3192 3193 If the optional dir flag is specified, enable a different mode 3194 where crl is a directory containing files named as revoked serial 3195 numbers (the files may be empty, the contents are never read). If 3196 a client requests a connection, where the client certificate serial 3197 number (decimal string) is the name of a file present in the direc‐ 3198 tory, it will be rejected. 3242 3199 3243 3200 SSL Library information: 3244 3201 --show-ciphers 3245 (Standalone) Show allcipher algorithms to use with the --cipher3202 (Standalone) Show all cipher algorithms to use with the --cipher 3246 3203 option. 3247 3204 3248 3205 --show-digests 3249 (Standalone) Show all message digest algorithms to use withthe3206 (Standalone) Show all message digest algorithms to use with the 3250 3207 --auth option. 3251 3208 3252 3209 --show-tls 3253 (Standalone) Show all TLS ciphers (TLS used only as a control3254 channel). The TLS ciphers will be sorted from highest prefer‐3255 ence (mostsecure) to lowest.3210 (Standalone) Show all TLS ciphers (TLS used only as a control chan‐ 3211 nel). The TLS ciphers will be sorted from highest preference (most 3212 secure) to lowest. 3256 3213 3257 3214 --show-engines 3258 (Standalone) Show currently available hardware-based crypto3259 acceleration engines supported by the OpenSSL library.3215 (Standalone) Show currently available hardware-based crypto accel‐ 3216 eration engines supported by the OpenSSL library. 3260 3217 3261 3218 Generate a random key: … … 3263 3220 3264 3221 --genkey 3265 (Standalone) Generate a random key to be used as a shared 3266 secret, for use with the --secret option. This file must be 3267 shared with the peer over a pre-existing secure channel such as 3268 scp(1) 3222 (Standalone) Generate a random key to be used as a shared secret, 3223 for use with the --secret option. This file must be shared with 3224 the peer over a pre-existing secure channel such as scp(1) 3269 3225 3270 3226 --secret file … … 3272 3228 3273 3229 TUN/TAP persistent tunnel config mode: 3274 Available with linux 2.4.7+. These options comprise a standalone mode3275 ofOpenVPN which can be used to create and delete persistent tunnels.3230 Available with linux 2.4.7+. These options comprise a standalone mode of 3231 OpenVPN which can be used to create and delete persistent tunnels. 3276 3232 3277 3233 --mktun 3278 (Standalone) Create a persistent tunnel on platforms which sup‐ 3279 port them such as Linux. Normally TUN/TAP tunnels exist only 3280 for the period of time that an application has them open. This 3281 option takes advantage of the TUN/TAP driver's ability to build 3282 persistent tunnels that live through multiple instantiations of 3283 OpenVPN and die only when they are deleted or the machine is 3284 rebooted. 3285 3286 One of the advantages of persistent tunnels is that they elimi‐ 3287 nate the need for separate --up and --down scripts to run the 3288 appropriate ifconfig(8) and route(8) commands. These commands 3289 can be placed in the the same shell script which starts or ter‐ 3290 minates an OpenVPN session. 3291 3292 Another advantage is that open connections through the TUN/TAP- 3293 based tunnel will not be reset if the OpenVPN peer restarts. 3294 This can be useful to provide uninterrupted connectivity through 3295 the tunnel in the event of a DHCP reset of the peer's public IP 3296 address (see the --ipchange option above). 3297 3298 One disadvantage of persistent tunnels is that it is harder to 3299 automatically configure their MTU value (see --link-mtu and 3300 --tun-mtu above). 3301 3302 On some platforms such as Windows, TAP-Win32 tunnels are persis‐ 3303 tent by default. 3234 (Standalone) Create a persistent tunnel on platforms which support 3235 them such as Linux. Normally TUN/TAP tunnels exist only for the 3236 period of time that an application has them open. This option 3237 takes advantage of the TUN/TAP driver's ability to build persistent 3238 tunnels that live through multiple instantiations of OpenVPN and 3239 die only when they are deleted or the machine is rebooted. 3240 3241 One of the advantages of persistent tunnels is that they eliminate 3242 the need for separate --up and --down scripts to run the appropri‐ 3243 ate ifconfig(8) and route(8) commands. These commands can be 3244 placed in the the same shell script which starts or terminates an 3245 OpenVPN session. 3246 3247 Another advantage is that open connections through the TUN/TAP- 3248 based tunnel will not be reset if the OpenVPN peer restarts. This 3249 can be useful to provide uninterrupted connectivity through the 3250 tunnel in the event of a DHCP reset of the peer's public IP address 3251 (see the --ipchange option above). 3252 3253 One disadvantage of persistent tunnels is that it is harder to 3254 automatically configure their MTU value (see --link-mtu and --tun- 3255 mtu above). 3256 3257 On some platforms such as Windows, TAP-Win32 tunnels are persistent 3258 by default. 3304 3259 3305 3260 --rmtun … … 3317 3272 Windows-Specific Options: 3318 3273 --win-sys path 3319 Set the Windows system directory pathname to use when looking 3320 for system executables such as route.exe and netsh.exe. By 3321 default, if this directive is not specified, OpenVPN will use 3322 the SystemRoot environment variable. 3323 3324 This option have changed behaviour in OpenVPN 2.3. Earlier you 3325 had to define --win-sys env to use the SystemRoot environment 3326 variable, otherwise it defaulted to C:\WINDOWS. It is not 3327 needed to use the env keyword any more, and it will just be 3328 ignored. A warning is logged when this is found in the configu‐ 3329 ration file. 3274 Set the Windows system directory pathname to use when looking for 3275 system executables such as route.exe and netsh.exe. By default, if 3276 this directive is not specified, OpenVPN will use the SystemRoot 3277 environment variable. 3278 3279 This option have changed behaviour in OpenVPN 2.3. Earlier you had 3280 to define --win-sys env to use the SystemRoot environment variable, 3281 otherwise it defaulted to C:\WINDOWS. It is not needed to use the 3282 env keyword any more, and it will just be ignored. A warning is 3283 logged when this is found in the configuration file. 3330 3284 3331 3285 --ip-win32 method 3332 When using --ifconfig on Windows, set the TAP-Win32 adapter IP 3333 address and netmask using method. Don't use this option unless 3334 you are also using --ifconfig. 3335 3336 manual -- Don't set the IP address or netmask automatically. 3337 Instead output a message to the console telling the user to con‐ 3338 figure the adapter manually and indicating the IP/netmask which 3339 OpenVPN expects the adapter to be set to. 3340 3341 dynamic [offset] [lease-time] -- Automatically set the IP 3342 address and netmask by replying to DHCP query messages generated 3343 by the kernel. This mode is probably the "cleanest" solution 3344 for setting the TCP/IP properties since it uses the well-known 3345 DHCP protocol. There are, however, two prerequisites for using 3346 this mode: (1) The TCP/IP properties for the TAP-Win32 adapter 3347 must be set to "Obtain an IP address automatically," and (2) 3348 OpenVPN needs to claim an IP address in the subnet for use as 3349 the virtual DHCP server address. By default in --dev tap mode, 3350 OpenVPN will take the normally unused first address in the sub‐ 3351 net. For example, if your subnet is 192.168.4.0 netmask 3352 255.255.255.0, then OpenVPN will take the IP address 192.168.4.0 3353 to use as the virtual DHCP server address. In --dev tun mode, 3354 OpenVPN will cause the DHCP server to masquerade as if it were 3355 coming from the remote endpoint. The optional offset parameter 3356 is an integer which is > -256 and < 256 and which defaults to 0. 3357 If offset is positive, the DHCP server will masquerade as the IP 3358 address at network address + offset. If offset is negative, the 3359 DHCP server will masquerade as the IP address at broadcast 3360 address + offset. The Windows ipconfig /all command can be used 3361 to show what Windows thinks the DHCP server address is. OpenVPN 3362 will "claim" this address, so make sure to use a free address. 3363 Having said that, different OpenVPN instantiations, including 3364 different ends of the same connection, can share the same vir‐ 3365 tual DHCP server address. The lease-time parameter controls the 3366 lease time of the DHCP assignment given to the TAP-Win32 3367 adapter, and is denoted in seconds. Normally a very long lease 3368 time is preferred because it prevents routes involving the TAP- 3369 Win32 adapter from being lost when the system goes to sleep. 3370 The default lease time is one year. 3371 3372 netsh -- Automatically set the IP address and netmask using the 3373 Windows command-line "netsh" command. This method appears to 3374 work correctly on Windows XP but not Windows 2000. 3375 3376 ipapi -- Automatically set the IP address and netmask using the 3377 Windows IP Helper API. This approach does not have ideal seman‐ 3378 tics, though testing has indicated that it works okay in prac‐ 3379 tice. If you use this option, it is best to leave the TCP/IP 3380 properties for the TAP-Win32 adapter in their default state, 3381 i.e. "Obtain an IP address automatically." 3382 3383 adaptive -- (Default) Try dynamic method initially and fail over 3384 to netsh if the DHCP negotiation with the TAP-Win32 adapter does 3385 not succeed in 20 seconds. Such failures have been known to 3386 occur when certain third-party firewall packages installed on 3387 the client machine block the DHCP negotiation used by the TAP- 3388 Win32 adapter. Note that if the netsh failover occurs, the TAP- 3389 Win32 adapter TCP/IP properties will be reset from DHCP to 3390 static, and this will cause future OpenVPN startups using the 3391 adaptive mode to use netsh immediately, rather than trying 3392 dynamic first. To "unstick" the adaptive mode from using netsh, 3393 run OpenVPN at least once using the dynamic mode to restore the 3394 TAP-Win32 adapter TCP/IP properties to a DHCP configuration. 3286 When using --ifconfig on Windows, set the TAP-Win32 adapter IP 3287 address and netmask using method. Don't use this option unless you 3288 are also using --ifconfig. 3289 3290 manual -- Don't set the IP address or netmask automatically. 3291 Instead output a message to the console telling the user to config‐ 3292 ure the adapter manually and indicating the IP/netmask which Open‐ 3293 VPN expects the adapter to be set to. 3294 3295 dynamic [offset] [lease-time] -- Automatically set the IP address 3296 and netmask by replying to DHCP query messages generated by the 3297 kernel. This mode is probably the "cleanest" solution for setting 3298 the TCP/IP properties since it uses the well-known DHCP protocol. 3299 There are, however, two prerequisites for using this mode: (1) The 3300 TCP/IP properties for the TAP-Win32 adapter must be set to "Obtain 3301 an IP address automatically," and (2) OpenVPN needs to claim an IP 3302 address in the subnet for use as the virtual DHCP server address. 3303 By default in --dev tap mode, OpenVPN will take the normally unused 3304 first address in the subnet. For example, if your subnet is 3305 192.168.4.0 netmask 255.255.255.0, then OpenVPN will take the IP 3306 address 192.168.4.0 to use as the virtual DHCP server address. In 3307 --dev tun mode, OpenVPN will cause the DHCP server to masquerade as 3308 if it were coming from the remote endpoint. The optional offset 3309 parameter is an integer which is > -256 and < 256 and which 3310 defaults to 0. If offset is positive, the DHCP server will mas‐ 3311 querade as the IP address at network address + offset. If offset 3312 is negative, the DHCP server will masquerade as the IP address at 3313 broadcast address + offset. The Windows ipconfig /all command can 3314 be used to show what Windows thinks the DHCP server address is. 3315 OpenVPN will "claim" this address, so make sure to use a free 3316 address. Having said that, different OpenVPN instantiations, 3317 including different ends of the same connection, can share the same 3318 virtual DHCP server address. The lease-time parameter controls the 3319 lease time of the DHCP assignment given to the TAP-Win32 adapter, 3320 and is denoted in seconds. Normally a very long lease time is pre‐ 3321 ferred because it prevents routes involving the TAP-Win32 adapter 3322 from being lost when the system goes to sleep. The default lease 3323 time is one year. 3324 3325 netsh -- Automatically set the IP address and netmask using the 3326 Windows command-line "netsh" command. This method appears to work 3327 correctly on Windows XP but not Windows 2000. 3328 3329 ipapi -- Automatically set the IP address and netmask using the 3330 Windows IP Helper API. This approach does not have ideal seman‐ 3331 tics, though testing has indicated that it works okay in practice. 3332 If you use this option, it is best to leave the TCP/IP properties 3333 for the TAP-Win32 adapter in their default state, i.e. "Obtain an 3334 IP address automatically." 3335 3336 adaptive -- (Default) Try dynamic method initially and fail over to 3337 netsh if the DHCP negotiation with the TAP-Win32 adapter does not 3338 succeed in 20 seconds. Such failures have been known to occur when 3339 certain third-party firewall packages installed on the client 3340 machine block the DHCP negotiation used by the TAP-Win32 adapter. 3341 Note that if the netsh failover occurs, the TAP-Win32 adapter 3342 TCP/IP properties will be reset from DHCP to static, and this will 3343 cause future OpenVPN startups using the adaptive mode to use netsh 3344 immediately, rather than trying dynamic first. To "unstick" the 3345 adaptive mode from using netsh, run OpenVPN at least once using the 3346 dynamic mode to restore the TAP-Win32 adapter TCP/IP properties to 3347 a DHCP configuration. 3395 3348 3396 3349 --route-method m 3397 3350 Which method m to use for adding routes on Windows? 3398 3351 3399 adaptive (default) -- Try IP helper API first. If that fails,3400 fallback to the route.exe shell command.3352 adaptive (default) -- Try IP helper API first. If that fails, fall 3353 back to the route.exe shell command. 3401 3354 ipapi -- Use IP helper API. 3402 3355 exe -- Call the route.exe shell command. 3403 3356 3404 3357 --dhcp-option type [parm] 3405 Set extended TAP-Win32 TCP/IP properties, must be used with3406 --ip-win32 dynamic or --ip-win32 adaptive. This option can be3407 used to set additional TCP/IP properties on the TAP-Win323408 adapter, and is particularly useful for configuring an OpenVPN3409 client to access aSamba server across the VPN.3358 Set extended TAP-Win32 TCP/IP properties, must be used with --ip- 3359 win32 dynamic or --ip-win32 adaptive. This option can be used to 3360 set additional TCP/IP properties on the TAP-Win32 adapter, and is 3361 particularly useful for configuring an OpenVPN client to access a 3362 Samba server across the VPN. 3410 3363 3411 3364 DOMAIN name -- Set Connection-specific DNS Suffix. 3412 3365 3413 DNS addr -- Set primary domain name server address. Repeatthis3366 DNS addr -- Set primary domain name server address. Repeat this 3414 3367 option to set secondary DNS server addresses. 3415 3368 3416 WINS addr -- Set primary WINS server address (NetBIOS over 3417 TCP/IP Name Server). Repeat this option to set secondary WINS 3418 server addresses. 3419 3420 NBDD addr -- Set primary NBDD server address (NetBIOS over 3421 TCP/IP Datagram Distribution Server) Repeat this option to set 3422 secondary NBDD server addresses. 3423 3424 NTP addr -- Set primary NTP server address (Network Time Proto‐ 3425 col). Repeat this option to set secondary NTP server addresses. 3426 3427 NBT type -- Set NetBIOS over TCP/IP Node type. Possible 3428 options: 1 = b-node (broadcasts), 2 = p-node (point-to-point 3429 name queries to a WINS server), 4 = m-node (broadcast then query 3430 name server), and 8 = h-node (query name server, then broad‐ 3431 cast). 3432 3433 NBS scope-id -- Set NetBIOS over TCP/IP Scope. A NetBIOS Scope 3434 ID provides an extended naming service for the NetBIOS over 3435 TCP/IP (Known as NBT) module. The primary purpose of a NetBIOS 3436 scope ID is to isolate NetBIOS traffic on a single network to 3437 only those nodes with the same NetBIOS scope ID. The NetBIOS 3438 scope ID is a character string that is appended to the NetBIOS 3439 name. The NetBIOS scope ID on two hosts must match, or the two 3440 hosts will not be able to communicate. The NetBIOS Scope ID also 3441 allows computers to use the same computer name, as they have 3442 different scope IDs. The Scope ID becomes a part of the NetBIOS 3443 name, making the name unique. (This description of NetBIOS 3444 scopes courtesy of NeonSurge@abyss.com) 3369 WINS addr -- Set primary WINS server address (NetBIOS over TCP/IP 3370 Name Server). Repeat this option to set secondary WINS server 3371 addresses. 3372 3373 NBDD addr -- Set primary NBDD server address (NetBIOS over TCP/IP 3374 Datagram Distribution Server) Repeat this option to set secondary 3375 NBDD server addresses. 3376 3377 NTP addr -- Set primary NTP server address (Network Time Protocol). 3378 Repeat this option to set secondary NTP server addresses. 3379 3380 NBT type -- Set NetBIOS over TCP/IP Node type. Possible options: 1 3381 = b-node (broadcasts), 2 = p-node (point-to-point name queries to a 3382 WINS server), 4 = m-node (broadcast then query name server), and 8 3383 = h-node (query name server, then broadcast). 3384 3385 NBS scope-id -- Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID 3386 provides an extended naming service for the NetBIOS over TCP/IP 3387 (Known as NBT) module. The primary purpose of a NetBIOS scope ID is 3388 to isolate NetBIOS traffic on a single network to only those nodes 3389 with the same NetBIOS scope ID. The NetBIOS scope ID is a charac‐ 3390 ter string that is appended to the NetBIOS name. The NetBIOS scope 3391 ID on two hosts must match, or the two hosts will not be able to 3392 communicate. The NetBIOS Scope ID also allows computers to use the 3393 same computer name, as they have different scope IDs. The Scope ID 3394 becomes a part of the NetBIOS name, making the name unique. (This 3395 description of NetBIOS scopes courtesy of NeonSurge@abyss.com) 3445 3396 3446 3397 DISABLE-NBT -- Disable Netbios-over-TCP/IP. 3447 3398 3448 Note that if --dhcp-option is pushed via --push to a non-windows 3449 client, the option will be saved in the client's environment 3450 before the up script is called, under the name "for‐ 3451 eign_option_{n}". 3399 Note that if --dhcp-option is pushed via --push to a non-windows 3400 client, the option will be saved in the client's environment before 3401 the up script is called, under the name "foreign_option_{n}". 3452 3402 3453 3403 --tap-sleep n 3454 Cause OpenVPN to sleepfor n seconds immediately after the TAP-3404 Cause OpenVPN to sleep for n seconds immediately after the TAP- 3455 3405 Win32 adapter state is set to "connected". 3456 3406 3457 This option is intended to be used to troubleshoot problemswith3458 the --ifconfig and --ip-win32 options, and is used to give the3459 TAP-Win32 adapter time to come up before Windows IP Helper API3460 operations are applied to it.3407 This option is intended to be used to troubleshoot problems with 3408 the --ifconfig and --ip-win32 options, and is used to give the TAP- 3409 Win32 adapter time to come up before Windows IP Helper API opera‐ 3410 tions are applied to it. 3461 3411 3462 3412 --show-net-up 3463 Output OpenVPN's view of the systemrouting table and network3464 adapter list to the syslog or log file after the TUN/TAPadapter3413 Output OpenVPN's view of the system routing table and network 3414 adapter list to the syslog or log file after the TUN/TAP adapter 3465 3415 has been brought up and any routes have been added. 3466 3416 3467 3417 --dhcp-renew 3468 Ask Windows to renew the TAP adapter lease on startup. This3469 option is normally unnecessary, as Windows automatically trig‐3470 gers a DHCP renegotiation on the TAP adapter when it comes up,3471 however if you set the TAP-Win32 adapter Media Status property3472 to "Always Connected", you may need this flag.3418 Ask Windows to renew the TAP adapter lease on startup. This option 3419 is normally unnecessary, as Windows automatically triggers a DHCP 3420 renegotiation on the TAP adapter when it comes up, however if you 3421 set the TAP-Win32 adapter Media Status property to "Always Con‐ 3422 nected", you may need this flag. 3473 3423 3474 3424 --dhcp-release 3475 Ask Windows to releasethe TAP adapter lease on shutdown. This3425 Ask Windows to release the TAP adapter lease on shutdown. This 3476 3426 option has the same caveats as --dhcp-renew above. 3477 3427 3478 3428 --register-dns 3479 Run net stop dnscache, net start dnscache, ipconfig /flushdns3480 and ipconfig /registerdns on connection initiation. This is3481 k nown to kick Windows into recognizing pushed DNS servers.3429 Run net stop dnscache, net start dnscache, ipconfig /flushdns and 3430 ipconfig /registerdns on connection initiation. This is known to 3431 kick Windows into recognizing pushed DNS servers. 3482 3432 3483 3433 --pause-exit 3484 Put up a "press any key to continue" message on the console3485 prior to OpenVPN program exit. This option is automatically3486 used by the Windows explorer when OpenVPN is run on a configura‐3487 t ion file using the right-click explorer menu.3434 Put up a "press any key to continue" message on the console prior 3435 to OpenVPN program exit. This option is automatically used by the 3436 Windows explorer when OpenVPN is run on a configuration file using 3437 the right-click explorer menu. 3488 3438 3489 3439 --service exit-event [0|1] 3490 Should be used when OpenVPN is being automatically executed by 3491 another program in such a context that no interaction with the 3492 user via display or keyboard is possible. In general, end-users 3493 should never need to explicitly use this option, as it is auto‐ 3494 matically added by the OpenVPN service wrapper when a given 3495 OpenVPN configuration is being run as a service. 3496 3497 exit-event is the name of a Windows global event object, and 3498 OpenVPN will continuously monitor the state of this event object 3499 and exit when it becomes signaled. 3500 3501 The second parameter indicates the initial state of exit-event 3502 and normally defaults to 0. 3503 3504 Multiple OpenVPN processes can be simultaneously executed with 3505 the same exit-event parameter. In any case, the controlling 3506 process can signal exit-event, causing all such OpenVPN pro‐ 3507 cesses to exit. 3508 3509 When executing an OpenVPN process using the --service directive, 3510 OpenVPN will probably not have a console window to output sta‐ 3511 tus/error messages, therefore it is useful to use --log or 3512 --log-append to write these messages to a file. 3440 Should be used when OpenVPN is being automatically executed by 3441 another program in such a context that no interaction with the user 3442 via display or keyboard is possible. In general, end-users should 3443 never need to explicitly use this option, as it is automatically 3444 added by the OpenVPN service wrapper when a given OpenVPN configu‐ 3445 ration is being run as a service. 3446 3447 exit-event is the name of a Windows global event object, and Open‐ 3448 VPN will continuously monitor the state of this event object and 3449 exit when it becomes signaled. 3450 3451 The second parameter indicates the initial state of exit-event and 3452 normally defaults to 0. 3453 3454 Multiple OpenVPN processes can be simultaneously executed with the 3455 same exit-event parameter. In any case, the controlling process 3456 can signal exit-event, causing all such OpenVPN processes to exit. 3457 3458 When executing an OpenVPN process using the --service directive, 3459 OpenVPN will probably not have a console window to output sta‐ 3460 tus/error messages, therefore it is useful to use --log or --log- 3461 append to write these messages to a file. 3513 3462 3514 3463 --show-adapters 3515 (Standalone) Show available TAP-Win32 adapters which canbe3516 selected using the --dev-node option. On non-Windows systems,3517 theifconfig(8) command provides similar functionality.3464 (Standalone) Show available TAP-Win32 adapters which can be 3465 selected using the --dev-node option. On non-Windows systems, the 3466 ifconfig(8) command provides similar functionality. 3518 3467 3519 3468 --allow-nonadmin [TAP-adapter] 3520 (Standalone) Set TAP-adapter to allow access from non-adminis‐ 3521 trative accounts. If TAP-adapter is omitted, all TAP adapters 3522 on the system will be configured to allow non-admin access. The 3523 non-admin access setting will only persist for the length of 3524 time that the TAP-Win32 device object and driver remain loaded, 3525 and will need to be re-enabled after a reboot, or if the driver 3526 is unloaded and reloaded. This directive can only be used by an 3527 administrator. 3469 (Standalone) Set TAP-adapter to allow access from non-administra‐ 3470 tive accounts. If TAP-adapter is omitted, all TAP adapters on the 3471 system will be configured to allow non-admin access. The non-admin 3472 access setting will only persist for the length of time that the 3473 TAP-Win32 device object and driver remain loaded, and will need to 3474 be re-enabled after a reboot, or if the driver is unloaded and 3475 reloaded. This directive can only be used by an administrator. 3528 3476 3529 3477 --show-valid-subnets 3530 (Standalone) Show valid subnets for --dev tun emulation. Since3531 the TAP-Win32 driver exports an ethernet interface to Windows,3532 and since TUN devices are point-to-point in nature, it is neces‐3533 sary for the TAP-Win32 driver to impose certain constraints on3534 TUN endpointaddress selection.3535 3536 Namely, the point-to-point endpoints used in TUN device emula ‐3537 tion must be the middle two addresses of a /30 subnet(netmask3478 (Standalone) Show valid subnets for --dev tun emulation. Since the 3479 TAP-Win32 driver exports an ethernet interface to Windows, and 3480 since TUN devices are point-to-point in nature, it is necessary for 3481 the TAP-Win32 driver to impose certain constraints on TUN endpoint 3482 address selection. 3483 3484 Namely, the point-to-point endpoints used in TUN device emulation 3485 must be the middle two addresses of a /30 subnet (netmask 3538 3486 255.255.255.252). 3539 3487 3540 3488 --show-net 3541 (Standalone) Show OpenVPN's view of the system routing tableand3489 (Standalone) Show OpenVPN's view of the system routing table and 3542 3490 network adapter list. 3543 3491 3544 3492 PKCS#11 Standalone Options: 3545 3493 --show-pkcs11-ids provider [cert_private] 3546 (Standalone) Show PKCS#11 token object list. Specify cert_pri ‐3547 vateas 1 if certificates are stored as private objects.3548 3549 --verb option can be used BEFORE this option to produce debug ‐3550 ginginformation.3494 (Standalone) Show PKCS#11 token object list. Specify cert_private 3495 as 1 if certificates are stored as private objects. 3496 3497 --verb option can be used BEFORE this option to produce debugging 3498 information. 3551 3499 3552 3500 IPv6 Related Options 3553 The following options exist to support IPv6 tunneling in peer-to-peer3554 and client-server mode. As of now, this is just very basic documenta‐3555 t ion of the IPv6-related options. More documentation can be foundon3501 The following options exist to support IPv6 tunneling in peer-to-peer and 3502 client-server mode. As of now, this is just very basic documentation of 3503 the IPv6-related options. More documentation can be found on 3556 3504 http://www.greenie.net/ipv6/openvpn.html. 3557 3505 3558 3506 --ifconfig-ipv6 ipv6addr/bits ipv6remote 3559 configure IPv6 address ipv6addr/bits on the ``tun'' device.The3560 second parameter is usedas route target for --route-ipv6 if no3507 configure IPv6 address ipv6addr/bits on the ``tun'' device. The 3508 second parameter is used as route target for --route-ipv6 if no 3561 3509 gateway is specified. 3562 3510 3563 3511 --route-ipv6 ipv6addr/bits [gateway] [metric] 3564 setup IPv6 routing in the system to send the specified IPv6 net ‐3565 workinto OpenVPN's ``tun'' device3512 setup IPv6 routing in the system to send the specified IPv6 network 3513 into OpenVPN's ``tun'' device 3566 3514 3567 3515 --server-ipv6 ipv6addr/bits 3568 convenience-function to enable a number of IPv6 related options 3569 at once, namely --ifconfig-ipv6, --ifconfig-ipv6-pool, --tun-3570 ipv6 and --push tun-ipv6 Is only accepted if ``--mode server''3571 or``--server'' is set.3516 convenience-function to enable a number of IPv6 related options at 3517 once, namely --ifconfig-ipv6, --ifconfig-ipv6-pool, --tun-ipv6 and 3518 --push tun-ipv6 Is only accepted if ``--mode server'' or 3519 ``--server'' is set. 3572 3520 3573 3521 --ifconfig-ipv6-pool ipv6addr/bits 3574 Specify an IPv6 address pool for dynamic assignmentto clients.3575 The pool starts at ipv6addrand increments by +1 for every new3576 client (linear mode). The /bits setting controls the size of3577 thepool.3522 Specify an IPv6 address pool for dynamic assignment to clients. 3523 The pool starts at ipv6addr and increments by +1 for every new 3524 client (linear mode). The /bits setting controls the size of the 3525 pool. 3578 3526 3579 3527 --ifconfig-ipv6-push ipv6addr/bits ipv6remote 3580 for ccd/ per-client static IPv6 interface configuration,see3528 for ccd/ per-client static IPv6 interface configuration, see 3581 3529 --client-config-dir and --ifconfig-push for more details. 3582 3530 3583 3531 --iroute-ipv6 ipv6addr/bits 3584 for ccd/ per-client static IPv6 route configuration, see3585 --iroute for more details how to setup and use this, and how3586 -- iroute and --route interact.3532 for ccd/ per-client static IPv6 route configuration, see --iroute 3533 for more details how to setup and use this, and how --iroute and 3534 --route interact. 3587 3535 3588 3536 3589 3537 SCRIPTING AND ENVIRONMENTAL VARIABLES 3590 OpenVPN exports a series of environmental variablesfor use by user-3538 OpenVPN exports a series of environmental variables for use by user- 3591 3539 defined scripts. 3592 3540 … … 3598 3546 3599 3547 --ipchange 3600 Executed after connection authentication, orremote IP address3548 Executed after connection authentication, or remote IP address 3601 3549 change. 3602 3550 3603 3551 --client-connect 3604 Executed in --mode server mode immediately after client authen‐3605 ti cation.3552 Executed in --mode server mode immediately after client authentica‐ 3553 tion. 3606 3554 3607 3555 --route-up 3608 Executed after connection authentication, either immediately3609 after, or some number of seconds after as defined by the3610 --route-delayoption.3556 Executed after connection authentication, either immediately after, 3557 or some number of seconds after as defined by the --route-delay 3558 option. 3611 3559 3612 3560 --route-pre-down … … 3619 3567 3620 3568 --learn-address 3621 Executed in --modeserver mode whenever an IPv4 address/route or3569 Executed in --mode server mode whenever an IPv4 address/route or 3622 3570 MAC address is added to OpenVPN's internal routing table. 3623 3571 3624 3572 --auth-user-pass-verify 3625 Executed in --mode server mode on new client connections, when3626 theclient is still untrusted.3573 Executed in --mode server mode on new client connections, when the 3574 client is still untrusted. 3627 3575 3628 3576 String Types and Remapping 3629 In certain cases, OpenVPN will perform remapping of characters in3630 strings. Essentially, any characters outside the set of permitted3631 characters foreach string type will be converted to underbar ('_').3577 In certain cases, OpenVPN will perform remapping of characters in strings. 3578 Essentially, any characters outside the set of permitted characters for 3579 each string type will be converted to underbar ('_'). 3632 3580 3633 3581 Q: Why is string remapping necessary? 3634 3582 3635 A: It's an important security feature to prevent the malicious coding 3636 of strings from untrusted sources to be passed as parameters to3637 s cripts, saved in the environment, used as a common name, translated to3638 a filename,etc.3583 A: It's an important security feature to prevent the malicious coding of 3584 strings from untrusted sources to be passed as parameters to scripts, 3585 saved in the environment, used as a common name, translated to a filename, 3586 etc. 3639 3587 3640 3588 Q: Can string remapping be disabled? 3641 3589 3642 A: Yes, by using the --no-name-remapping option, however this shouldbe3590 A: Yes, by using the --no-name-remapping option, however this should be 3643 3591 considered an advanced option. 3644 3592 3645 Here is a brief rundown of OpenVPN's current string types and the per‐ 3646 mitted character class for each string: 3647 3648 X509 Names: Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), at 3649 ('@'), colon (':'), slash ('/'), and equal ('='). Alphanumeric is 3650 defined as a character which will cause the C library isalnum() func‐ 3651 tion to return true. 3652 3653 Common Names: Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), and 3654 at ('@'). 3655 3656 --auth-user-pass username: Same as Common Name, with one exception: 3657 starting with OpenVPN 2.0.1, the username is passed to the OPEN‐ 3658 VPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin in its raw form, without string 3659 remapping. 3660 3661 --auth-user-pass password: Any "printable" character except CR or LF. 3662 Printable is defined to be a character which will cause the C library 3593 Here is a brief rundown of OpenVPN's current string types and the permit‐ 3594 ted character class for each string: 3595 3596 X509 Names: Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), at ('@'), 3597 colon (':'), slash ('/'), and equal ('='). Alphanumeric is defined as a 3598 character which will cause the C library isalnum() function to return 3599 true. 3600 3601 Common Names: Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), and at 3602 ('@'). 3603 3604 --auth-user-pass username: Same as Common Name, with one exception: start‐ 3605 ing with OpenVPN 2.0.1, the username is passed to the OPENVPN_PLUG‐ 3606 IN_AUTH_USER_PASS_VERIFY plugin in its raw form, without string remapping. 3607 3608 --auth-user-pass password: Any "printable" character except CR or LF. 3609 Printable is defined to be a character which will cause the C library 3663 3610 isprint() function to return true. 3664 3611 3665 --client-config-dir filename as derived from common name or username: 3666 Alphanumeric, underbar ('_'), dash ('-'), and dot ('.') except for "." 3667 or ".." as standalone strings. As of 2.0.1-rc6, the at ('@') character 3668 has been added as well for compatibility with the common name character 3669 class. 3612 --client-config-dir filename as derived from common name or username: 3613 Alphanumeric, underbar ('_'), dash ('-'), and dot ('.') except for "." or 3614 ".." as standalone strings. As of 2.0.1-rc6, the at ('@') character has 3615 been added as well for compatibility with the common name character class. 3670 3616 3671 3617 Environmental variable names: Alphanumeric or underbar ('_'). … … 3673 3619 Environmental variable values: Any printable character. 3674 3620 3675 For all cases, characters in a string which are not members of the 3676 legal character class for that string type will be remapped to underbar 3677 ('_'). 3621 For all cases, characters in a string which are not members of the legal 3622 character class for that string type will be remapped to underbar ('_'). 3678 3623 3679 3624 Environmental Variables 3680 Once set, a variable is persisted indefinitely until it is reset by a 3681 new value or a restart, 3682 3683 As of OpenVPN 2.0-beta12, in server mode, environmental variables set 3684 by OpenVPN are scoped according to the client objects they are associ‐ 3685 ated with, so there should not be any issues with scripts having access 3686 to stale, previously set variables which refer to different client 3687 instances. 3625 Once set, a variable is persisted indefinitely until it is reset by a new 3626 value or a restart, 3627 3628 As of OpenVPN 2.0-beta12, in server mode, environmental variables set by 3629 OpenVPN are scoped according to the client objects they are associated 3630 with, so there should not be any issues with scripts having access to 3631 stale, previously set variables which refer to different client instances. 3688 3632 3689 3633 bytes_received 3690 Total number of bytes received from client during VPN session.3691 Setprior to execution of the --client-disconnect script.3634 Total number of bytes received from client during VPN session. Set 3635 prior to execution of the --client-disconnect script. 3692 3636 3693 3637 bytes_sent 3694 Total number of bytes sent to client during VPN session. Set3695 priorto execution of the --client-disconnect script.3638 Total number of bytes sent to client during VPN session. Set prior 3639 to execution of the --client-disconnect script. 3696 3640 3697 3641 common_name 3698 The X509 common name of an authenticated client. Set prior to3699 execution of --client-connect, --client-disconnect, and --auth-3700 user-pass-verify scripts.3701 3702 config Name of first --config file. Set on program initiation and3703 reseton SIGHUP.3704 3705 daemon Set to "1"if the --daemon directive is specified, or "0" other‐3642 The X509 common name of an authenticated client. Set prior to exe‐ 3643 cution of --client-connect, --client-disconnect, and --auth-user- 3644 pass-verify scripts. 3645 3646 config Name of first --config file. Set on program initiation and reset 3647 on SIGHUP. 3648 3649 daemon Set to "1" if the --daemon directive is specified, or "0" other‐ 3706 3650 wise. Set on program initiation and reset on SIGHUP. 3707 3651 3708 3652 daemon_log_redirect 3709 Set to "1" if the --log or --log-append directives are speci‐ 3710 fied, or "0" otherwise. Set on program initiation and reset on 3653 Set to "1" if the --log or --log-append directives are specified, 3654 or "0" otherwise. Set on program initiation and reset on SIGHUP. 3655 3656 dev The actual name of the TUN/TAP device, including a unit number if 3657 it exists. Set prior to --up or --down script execution. 3658 3659 foreign_option_{n} 3660 An option pushed via --push to a client which does not natively 3661 support it, such as --dhcp-option on a non-Windows system, will be 3662 recorded to this environmental variable sequence prior to --up 3663 script execution. 3664 3665 ifconfig_broadcast 3666 The broadcast address for the virtual ethernet segment which is 3667 derived from the --ifconfig option when --dev tap is used. Set 3668 prior to OpenVPN calling the ifconfig or netsh (windows version of 3669 ifconfig) commands which normally occurs prior to --up script exe‐ 3670 cution. 3671 3672 ifconfig_ipv6_local 3673 The local VPN endpoint IPv6 address specified in the --ifconfig- 3674 ipv6 option (first parameter). Set prior to OpenVPN calling the 3675 ifconfig or netsh (windows version of ifconfig) commands which nor‐ 3676 mally occurs prior to --up script execution. 3677 3678 ifconfig_ipv6_netbits 3679 The prefix length of the IPv6 network on the VPN interface. 3680 Derived from the /nnn parameter of the IPv6 address in the --ifcon‐ 3681 fig-ipv6 option (first parameter). Set prior to OpenVPN calling 3682 the ifconfig or netsh (windows version of ifconfig) commands which 3683 normally occurs prior to --up script execution. 3684 3685 ifconfig_ipv6_remote 3686 The remote VPN endpoint IPv6 address specified in the --ifconfig- 3687 ipv6 option (second parameter). Set prior to OpenVPN calling the 3688 ifconfig or netsh (windows version of ifconfig) commands which nor‐ 3689 mally occurs prior to --up script execution. 3690 3691 ifconfig_local 3692 The local VPN endpoint IP address specified in the --ifconfig 3693 option (first parameter). Set prior to OpenVPN calling the ifcon‐ 3694 fig or netsh (windows version of ifconfig) commands which normally 3695 occurs prior to --up script execution. 3696 3697 ifconfig_remote 3698 The remote VPN endpoint IP address specified in the --ifconfig 3699 option (second parameter) when --dev tun is used. Set prior to 3700 OpenVPN calling the ifconfig or netsh (windows version of ifconfig) 3701 commands which normally occurs prior to --up script execution. 3702 3703 ifconfig_netmask 3704 The subnet mask of the virtual ethernet segment that is specified 3705 as the second parameter to --ifconfig when --dev tap is being used. 3706 Set prior to OpenVPN calling the ifconfig or netsh (windows version 3707 of ifconfig) commands which normally occurs prior to --up script 3708 execution. 3709 3710 ifconfig_pool_local_ip 3711 The local virtual IP address for the TUN/TAP tunnel taken from an 3712 --ifconfig-push directive if specified, or otherwise from the 3713 ifconfig pool (controlled by the --ifconfig-pool config file direc‐ 3714 tive). Only set for --dev tun tunnels. This option is set on the 3715 server prior to execution of the --client-connect and --client-dis‐ 3716 connect scripts. 3717 3718 ifconfig_pool_netmask 3719 The virtual IP netmask for the TUN/TAP tunnel taken from an 3720 --ifconfig-push directive if specified, or otherwise from the 3721 ifconfig pool (controlled by the --ifconfig-pool config file direc‐ 3722 tive). Only set for --dev tap tunnels. This option is set on the 3723 server prior to execution of the --client-connect and --client-dis‐ 3724 connect scripts. 3725 3726 ifconfig_pool_remote_ip 3727 The remote virtual IP address for the TUN/TAP tunnel taken from an 3728 --ifconfig-push directive if specified, or otherwise from the 3729 ifconfig pool (controlled by the --ifconfig-pool config file direc‐ 3730 tive). This option is set on the server prior to execution of the 3731 --client-connect and --client-disconnect scripts. 3732 3733 link_mtu 3734 The maximum packet size (not including the IP header) of tunnel 3735 data in UDP tunnel transport mode. Set prior to --up or --down 3736 script execution. 3737 3738 local The --local parameter. Set on program initiation and reset on 3711 3739 SIGHUP. 3712 3740 3713 dev The actual name of the TUN/TAP device, including a unit number 3714 if it exists. Set prior to --up or --down script execution. 3715 3716 foreign_option_{n} 3717 An option pushed via --push to a client which does not natively 3718 support it, such as --dhcp-option on a non-Windows system, will 3719 be recorded to this environmental variable sequence prior to 3720 --up script execution. 3721 3722 ifconfig_broadcast 3723 The broadcast address for the virtual ethernet segment which is 3724 derived from the --ifconfig option when --dev tap is used. Set 3725 prior to OpenVPN calling the ifconfig or netsh (windows version 3726 of ifconfig) commands which normally occurs prior to --up script 3741 local_port 3742 The local port number, specified by --port or --lport. Set on pro‐ 3743 gram initiation and reset on SIGHUP. 3744 3745 password 3746 The password provided by a connecting client. Set prior to --auth- 3747 user-pass-verify script execution only when the via-env modifier is 3748 specified, and deleted from the environment after the script 3749 returns. 3750 3751 proto The --proto parameter. Set on program initiation and reset on 3752 SIGHUP. 3753 3754 remote_{n} 3755 The --remote parameter. Set on program initiation and reset on 3756 SIGHUP. 3757 3758 remote_port_{n} 3759 The remote port number, specified by --port or --rport. Set on 3760 program initiation and reset on SIGHUP. 3761 3762 route_net_gateway 3763 The pre-existing default IP gateway in the system routing table. 3764 Set prior to --up script execution. 3765 3766 route_vpn_gateway 3767 The default gateway used by --route options, as specified in either 3768 the --route-gateway option or the second parameter to --ifconfig 3769 when --dev tun is specified. Set prior to --up script execution. 3770 3771 route_{parm}_{n} 3772 A set of variables which define each route to be added, and are set 3773 prior to --up script execution. 3774 3775 parm will be one of "network", "netmask", "gateway", or "metric". 3776 3777 n is the OpenVPN route number, starting from 1. 3778 3779 If the network or gateway are resolvable DNS names, their IP 3780 address translations will be recorded rather than their names as 3781 denoted on the command line or configuration file. 3782 3783 route_ipv6_{parm}_{n} 3784 A set of variables which define each IPv6 route to be added, and 3785 are set prior to --up script execution. 3786 3787 parm will be one of "network" or "gateway" ("netmask" is contained 3788 as "/nnn" in the route_ipv6_network_{n}, unlike IPv4 where it is 3789 passed in a separate environment variable). 3790 3791 n is the OpenVPN route number, starting from 1. 3792 3793 If the network or gateway are resolvable DNS names, their IP 3794 address translations will be recorded rather than their names as 3795 denoted on the command line or configuration file. 3796 3797 peer_cert 3798 Temporary file name containing the client certificate upon connec‐ 3799 tion. Useful in conjunction with --tls-verify 3800 3801 script_context 3802 Set to "init" or "restart" prior to up/down script execution. For 3803 more information, see documentation for --up. 3804 3805 script_type 3806 Prior to execution of any script, this variable is set to the type 3807 of script being run. It can be one of the following: up, down, 3808 ipchange, route-up, tls-verify, auth-user-pass-verify, client-con‐ 3809 nect, client-disconnect, or learn-address. Set prior to execution 3810 of any script. 3811 3812 signal The reason for exit or restart. Can be one of sigusr1, sighup, 3813 sigterm, sigint, inactive (controlled by --inactive option), ping- 3814 exit (controlled by --ping-exit option), ping-restart (controlled 3815 by --ping-restart option), connection-reset (triggered on TCP con‐ 3816 nection reset), error, or unknown (unknown signal). This variable 3817 is set just prior to down script execution. 3818 3819 time_ascii 3820 Client connection timestamp, formatted as a human-readable time 3821 string. Set prior to execution of the --client-connect script. 3822 3823 time_duration 3824 The duration (in seconds) of the client session which is now dis‐ 3825 connecting. Set prior to execution of the --client-disconnect 3826 script. 3827 3828 time_unix 3829 Client connection timestamp, formatted as a unix integer date/time 3830 value. Set prior to execution of the --client-connect script. 3831 3832 tls_id_{n} 3833 A series of certificate fields from the remote peer, where n is the 3834 verification level. Only set for TLS connections. Set prior to 3835 execution of --tls-verify script. 3836 3837 tls_serial_{n} 3838 The serial number of the certificate from the remote peer, where n 3839 is the verification level. Only set for TLS connections. Set 3840 prior to execution of --tls-verify script. This is in the form of a 3841 hex string like "37AB46E0", which is suitable for doing serial- 3842 based OCSP queries (with OpenSSL, you have to prepend "0x" to the 3843 string). If something goes wrong while reading the value from the 3844 certificate it will be an empty string, so your code should check 3845 that. See the contrib/OCSP_check/OCSP_check.sh script for an exam‐ 3846 ple. 3847 3848 tun_mtu 3849 The MTU of the TUN/TAP device. Set prior to --up or --down script 3727 3850 execution. 3728 3851 3729 ifconfig_ipv6_local3730 The local VPN endpoint IPv6 address specified in the --ifconfig-3731 ipv6 option (first parameter). Set prior to OpenVPN calling the3732 ifconfig or netsh (windows version of ifconfig) commands which3733 normally occurs prior to --up script execution.3734 3735 ifconfig_ipv6_netbits3736 The prefix length of the IPv6 network on the VPN interface.3737 Derived from the /nnn parameter of the IPv6 address in the3738 --ifconfig-ipv6 option (first parameter). Set prior to OpenVPN3739 calling the ifconfig or netsh (windows version of ifconfig) com‐3740 mands which normally occurs prior to --up script execution.3741 3742 ifconfig_ipv6_remote3743 The remote VPN endpoint IPv6 address specified in the --ifcon‐3744 fig-ipv6 option (second parameter). Set prior to OpenVPN call‐3745 ing the ifconfig or netsh (windows version of ifconfig) commands3746 which normally occurs prior to --up script execution.3747 3748 ifconfig_local3749 The local VPN endpoint IP address specified in the --ifconfig3750 option (first parameter). Set prior to OpenVPN calling the3751 ifconfig or netsh (windows version of ifconfig) commands which3752 normally occurs prior to --up script execution.3753 3754 ifconfig_remote3755 The remote VPN endpoint IP address specified in the --ifconfig3756 option (second parameter) when --dev tun is used. Set prior to3757 OpenVPN calling the ifconfig or netsh (windows version of ifcon‐3758 fig) commands which normally occurs prior to --up script execu‐3759 tion.3760 3761 ifconfig_netmask3762 The subnet mask of the virtual ethernet segment that is speci‐3763 fied as the second parameter to --ifconfig when --dev tap is3764 being used. Set prior to OpenVPN calling the ifconfig or netsh3765 (windows version of ifconfig) commands which normally occurs3766 prior to --up script execution.3767 3768 ifconfig_pool_local_ip3769 The local virtual IP address for the TUN/TAP tunnel taken from3770 an --ifconfig-push directive if specified, or otherwise from the3771 ifconfig pool (controlled by the --ifconfig-pool config file3772 directive). Only set for --dev tun tunnels. This option is set3773 on the server prior to execution of the --client-connect and3774 --client-disconnect scripts.3775 3776 ifconfig_pool_netmask3777 The virtual IP netmask for the TUN/TAP tunnel taken from an3778 --ifconfig-push directive if specified, or otherwise from the3779 ifconfig pool (controlled by the --ifconfig-pool config file3780 directive). Only set for --dev tap tunnels. This option is set3781 on the server prior to execution of the --client-connect and3782 --client-disconnect scripts.3783 3784 ifconfig_pool_remote_ip3785 The remote virtual IP address for the TUN/TAP tunnel taken from3786 an --ifconfig-push directive if specified, or otherwise from the3787 ifconfig pool (controlled by the --ifconfig-pool config file3788 directive). This option is set on the server prior to execution3789 of the --client-connect and --client-disconnect scripts.3790 3791 link_mtu3792 The maximum packet size (not including the IP header) of tunnel3793 data in UDP tunnel transport mode. Set prior to --up or --down3794 script execution.3795 3796 local The --local parameter. Set on program initiation and reset on3797 SIGHUP.3798 3799 local_port3800 The local port number, specified by --port or --lport. Set on3801 program initiation and reset on SIGHUP.3802 3803 password3804 The password provided by a connecting client. Set prior to3805 --auth-user-pass-verify script execution only when the via-env3806 modifier is specified, and deleted from the environment after3807 the script returns.3808 3809 proto The --proto parameter. Set on program initiation and reset on3810 SIGHUP.3811 3812 remote_{n}3813 The --remote parameter. Set on program initiation and reset on3814 SIGHUP.3815 3816 remote_port_{n}3817 The remote port number, specified by --port or --rport. Set on3818 program initiation and reset on SIGHUP.3819 3820 route_net_gateway3821 The pre-existing default IP gateway in the system routing table.3822 Set prior to --up script execution.3823 3824 route_vpn_gateway3825 The default gateway used by --route options, as specified in3826 either the --route-gateway option or the second parameter to3827 --ifconfig when --dev tun is specified. Set prior to --up3828 script execution.3829 3830 route_{parm}_{n}3831 A set of variables which define each route to be added, and are3832 set prior to --up script execution.3833 3834 parm will be one of "network", "netmask", "gateway", or "met‐3835 ric".3836 3837 n is the OpenVPN route number, starting from 1.3838 3839 If the network or gateway are resolvable DNS names, their IP3840 address translations will be recorded rather than their names as3841 denoted on the command line or configuration file.3842 3843 route_ipv6_{parm}_{n}3844 A set of variables which define each IPv6 route to be added, and3845 are set prior to --up script execution.3846 3847 parm will be one of "network" or "gateway" ("netmask" is con‐3848 tained as "/nnn" in the route_ipv6_network_{n}, unlike IPv43849 where it is passed in a separate environment variable).3850 3851 n is the OpenVPN route number, starting from 1.3852 3853 If the network or gateway are resolvable DNS names, their IP3854 address translations will be recorded rather than their names as3855 denoted on the command line or configuration file.3856 3857 peer_cert3858 Temporary file name containing the client certificate upon con‐3859 nection. Useful in conjunction with --tls-verify3860 3861 script_context3862 Set to "init" or "restart" prior to up/down script execution.3863 For more information, see documentation for --up.3864 3865 script_type3866 Prior to execution of any script, this variable is set to the3867 type of script being run. It can be one of the following: up,3868 down, ipchange, route-up, tls-verify, auth-user-pass-verify,3869 client-connect, client-disconnect, or learn-address. Set prior3870 to execution of any script.3871 3872 signal The reason for exit or restart. Can be one of sigusr1, sighup,3873 sigterm, sigint, inactive (controlled by --inactive option),3874 ping-exit (controlled by --ping-exit option), ping-restart (con‐3875 trolled by --ping-restart option), connection-reset (triggered3876 on TCP connection reset), error, or unknown (unknown signal).3877 This variable is set just prior to down script execution.3878 3879 time_ascii3880 Client connection timestamp, formatted as a human-readable time3881 string. Set prior to execution of the --client-connect script.3882 3883 time_duration3884 The duration (in seconds) of the client session which is now3885 disconnecting. Set prior to execution of the --client-discon‐3886 nect script.3887 3888 time_unix3889 Client connection timestamp, formatted as a unix integer3890 date/time value. Set prior to execution of the --client-connect3891 script.3892 3893 tls_id_{n}3894 A series of certificate fields from the remote peer, where n is3895 the verification level. Only set for TLS connections. Set3896 prior to execution of --tls-verify script.3897 3898 tls_serial_{n}3899 The serial number of the certificate from the remote peer, where3900 n is the verification level. Only set for TLS connections. Set3901 prior to execution of --tls-verify script. This is in the form3902 of a hex string like "37AB46E0", which is suitable for doing3903 serial-based OCSP queries (with OpenSSL, you have to prepend3904 "0x" to the string). If something goes wrong while reading the3905 value from the certificate it will be an empty string, so your3906 code should check that. See the con‐3907 trib/OCSP_check/OCSP_check.sh script for an example.3908 3909 tun_mtu3910 The MTU of the TUN/TAP device. Set prior to --up or --down3911 script execution.3912 3913 3852 trusted_ip (or trusted_ip6) 3914 Actual IP address of connecting client or peer which hasbeen3915 authenticated. Set prior to execution of --ipchange, --client-3916 connect, and --client-disconnect scripts. If using ipv6 end‐3917 points(udp6, tcp6), trusted_ip6 will be set instead.3853 Actual IP address of connecting client or peer which has been 3854 authenticated. Set prior to execution of --ipchange, --client-con‐ 3855 nect, and --client-disconnect scripts. If using ipv6 endpoints 3856 (udp6, tcp6), trusted_ip6 will be set instead. 3918 3857 3919 3858 trusted_port 3920 Actual port number of connecting client or peer which hasbeen3921 authenticated. Set prior to execution of --ipchange, --client-3922 connect, and --client-disconnect scripts.3859 Actual port number of connecting client or peer which has been 3860 authenticated. Set prior to execution of --ipchange, --client-con‐ 3861 nect, and --client-disconnect scripts. 3923 3862 3924 3863 untrusted_ip (or untrusted_ip6) 3925 Actual IP address of connecting client or peer which has not3926 been authenticated yet. Sometimes used to nmap the connecting3927 host in a --tls-verify script to ensure it is firewalled prop‐3928 erly. Set prior to execution of --tls-verify and --auth-user-3929 pass-verify scripts. If using ipv6 endpoints (udp6, tcp6),3930 untrusted_ip6 will be setinstead.3864 Actual IP address of connecting client or peer which has not been 3865 authenticated yet. Sometimes used to nmap the connecting host in a 3866 --tls-verify script to ensure it is firewalled properly. Set prior 3867 to execution of --tls-verify and --auth-user-pass-verify scripts. 3868 If using ipv6 endpoints (udp6, tcp6), untrusted_ip6 will be set 3869 instead. 3931 3870 3932 3871 untrusted_port 3933 Actual port number of connecting client or peer which has not3934 been authenticated yet. Set prior to execution of --tls-verify3935 and--auth-user-pass-verify scripts.3872 Actual port number of connecting client or peer which has not been 3873 authenticated yet. Set prior to execution of --tls-verify and 3874 --auth-user-pass-verify scripts. 3936 3875 3937 3876 username 3938 The username provided by a connecting client. Set prior to3939 --auth-user-pass-verify script execution only when the via-env3940 modifier isspecified.3877 The username provided by a connecting client. Set prior to --auth- 3878 user-pass-verify script execution only when the via-env modifier is 3879 specified. 3941 3880 3942 3881 X509_{n}_{subject_field} 3943 An X509 subject field from the remote peer certificate, where n3944 is the verification level. Only set for TLS connections. Set3945 prior to execution of --tls-verify script. This variable is3946 similar to tls_id_{n} except the component X509 subject fields3947 a re broken out, and no string remapping occurs on these field3948 values (except for remapping of control characters to "_"). For3949 example, the following variables would be set on the OpenVPN3950 server using the sample client certificate in sample-keys3951 (client.crt). Note that the verification level is 0 for the3952 c lient certificate and 1 for the CA certificate.3882 An X509 subject field from the remote peer certificate, where n is 3883 the verification level. Only set for TLS connections. Set prior 3884 to execution of --tls-verify script. This variable is similar to 3885 tls_id_{n} except the component X509 subject fields are broken out, 3886 and no string remapping occurs on these field values (except for 3887 remapping of control characters to "_"). For example, the follow‐ 3888 ing variables would be set on the OpenVPN server using the sample 3889 client certificate in sample-keys (client.crt). Note that the ver‐ 3890 ification level is 0 for the client certificate and 1 for the CA 3891 certificate. 3953 3892 3954 3893 X509_0_emailAddress=me@myhost.mydomain … … 3964 3903 3965 3904 INLINE FILE SUPPORT 3966 OpenVPN allows including files in the main configuration for the--ca,3967 --cert, --dh, --extra-certs, --key, --pkcs12, --secret and--tls-auth3905 OpenVPN allows including files in the main configuration for the --ca, 3906 --cert, --dh, --extra-certs, --key, --pkcs12, --secret and --tls-auth 3968 3907 options. 3969 3908 3970 Each inline file started by the line <option> and ended by theline3909 Each inline file started by the line <option> and ended by the line 3971 3910 </option> 3972 3911 … … 3979 3918 </cert> 3980 3919 3981 When using the inline file feature with --pkcs12 the inline file has to 3982 b e base64 encoded. Encoding of a .p12 file into base64 can be done for3983 example with OpenSSL by running openssl base64 -in input.p123920 When using the inline file feature with --pkcs12 the inline file has to be 3921 base64 encoded. Encoding of a .p12 file into base64 can be done for exam‐ 3922 ple with OpenSSL by running openssl base64 -in input.p12 3984 3923 3985 3924 3986 3925 SIGNALS 3987 SIGHUP Cause OpenVPN to close all TUN/TAP and networkconnections,3988 restart, re-read the configuration file (if any), andreopen3926 SIGHUP Cause OpenVPN to close all TUN/TAP and network connections, 3927 restart, re-read the configuration file (if any), and reopen 3989 3928 TUN/TAP and network connections. 3990 3929 3991 3930 SIGUSR1 3992 Like SIGHUP, except don't re-read configuration file, and possi‐3993 bly don't close and reopen TUN/TAP device, re-read key files,3994 preserve local IP address/port, or preserve most recently3995 authenticated remote IP address/port based on --persist-tun,3996 --persist- key, --persist-local-ip, and --persist-remote-ip3997 options respectively(see above).3998 3999 This signal mayalso be internally generated by a timeout condi‐3931 Like SIGHUP, except don't re-read configuration file, and possibly 3932 don't close and reopen TUN/TAP device, re-read key files, preserve 3933 local IP address/port, or preserve most recently authenticated 3934 remote IP address/port based on --persist-tun, --persist-key, 3935 --persist-local-ip, and --persist-remote-ip options respectively 3936 (see above). 3937 3938 This signal may also be internally generated by a timeout condi‐ 4000 3939 tion, governed by the --ping-restart option. 4001 3940 4002 This signal, when combined with --persist-remote-ip, may besent4003 when the underlying parameters of the host's networkinterface4004 change such as when the host is a DHCP client and is assigned a4005 newIP address. See --ipchange above for more information.3941 This signal, when combined with --persist-remote-ip, may be sent 3942 when the underlying parameters of the host's network interface 3943 change such as when the host is a DHCP client and is assigned a new 3944 IP address. See --ipchange above for more information. 4006 3945 4007 3946 SIGUSR2 4008 Causes OpenVPN to display its current statistics (to thesyslog3947 Causes OpenVPN to display its current statistics (to the syslog 4009 3948 file if --daemon is used, or stdout otherwise). 4010 3949 … … 4013 3952 4014 3953 TUN/TAP DRIVER SETUP 4015 If you are running Linux 2.4.7 or higher, you probably have theTUN/TAP4016 driver already installed. If so, there are still a few things you need 4017 todo:3954 If you are running Linux 2.4.7 or higher, you probably have the TUN/TAP 3955 driver already installed. If so, there are still a few things you need to 3956 do: 4018 3957 4019 3958 Make device: mknod /dev/net/tun c 10 200 … … 4022 3961 4023 3962 EXAMPLES 4024 Prior to running these examples, you should have OpenVPN installed on4025 two machines with network connectivity between them. If you have not4026 yet installed OpenVPN, consult the INSTALL file included in the OpenVPN4027 distribution.3963 Prior to running these examples, you should have OpenVPN installed on two 3964 machines with network connectivity between them. If you have not yet 3965 installed OpenVPN, consult the INSTALL file included in the OpenVPN dis‐ 3966 tribution. 4028 3967 4029 3968 TUN/TAP Setup: 4030 If you areusing Linux 2.4 or higher, make the tun device node and load3969 If you are using Linux 2.4 or higher, make the tun device node and load 4031 3970 the tun module: 4032 3971 … … 4035 3974 modprobe tun 4036 3975 4037 If you installed from RPM, the mknod step may be omitted, because the4038 RPMinstall does that for you.3976 If you installed from RPM, the mknod step may be omitted, because the RPM 3977 install does that for you. 4039 3978 4040 3979 Only Linux 2.4 and newer are supported. 4041 3980 4042 For other platforms, consult the INSTALL file athttp://open‐3981 For other platforms, consult the INSTALL file at http://open‐ 4043 3982 vpn.net/install.html for more information. 4044 3983 4045 3984 Firewall Setup: 4046 If firewalls exist between the two machines, they should be set to for‐ 4047 ward UDP port 1194 in both directions. If you do not have control over 4048 the firewalls between the two machines, you may still be able to use 4049 OpenVPN by adding --ping 15 to each of the openvpn commands used below 4050 in the examples (this will cause each peer to send out a UDP ping to 4051 its remote peer once every 15 seconds which will cause many stateful 4052 firewalls to forward packets in both directions without an explicit 4053 firewall rule). 4054 4055 If you are using a Linux iptables-based firewall, you may need to enter 3985 If firewalls exist between the two machines, they should be set to forward 3986 UDP port 1194 in both directions. If you do not have control over the 3987 firewalls between the two machines, you may still be able to use OpenVPN 3988 by adding --ping 15 to each of the openvpn commands used below in the 3989 examples (this will cause each peer to send out a UDP ping to its remote 3990 peer once every 15 seconds which will cause many stateful firewalls to 3991 forward packets in both directions without an explicit firewall rule). 3992 3993 If you are using a Linux iptables-based firewall, you may need to enter 4056 3994 the following command to allow incoming packets on the TUN device: 4057 3995 4058 3996 iptables -A INPUT -i tun+ -j ACCEPT 4059 3997 4060 See the firewalls section below for more information on configuring4061 firewalls for use with OpenVPN.3998 See the firewalls section below for more information on configuring fire‐ 3999 walls for use with OpenVPN. 4062 4000 4063 4001 VPN Address Setup: 4064 For purposes of our example, our two machines will be called may.kgand4065 june.kg. If youare constructing a VPN over the internet, then replace4066 may.kg and june.kg with the internet hostname or IPaddress that each4002 For purposes of our example, our two machines will be called may.kg and 4003 june.kg. If you are constructing a VPN over the internet, then replace 4004 may.kg and june.kg with the internet hostname or IP address that each 4067 4005 machine will use to contact the other over the internet. 4068 4006 4069 Now we will choose the tunnel endpoints. Tunnel endpoints are private 4070 IP addresses that only have meaning in the context of the VPN. Each4071 machine will use the tunnel endpoint of the other machine to access it4072 over the VPN. In our example, the tunnel endpoint for may.kg will be4073 10.4.0.1 andfor june.kg, 10.4.0.2.4074 4075 Once the VPN is established, you have essentially created a secure4076 alternate path between the two hosts which is addressed by using the4077 tunnel endpoints. You can control which network traffic passes between4078 the hosts (a) over the VPN or (b) independently of the VPN, by choosing4079 whether to use (a) the VPN endpoint address or (b) the public internet4080 a ddress, to access the remote host. For example if you are on may.kg4081 and you wish to connect to june.kg via ssh without using the VPN (since4082 ssh has its own built-in security) you would use the command ssh4083 june.kg. However in the same scenario, you could also use the command4084 telnet 10.4.0.2 to create a telnet session with june.kg over the VPN,4085 th at would use the VPN to secure the session rather than ssh.4086 4087 You can useany address you wish for the tunnel endpoints but make sure4088 that they are private addresses (such as those thatbegin with 10 or4089 192.168) and that they are not part of any existing subnet on the net‐4090 works of either peer, unless you are bridging. If you use an address4091 that is part of your local subnet for either of the tunnel endpoints,4092 you will geta weird feedback loop.4007 Now we will choose the tunnel endpoints. Tunnel endpoints are private IP 4008 addresses that only have meaning in the context of the VPN. Each machine 4009 will use the tunnel endpoint of the other machine to access it over the 4010 VPN. In our example, the tunnel endpoint for may.kg will be 10.4.0.1 and 4011 for june.kg, 10.4.0.2. 4012 4013 Once the VPN is established, you have essentially created a secure alter‐ 4014 nate path between the two hosts which is addressed by using the tunnel 4015 endpoints. You can control which network traffic passes between the hosts 4016 (a) over the VPN or (b) independently of the VPN, by choosing whether to 4017 use (a) the VPN endpoint address or (b) the public internet address, to 4018 access the remote host. For example if you are on may.kg and you wish to 4019 connect to june.kg via ssh without using the VPN (since ssh has its own 4020 built-in security) you would use the command ssh june.kg. However in the 4021 same scenario, you could also use the command telnet 10.4.0.2 to create a 4022 telnet session with june.kg over the VPN, that would use the VPN to secure 4023 the session rather than ssh. 4024 4025 You can use any address you wish for the tunnel endpoints but make sure 4026 that they are private addresses (such as those that begin with 10 or 4027 192.168) and that they are not part of any existing subnet on the networks 4028 of either peer, unless you are bridging. If you use an address that is 4029 part of your local subnet for either of the tunnel endpoints, you will get 4030 a weird feedback loop. 4093 4031 4094 4032 Example 1: A simple tunnel without security 4095 4033 On may: 4096 4034 4097 openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.110.4.0.24035 openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 4098 4036 --verb 9 4099 4037 4100 4038 On june: 4101 4039 4102 openvpn --remote may.kg --devtun1 --ifconfig 10.4.0.2 10.4.0.14040 openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 4103 4041 --verb 9 4104 4042 … … 4113 4051 ping 10.4.0.1 4114 4052 4115 The --verb 9 option will produce verbose output, similar to the tcp‐ 4116 dump(8) program. Omit the --verb 9 option to have OpenVPN run quietly. 4117 4118 Example 2: A tunnel with static-key security (i.e. using a pre-shared 4119 secret) 4053 The --verb 9 option will produce verbose output, similar to the tcpdump(8) 4054 program. Omit the --verb 9 option to have OpenVPN run quietly. 4055 4056 Example 2: A tunnel with static-key security (i.e. using a pre-shared secret) 4120 4057 First build a static key on may. 4121 4058 4122 4059 openvpn --genkey --secret key 4123 4060 4124 This command willbuild a random key file called key (in ascii format).4125 Now copy key to june over a secure medium such as by using the scp(1)4126 program.4061 This command will build a random key file called key (in ascii format). 4062 Now copy key to june over a secure medium such as by using the scp(1) pro‐ 4063 gram. 4127 4064 4128 4065 On may: 4129 4066 4130 openvpn --remote june.kg--dev tun1 --ifconfig 10.4.0.1 10.4.0.24067 openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 4131 4068 --verb 5 --secret key 4132 4069 4133 4070 On june: 4134 4071 4135 openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.210.4.0.14072 openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 4136 4073 --verb 5 --secret key 4137 4074 … … 4147 4084 4148 4085 Example 3: A tunnel with full TLS-based security 4149 For this test, we will designate may as the TLS client and june as the 4150 TLS server. Note that client or server designation only has meaning 4151 for the TLS subsystem. It has no bearing on OpenVPN's peer-to-peer, 4152 UDP-based communication model. 4153 4154 First, build a separate certificate/key pair for both may and june (see 4155 above where --cert is discussed for more info). Then construct Diffie 4156 Hellman parameters (see above where --dh is discussed for more info). 4157 You can also use the included test files client.crt, client.key, 4158 server.crt, server.key and ca.crt. The .crt files are certifi‐ 4159 cates/public-keys, the .key files are private keys, and ca.crt is a 4160 certification authority who has signed both client.crt and server.crt. 4161 For Diffie Hellman parameters you can use the included file dh1024.pem. 4162 Note that all client, server, and certificate authority certificates 4163 and keys included in the OpenVPN distribution are totally insecure and 4164 should be used for testing only. 4086 For this test, we will designate may as the TLS client and june as the TLS 4087 server. Note that client or server designation only has meaning for the 4088 TLS subsystem. It has no bearing on OpenVPN's peer-to-peer, UDP-based com‐ 4089 munication model. 4090 4091 First, build a separate certificate/key pair for both may and june (see 4092 above where --cert is discussed for more info). Then construct Diffie 4093 Hellman parameters (see above where --dh is discussed for more info). You 4094 can also use the included test files client.crt, client.key, server.crt, 4095 server.key and ca.crt. The .crt files are certificates/public-keys, the 4096 .key files are private keys, and ca.crt is a certification authority who 4097 has signed both client.crt and server.crt. For Diffie Hellman parameters 4098 you can use the included file dh1024.pem. Note that all client, server, 4099 and certificate authority certificates and keys included in the OpenVPN 4100 distribution are totally insecure and should be used for testing only. 4165 4101 4166 4102 On may: 4167 4103 4168 openvpn --remote june.kg--dev tun1 --ifconfig 10.4.0.1 10.4.0.24169 --tls-client --ca ca.crt --cert client.crt --keyclient.key4104 openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 4105 --tls-client --ca ca.crt --cert client.crt --key client.key 4170 4106 --reneg-sec 60 --verb 5 4171 4107 4172 4108 On june: 4173 4109 4174 openvpn --remote may.kg --devtun1 --ifconfig 10.4.0.2 10.4.0.14175 --tls-server --dh dh1024.pem --ca ca.crt --cert server.crt--key4110 openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 4111 --tls-server --dh dh1024.pem --ca ca.crt --cert server.crt --key 4176 4112 server.key --reneg-sec 60 --verb 5 4177 4113 … … 4186 4122 ping 10.4.0.1 4187 4123 4188 Notice the --reneg-sec 60option we used above. That tells OpenVPN to4189 renegotiate the data channel keys every minute. Since we used --verb54124 Notice the --reneg-sec 60 option we used above. That tells OpenVPN to 4125 renegotiate the data channel keys every minute. Since we used --verb 5 4190 4126 above, you will see status information on each new key negotiation. 4191 4127 4192 For production operations, a key renegotiation interval of 60 seconds 4193 is probably too frequent. Omit the --reneg-sec 60 option to use Open‐4194 VPN'sdefault key renegotiation interval of one hour.4128 For production operations, a key renegotiation interval of 60 seconds is 4129 probably too frequent. Omit the --reneg-sec 60 option to use OpenVPN's 4130 default key renegotiation interval of one hour. 4195 4131 4196 4132 Routing: 4197 Assuming you can ping across the tunnel, the next step is to route a 4198 real subnet over the secure tunnel. Suppose that may and june have two 4199 network interfaces each, one connected to the internet, and the other 4200 to a private network. Our goal is to securely connect both private 4201 networks. We will assume that may's private subnet is 10.0.0.0/24 and 4202 june's is 10.0.1.0/24. 4203 4204 First, ensure that IP forwarding is enabled on both peers. On Linux, 4133 Assuming you can ping across the tunnel, the next step is to route a real 4134 subnet over the secure tunnel. Suppose that may and june have two network 4135 interfaces each, one connected to the internet, and the other to a private 4136 network. Our goal is to securely connect both private networks. We will 4137 assume that may's private subnet is 10.0.0.0/24 and june's is 10.0.1.0/24. 4138 4139 First, ensure that IP forwarding is enabled on both peers. On Linux, 4205 4140 enable routing: 4206 4141 … … 4219 4154 route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1 4220 4155 4221 Now any machine on the 10.0.0.0/24 subnet can access any machine onthe4156 Now any machine on the 10.0.0.0/24 subnet can access any machine on the 4222 4157 10.0.1.0/24 subnet over the secure tunnel (or vice versa). 4223 4158 4224 In a production environment, you could put the route command(s) ina4159 In a production environment, you could put the route command(s) in a 4225 4160 script and execute with the --up option. 4226 4161 4227 4162 FIREWALLS 4228 OpenVPN's usage of a single UDP port makes it fairlyfirewall-friendly.4229 You should add an entry to your firewall rules to allow incoming Open‐4230 VPNpackets. On Linux 2.4+:4163 OpenVPN's usage of a single UDP port makes it fairly firewall-friendly. 4164 You should add an entry to your firewall rules to allow incoming OpenVPN 4165 packets. On Linux 2.4+: 4231 4166 4232 4167 iptables -A INPUT -p udp -s 1.2.3.4 --dport 1194 -j ACCEPT 4233 4168 4234 This will allow incoming packets on UDP port 1194 (OpenVPN's default4235 UDPport) from an OpenVPN peer at 1.2.3.4.4236 4237 If you are using HMAC-based packet authentication (the default in any4238 of OpenVPN's secure modes), having the firewall filter on source4239 address can be considered optional, since HMAC packet authentication is4240 a much more secure method of verifying the authenticity of a packet4241 source. In thatcase:4169 This will allow incoming packets on UDP port 1194 (OpenVPN's default UDP 4170 port) from an OpenVPN peer at 1.2.3.4. 4171 4172 If you are using HMAC-based packet authentication (the default in any of 4173 OpenVPN's secure modes), having the firewall filter on source address can 4174 be considered optional, since HMAC packet authentication is a much more 4175 secure method of verifying the authenticity of a packet source. In that 4176 case: 4242 4177 4243 4178 iptables -A INPUT -p udp --dport 1194 -j ACCEPT 4244 4179 4245 would be adequate and would not render the host inflexible with respect 4246 toits peer having a dynamic IP address.4247 4248 OpenVPN also works well on stateful firewalls. In some cases, you may4249 n ot need to add any static rules to the firewall list if you are using4250 a stateful firewall that knows how to track UDP connections. If you4251 specify --ping n, OpenVPN will be guaranteed to send a packet to its4252 peer at least once every n seconds. If n is less than the stateful4253 firewall connection timeout, you can maintain an OpenVPN connection4254 indefinitely withoutexplicit firewall rules.4255 4256 You should also add firewall rules to allow incoming IP traffic on TUN4257 orTAP devices such as:4180 would be adequate and would not render the host inflexible with respect to 4181 its peer having a dynamic IP address. 4182 4183 OpenVPN also works well on stateful firewalls. In some cases, you may not 4184 need to add any static rules to the firewall list if you are using a 4185 stateful firewall that knows how to track UDP connections. If you specify 4186 --ping n, OpenVPN will be guaranteed to send a packet to its peer at least 4187 once every n seconds. If n is less than the stateful firewall connection 4188 timeout, you can maintain an OpenVPN connection indefinitely without 4189 explicit firewall rules. 4190 4191 You should also add firewall rules to allow incoming IP traffic on TUN or 4192 TAP devices such as: 4258 4193 4259 4194 iptables -A INPUT -i tun+ -j ACCEPT … … 4263 4198 iptables -A FORWARD -i tun+ -j ACCEPT 4264 4199 4265 to allow input packets from tun devices to be forwarded to other hosts4266 onthe local network,4200 to allow input packets from tun devices to be forwarded to other hosts on 4201 the local network, 4267 4202 4268 4203 iptables -A INPUT -i tap+ -j ACCEPT … … 4272 4207 iptables -A FORWARD -i tap+ -j ACCEPT 4273 4208 4274 to allow input packets from tap devices to be forwarded to other hosts4275 onthe local network.4276 4277 These rules are secure if you use packet authentication, since no4278 incoming packets will arrive on a TUN or TAP virtual device unless they4279 first passan HMAC authentication test.4209 to allow input packets from tap devices to be forwarded to other hosts on 4210 the local network. 4211 4212 These rules are secure if you use packet authentication, since no incoming 4213 packets will arrive on a TUN or TAP virtual device unless they first pass 4214 an HMAC authentication test. 4280 4215 4281 4216 FAQ … … 4283 4218 4284 4219 HOWTO 4285 For a more comprehensive guide to setting up OpenVPN in a production4286 setting, see the OpenVPN HOWTO at http://openvpn.net/howto.html4220 For a more comprehensive guide to setting up OpenVPN in a production set‐ 4221 ting, see the OpenVPN HOWTO at http://openvpn.net/howto.html 4287 4222 4288 4223 PROTOCOL 4289 For a description of OpenVPN's underlying protocol, seehttp://open‐4224 For a description of OpenVPN's underlying protocol, see http://open‐ 4290 4225 vpn.net/security.html 4291 4226 … … 4293 4228 OpenVPN's web site is at http://openvpn.net/ 4294 4229 4295 Go here to download the latest version of OpenVPN, subscribe to the 4296 mailing lists, read the mailing list archives, or browse the SVN repos‐ 4297 itory. 4230 Go here to download the latest version of OpenVPN, subscribe to the mail‐ 4231 ing lists, read the mailing list archives, or browse the SVN repository. 4298 4232 4299 4233 BUGS … … 4304 4238 4305 4239 NOTES 4306 This product includessoftware developed by the OpenSSL Project (4240 This product includes software developed by the OpenSSL Project ( 4307 4241 http://www.openssl.org/ ) 4308 4242 4309 For more information on the TLS protocol,see4243 For more information on the TLS protocol, see 4310 4244 http://www.ietf.org/rfc/rfc2246.txt 4311 4245 4312 For more informationon the LZO real-time compression library see4246 For more information on the LZO real-time compression library see 4313 4247 http://www.oberhumer.com/opensource/lzo/ 4314 4248 4315 4249 COPYRIGHT 4316 Copyright (C) 2002-2010OpenVPN Technologies, Inc. This program is free4317 software; you can redistribute it and/or modify it under the terms of4318 the GNU General Public License version 2 as published by the Free Soft‐4319 wareFoundation.4250 Copyright (C) 2002-2010 OpenVPN Technologies, Inc. This program is free 4251 software; you can redistribute it and/or modify it under the terms of the 4252 GNU General Public License version 2 as published by the Free Software 4253 Foundation. 4320 4254 4321 4255 AUTHORS … … 4324 4258 4325 4259 4326 17 November 2008openvpn(8)4260 17 November 2008 openvpn(8) 4327 4261 }}} 4328 4262 }}}