]>
Commit | Line | Data |
---|---|---|
f500c49c DS |
1 | Server Options |
2 | -------------- | |
3 | Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is | |
4 | supported, and can be enabled with the ``--mode server`` option. In | |
5 | server mode, OpenVPN will listen on a single port for incoming client | |
6 | connections. All client connections will be routed through a single tun | |
7 | or tap interface. This mode is designed for scalability and should be | |
8 | able to support hundreds or even thousands of clients on sufficiently | |
9 | fast hardware. SSL/TLS authentication must be used in this mode. | |
10 | ||
11 | --auth-gen-token args | |
12 | Returns an authentication token to successfully authenticated clients. | |
13 | ||
14 | Valid syntax: | |
15 | :: | |
16 | ||
9a516170 | 17 | auth-gen-token [lifetime] [renewal-time] [external-auth] |
f500c49c DS |
18 | |
19 | After successful user/password authentication, the OpenVPN server will | |
20 | with this option generate a temporary authentication token and push that | |
21 | to the client. On the following renegotiations, the OpenVPN client will pass | |
22 | this token instead of the users password. On the server side the server | |
23 | will do the token authentication internally and it will NOT do any | |
24 | additional authentications against configured external user/password | |
25 | authentication mechanisms. | |
26 | ||
27 | The tokens implemented by this mechanism include an initial timestamp and | |
28 | a renew timestamp and are secured by HMAC. | |
29 | ||
30 | The ``lifetime`` argument defines how long the generated token is valid. | |
31 | The lifetime is defined in seconds. If lifetime is not set or it is set | |
32 | to :code:`0`, the token will never expire. | |
33 | ||
9a516170 AS |
34 | If ``renewal-time`` is not set it defaults to ``reneg-sec``. |
35 | ||
36 | ||
f500c49c DS |
37 | The token will expire either after the configured ``lifetime`` of the |
38 | token is reached or after not being renewed for more than 2 \* | |
9a516170 AS |
39 | ``renewal-time`` seconds. Clients will be sent renewed tokens on every TLS |
40 | renegotiation. If ``renewal-time`` is lower than ``reneg-sec`` the server | |
41 | will push an updated temporary authentication token every ``reneweal-time`` | |
42 | seconds. This is done to invalidate a token if a client is disconnected for a | |
43 | sufficiently long time, while at the same time permitting much longer token | |
44 | lifetimes for active clients. | |
f500c49c DS |
45 | |
46 | This feature is useful for environments which are configured to use One | |
47 | Time Passwords (OTP) as part of the user/password authentications and | |
48 | that authentication mechanism does not implement any auth-token support. | |
49 | ||
50 | When the :code:`external-auth` keyword is present the normal | |
51 | authentication method will always be called even if auth-token succeeds. | |
52 | Normally other authentications method are skipped if auth-token | |
d75e0736 | 53 | verification succeeds or fails. |
f500c49c DS |
54 | |
55 | This option postpones this decision to the external authentication | |
56 | methods and checks the validity of the account and do other checks. | |
57 | ||
58 | In this mode the environment will have a ``session_id`` variable that | |
59 | holds the session id from auth-gen-token. Also an environment variable | |
60 | ``session_state`` is present. This variable indicates whether the | |
61 | auth-token has succeeded or not. It can have the following values: | |
62 | ||
63 | :code:`Initial` | |
64 | No token from client. | |
65 | ||
66 | :code:`Authenticated` | |
67 | Token is valid and not expired. | |
68 | ||
69 | :code:`Expired` | |
70 | Token is valid but has expired. | |
71 | ||
72 | :code:`Invalid` | |
73 | Token is invalid (failed HMAC or wrong length) | |
74 | ||
75 | :code:`AuthenticatedEmptyUser` / :code:`ExpiredEmptyUser` | |
76 | The token is not valid with the username sent from the client but | |
77 | would be valid (or expired) if we assume an empty username was | |
78 | used instead. These two cases are a workaround for behaviour in | |
79 | OpenVPN 3. If this workaround is not needed these two cases should | |
80 | be handled in the same way as :code:`Invalid`. | |
81 | ||
82 | **Warning:** Use this feature only if you want your authentication | |
83 | method called on every verification. Since the external authentication | |
84 | is called it needs to also indicate a success or failure of the | |
85 | authentication. It is strongly recommended to return an authentication | |
86 | failure in the case of the Invalid/Expired auth-token with the | |
87 | external-auth option unless the client could authenticate in another | |
88 | acceptable way (e.g. client certificate), otherwise returning success | |
89 | will lead to authentication bypass (as does returning success on a wrong | |
90 | password from a script). | |
91 | ||
92 | --auth-gen-token-secret file | |
93 | Specifies a file that holds a secret for the HMAC used in | |
94 | ``--auth-gen-token`` If ``file`` is not present OpenVPN will generate a | |
95 | random secret on startup. This file should be used if auth-token should | |
96 | validate after restarting a server or if client should be able to roam | |
97 | between multiple OpenVPN servers with their auth-token. | |
98 | ||
99 | --auth-user-pass-optional | |
100 | Allow connections by clients that do not specify a username/password. | |
101 | Normally, when ``--auth-user-pass-verify`` or | |
102 | ``--management-client-auth`` are specified (or an authentication plugin | |
103 | module), the OpenVPN server daemon will require connecting clients to | |
104 | specify a username and password. This option makes the submission of a | |
105 | username/password by clients optional, passing the responsibility to the | |
106 | user-defined authentication module/script to accept or deny the client | |
107 | based on other factors (such as the setting of X509 certificate fields). | |
108 | When this option is used, and a connecting client does not submit a | |
109 | username/password, the user-defined authentication module/script will | |
110 | see the username and password as being set to empty strings (""). The | |
111 | authentication module/script MUST have logic to detect this condition | |
112 | and respond accordingly. | |
113 | ||
114 | --ccd-exclusive | |
115 | Require, as a condition of authentication, that a connecting client has | |
116 | a ``--client-config-dir`` file. | |
117 | ||
118 | --client-config-dir dir | |
119 | Specify a directory ``dir`` for custom client config files. After a | |
120 | connecting client has been authenticated, OpenVPN will look in this | |
121 | directory for a file having the same name as the client's X509 common | |
122 | name. If a matching file exists, it will be opened and parsed for | |
123 | client-specific configuration options. If no matching file is found, | |
124 | OpenVPN will instead try to open and parse a default file called | |
125 | "DEFAULT", which may be provided but is not required. Note that the | |
126 | configuration files must be readable by the OpenVPN process after it has | |
127 | dropped it's root privileges. | |
128 | ||
129 | This file can specify a fixed IP address for a given client using | |
130 | ``--ifconfig-push``, as well as fixed subnets owned by the client using | |
131 | ``--iroute``. | |
132 | ||
133 | One of the useful properties of this option is that it allows client | |
134 | configuration files to be conveniently created, edited, or removed while | |
135 | the server is live, without needing to restart the server. | |
136 | ||
137 | The following options are legal in a client-specific context: ``--push``, | |
138 | ``--push-reset``, ``--push-remove``, ``--iroute``, ``--ifconfig-push``, | |
139 | ``--vlan-pvid`` and ``--config``. | |
140 | ||
141 | --client-to-client | |
142 | Because the OpenVPN server mode handles multiple clients through a | |
143 | single tun or tap interface, it is effectively a router. The | |
144 | ``--client-to-client`` flag tells OpenVPN to internally route | |
145 | client-to-client traffic rather than pushing all client-originating | |
146 | traffic to the TUN/TAP interface. | |
147 | ||
148 | When this option is used, each client will "see" the other clients which | |
149 | are currently connected. Otherwise, each client will only see the | |
150 | server. Don't use this option if you want to firewall tunnel traffic | |
151 | using custom, per-client rules. | |
152 | ||
7a4c7592 AQ |
153 | Please note that when using data channel offload this option has no |
154 | effect. Packets are always sent to the tunnel interface and then | |
155 | routed based on the system routing table. | |
156 | ||
f500c49c DS |
157 | --disable |
158 | Disable a particular client (based on the common name) from connecting. | |
159 | Don't use this option to disable a client due to key or password | |
160 | compromise. Use a CRL (certificate revocation list) instead (see the | |
161 | ``--crl-verify`` option). | |
162 | ||
163 | This option must be associated with a specific client instance, which | |
164 | means that it must be specified either in a client instance config file | |
165 | using ``--client-config-dir`` or dynamically generated using a | |
166 | ``--client-connect`` script. | |
167 | ||
168 | --connect-freq args | |
169 | Allow a maximum of ``n`` new connections per ``sec`` seconds from | |
170 | clients. | |
171 | ||
172 | Valid syntax: | |
173 | :: | |
174 | ||
175 | connect-freq n sec | |
176 | ||
177 | This is designed to contain DoS attacks which flood the server | |
178 | with connection requests using certificates which will ultimately fail | |
179 | to authenticate. | |
180 | ||
b520c68c AS |
181 | This limit applies after ``--connect-freq-initial`` and |
182 | only applies to client that have completed the three-way handshake | |
183 | or client that use ``--tls-crypt-v2`` without cookie support | |
184 | (``allow-noncookie`` argument to ``--tls-crypt-v2``). | |
185 | ||
f500c49c DS |
186 | This is an imperfect solution however, because in a real DoS scenario, |
187 | legitimate connections might also be refused. | |
188 | ||
189 | For the best protection against DoS attacks in server mode, use | |
190 | ``--proto udp`` and either ``--tls-auth`` or ``--tls-crypt``. | |
191 | ||
b520c68c AS |
192 | --connect-freq-initial args |
193 | (UDP only) Allow a maximum of ``n`` initial connection packet responses | |
194 | per ``sec`` seconds from the OpenVPN server to clients. | |
195 | ||
196 | Valid syntax: | |
197 | :: | |
198 | ||
199 | connect-freq-initial n sec | |
200 | ||
201 | OpenVPN starting at 2.6 is very efficient in responding to initial | |
202 | connection packets. When not limiting the initial responses | |
203 | an OpenVPN daemon can be abused in reflection attacks. | |
204 | This option is designed to limit the rate OpenVPN will respond to initial | |
205 | attacks. | |
206 | ||
207 | Connection attempts that complete the initial three-way handshake | |
208 | will not be counted against the limit. The default is to allow | |
209 | 100 initial connection per 10s. | |
210 | ||
f500c49c DS |
211 | --duplicate-cn |
212 | Allow multiple clients with the same common name to concurrently | |
213 | connect. In the absence of this option, OpenVPN will disconnect a client | |
214 | instance upon connection of a new client having the same common name. | |
215 | ||
216 | --ifconfig-pool args | |
217 | Set aside a pool of subnets to be dynamically allocated to connecting | |
218 | clients, similar to a DHCP server. | |
219 | ||
220 | Valid syntax: | |
221 | :: | |
222 | ||
223 | ifconfig-pool start-IP end-IP [netmask] | |
224 | ||
225 | For tun-style tunnels, each client | |
226 | will be given a /30 subnet (for interoperability with Windows clients). | |
227 | For tap-style tunnels, individual addresses will be allocated, and the | |
228 | optional ``netmask`` parameter will also be pushed to clients. | |
229 | ||
230 | --ifconfig-ipv6-pool args | |
231 | Specify an IPv6 address pool for dynamic assignment to clients. | |
232 | ||
233 | Valid args: | |
234 | :: | |
235 | ||
236 | ifconfig-ipv6-pool ipv6addr/bits | |
237 | ||
238 | The pool starts at ``ipv6addr`` and matches the offset determined from | |
4dff2368 GD |
239 | the start of the IPv4 pool. If the host part of the given IPv6 |
240 | address is ``0``, the pool starts at ``ipv6addr`` +1. | |
f500c49c DS |
241 | |
242 | --ifconfig-pool-persist args | |
243 | Persist/unpersist ifconfig-pool data to ``file``, at ``seconds`` | |
244 | intervals (default :code:`600`), as well as on program startup and shutdown. | |
245 | ||
246 | Valid syntax: | |
247 | :: | |
248 | ||
249 | ifconfig-pool-persist file [seconds] | |
250 | ||
251 | The goal of this option is to provide a long-term association between | |
252 | clients (denoted by their common name) and the virtual IP address | |
253 | assigned to them from the ifconfig-pool. Maintaining a long-term | |
254 | association is good for clients because it allows them to effectively | |
255 | use the ``--persist-tun`` option. | |
256 | ||
257 | ``file`` is a comma-delimited ASCII file, formatted as | |
258 | :code:`<Common-Name>,<IP-address>`. | |
259 | ||
260 | If ``seconds`` = :code:`0`, ``file`` will be treated as read-only. This | |
261 | is useful if you would like to treat ``file`` as a configuration file. | |
262 | ||
263 | Note that the entries in this file are treated by OpenVPN as | |
264 | *suggestions* only, based on past associations between a common name and | |
265 | IP address. They do not guarantee that the given common name will always | |
266 | receive the given IP address. If you want guaranteed assignment, use | |
267 | ``--ifconfig-push`` | |
268 | ||
269 | --ifconfig-push args | |
270 | Push virtual IP endpoints for client tunnel, overriding the | |
271 | ``--ifconfig-pool`` dynamic allocation. | |
272 | ||
273 | Valid syntax: | |
274 | :: | |
275 | ||
276 | ifconfig-push local remote-netmask [alias] | |
277 | ||
278 | The parameters ``local`` and ``remote-netmask`` are set according to the | |
279 | ``--ifconfig`` directive which you want to execute on the client machine | |
280 | to configure the remote end of the tunnel. Note that the parameters | |
281 | ``local`` and ``remote-netmask`` are from the perspective of the client, | |
282 | not the server. They may be DNS names rather than IP addresses, in which | |
283 | case they will be resolved on the server at the time of client | |
284 | connection. | |
285 | ||
286 | The optional ``alias`` parameter may be used in cases where NAT causes | |
287 | the client view of its local endpoint to differ from the server view. In | |
288 | this case ``local/remote-netmask`` will refer to the server view while | |
289 | ``alias/remote-netmask`` will refer to the client view. | |
290 | ||
291 | This option must be associated with a specific client instance, which | |
292 | means that it must be specified either in a client instance config file | |
293 | using ``--client-config-dir`` or dynamically generated using a | |
294 | ``--client-connect`` script. | |
295 | ||
296 | Remember also to include a ``--route`` directive in the main OpenVPN | |
297 | config file which encloses ``local``, so that the kernel will know to | |
298 | route it to the server's TUN/TAP interface. | |
299 | ||
300 | OpenVPN's internal client IP address selection algorithm works as | |
301 | follows: | |
302 | ||
303 | 1. Use ``--client-connect script`` generated file for static IP | |
304 | (first choice). | |
305 | ||
306 | 2. Use ``--client-config-dir`` file for static IP (next choice). | |
307 | ||
308 | 3. Use ``--ifconfig-pool`` allocation for dynamic IP (last | |
309 | choice). | |
310 | ||
311 | --ifconfig-ipv6-push args | |
312 | for ``--client-config-dir`` per-client static IPv6 interface | |
313 | configuration, see ``--client-config-dir`` and ``--ifconfig-push`` for | |
314 | more details. | |
315 | ||
316 | Valid syntax: | |
317 | :: | |
318 | ||
319 | ifconfig-ipv6-push ipv6addr/bits ipv6remote | |
320 | ||
f500c49c DS |
321 | --multihome |
322 | Configure a multi-homed UDP server. This option needs to be used when a | |
323 | server has more than one IP address (e.g. multiple interfaces, or | |
324 | secondary IP addresses), and is not using ``--local`` to force binding | |
325 | to one specific address only. This option will add some extra lookups to | |
326 | the packet path to ensure that the UDP reply packets are always sent | |
327 | from the address that the client is talking to. This is not supported on | |
328 | all platforms, and it adds more processing, so it's not enabled by | |
329 | default. | |
330 | ||
331 | *Notes:* | |
332 | - This option is only relevant for UDP servers. | |
333 | - If you do an IPv6+IPv4 dual-stack bind on a Linux machine with | |
334 | multiple IPv4 address, connections to IPv4 addresses will not | |
335 | work right on kernels before 3.15, due to missing kernel | |
336 | support for the IPv4-mapped case (some distributions have | |
337 | ported this to earlier kernel versions, though). | |
338 | ||
339 | --iroute args | |
340 | Generate an internal route to a specific client. The ``netmask`` | |
341 | parameter, if omitted, defaults to :code:`255.255.255.255`. | |
342 | ||
343 | Valid syntax: | |
344 | :: | |
345 | ||
346 | iroute network [netmask] | |
347 | ||
348 | This directive can be used to route a fixed subnet from the server to a | |
349 | particular client, regardless of where the client is connecting from. | |
350 | Remember that you must also add the route to the system routing table as | |
351 | well (such as by using the ``--route`` directive). The reason why two | |
352 | routes are needed is that the ``--route`` directive routes the packet | |
353 | from the kernel to OpenVPN. Once in OpenVPN, the ``--iroute`` directive | |
354 | routes to the specific client. | |
355 | ||
fba724e3 AQ |
356 | However, when using DCO, the ``--iroute`` directive is usually enough |
357 | for DCO to fully configure the routing table. The extra ``--route`` | |
358 | directive is required only if the expected behaviour is to route the | |
359 | traffic for a specific network to the VPN interface also when the | |
360 | responsible client is not connected (traffic will then be dropped). | |
361 | ||
f500c49c DS |
362 | This option must be specified either in a client instance config file |
363 | using ``--client-config-dir`` or dynamically generated using a | |
364 | ``--client-connect`` script. | |
365 | ||
366 | The ``--iroute`` directive also has an important interaction with | |
367 | ``--push "route ..."``. ``--iroute`` essentially defines a subnet which | |
368 | is owned by a particular client (we will call this client *A*). If you | |
369 | would like other clients to be able to reach *A*'s subnet, you can use | |
370 | ``--push "route ..."`` together with ``--client-to-client`` to effect | |
371 | this. In order for all clients to see *A*'s subnet, OpenVPN must push | |
372 | this route to all clients EXCEPT for *A*, since the subnet is already | |
373 | owned by *A*. OpenVPN accomplishes this by not not pushing a route to | |
374 | a client if it matches one of the client's iroutes. | |
375 | ||
376 | --iroute-ipv6 args | |
377 | for ``--client-config-dir`` per-client static IPv6 route configuration, | |
378 | see ``--iroute`` for more details how to setup and use this, and how | |
379 | ``--iroute`` and ``--route`` interact. | |
380 | ||
381 | Valid syntax: | |
382 | :: | |
383 | ||
384 | iroute-ipv6 ipv6addr/bits | |
385 | ||
386 | --max-clients n | |
387 | Limit server to a maximum of ``n`` concurrent clients. | |
388 | ||
389 | --max-routes-per-client n | |
390 | Allow a maximum of ``n`` internal routes per client (default | |
391 | :code:`256`). This is designed to help contain DoS attacks where an | |
392 | authenticated client floods the server with packets appearing to come | |
393 | from many unique MAC addresses, forcing the server to deplete virtual | |
394 | memory as its internal routing table expands. This directive can be used | |
395 | in a ``--client-config-dir`` file or auto-generated by a | |
396 | ``--client-connect`` script to override the global value for a particular | |
397 | client. | |
398 | ||
399 | Note that this directive affects OpenVPN's internal routing table, not | |
400 | the kernel routing table. | |
401 | ||
402 | --opt-verify | |
2104ea62 AS |
403 | **DEPRECATED** Clients that connect with options that are incompatible with |
404 | those of the server will be disconnected. | |
f500c49c DS |
405 | |
406 | Options that will be compared for compatibility include ``dev-type``, | |
407 | ``link-mtu``, ``tun-mtu``, ``proto``, ``ifconfig``, | |
408 | ``comp-lzo``, ``fragment``, ``keydir``, ``cipher``, | |
392da5bd | 409 | ``auth``, ``keysize``, |
4b4b34da | 410 | ``tls-auth``, ``key-method``, ``tls-server`` |
f500c49c DS |
411 | and ``tls-client``. |
412 | ||
413 | This option requires that ``--disable-occ`` NOT be used. | |
414 | ||
415 | --port-share args | |
416 | Share OpenVPN TCP with another service | |
417 | ||
418 | Valid syntax: | |
419 | :: | |
420 | ||
421 | port-share host port [dir] | |
422 | ||
423 | When run in TCP server mode, share the OpenVPN port with another | |
424 | application, such as an HTTPS server. If OpenVPN senses a connection to | |
425 | its port which is using a non-OpenVPN protocol, it will proxy the | |
426 | connection to the server at ``host``:``port``. Currently only designed to | |
427 | work with HTTP/HTTPS, though it would be theoretically possible to | |
428 | extend to other protocols such as ssh. | |
429 | ||
430 | ``dir`` specifies an optional directory where a temporary file with name | |
431 | N containing content C will be dynamically generated for each proxy | |
432 | connection, where N is the source IP:port of the client connection and C | |
433 | is the source IP:port of the connection to the proxy receiver. This | |
434 | directory can be used as a dictionary by the proxy receiver to determine | |
435 | the origin of the connection. Each generated file will be automatically | |
436 | deleted when the proxied connection is torn down. | |
437 | ||
438 | Not implemented on Windows. | |
439 | ||
440 | --push option | |
441 | Push a config file option back to the client for remote execution. Note | |
442 | that ``option`` must be enclosed in double quotes (:code:`""`). The | |
443 | client must specify ``--pull`` in its config file. The set of options | |
444 | which can be pushed is limited by both feasibility and security. Some | |
445 | options such as those which would execute scripts are banned, since they | |
446 | would effectively allow a compromised server to execute arbitrary code | |
447 | on the client. Other options such as TLS or MTU parameters cannot be | |
448 | pushed because the client needs to know them before the connection to the | |
449 | server can be initiated. | |
450 | ||
451 | This is a partial list of options which can currently be pushed: | |
452 | ``--route``, ``--route-gateway``, ``--route-delay``, | |
b3e0d95d | 453 | ``--redirect-gateway``, ``--ip-win32``, ``--dhcp-option``, ``--dns``, |
f500c49c | 454 | ``--inactive``, ``--ping``, ``--ping-exit``, ``--ping-restart``, |
802fcce5 | 455 | ``--setenv``, ``--auth-token``, ``--persist-tun``, |
f500c49c | 456 | ``--echo``, ``--comp-lzo``, ``--socket-flags``, ``--sndbuf``, |
f96290ff | 457 | ``--rcvbuf``, ``--session-timeout`` |
f500c49c | 458 | |
f500c49c DS |
459 | --push-remove opt |
460 | Selectively remove all ``--push`` options matching "opt" from the option | |
461 | list for a client. ``opt`` is matched as a substring against the whole | |
462 | option string to-be-pushed to the client, so ``--push-remove route`` | |
463 | would remove all ``--push route ...`` and ``--push route-ipv6 ...`` | |
464 | statements, while ``--push-remove "route-ipv6 2001:"`` would only remove | |
465 | IPv6 routes for :code:`2001:...` networks. | |
466 | ||
467 | ``--push-remove`` can only be used in a client-specific context, like in | |
468 | a ``--client-config-dir`` file, or ``--client-connect`` script or plugin | |
469 | -- similar to ``--push-reset``, just more selective. | |
470 | ||
471 | *NOTE*: to *change* an option, ``--push-remove`` can be used to first | |
472 | remove the old value, and then add a new ``--push`` option with the new | |
473 | value. | |
474 | ||
475 | *NOTE 2*: due to implementation details, 'ifconfig' and 'ifconfig-ipv6' | |
476 | can only be removed with an exact match on the option ( | |
477 | :code:`push-remove ifconfig`), no substring matching and no matching on | |
478 | the IPv4/IPv6 address argument is possible. | |
479 | ||
480 | --push-reset | |
481 | Don't inherit the global push list for a specific client instance. | |
482 | Specify this option in a client-specific context such as with a | |
483 | ``--client-config-dir`` configuration file. This option will ignore | |
484 | ``--push`` options at the global config file level. | |
485 | ||
5fd66510 GD |
486 | *NOTE*: ``--push-reset`` is very thorough: it will remove almost |
487 | all options from the list of to-be-pushed options. In many cases, | |
488 | some of these options will need to be re-configured afterwards - | |
489 | specifically, ``--topology subnet`` and ``--route-gateway`` will get | |
490 | lost and this will break client configs in many cases. Thus, for most | |
491 | purposes, ``--push-remove`` is better suited to selectively remove | |
492 | push options for individual clients. | |
493 | ||
f500c49c DS |
494 | --server args |
495 | A helper directive designed to simplify the configuration of OpenVPN's | |
496 | server mode. This directive will set up an OpenVPN server which will | |
497 | allocate addresses to clients out of the given network/netmask. The | |
498 | server itself will take the :code:`.1` address of the given network for | |
499 | use as the server-side endpoint of the local TUN/TAP interface. If the | |
500 | optional :code:`nopool` flag is given, no dynamic IP address pool will | |
501 | prepared for VPN clients. | |
502 | ||
503 | Valid syntax: | |
504 | :: | |
505 | ||
506 | server network netmask [nopool] | |
507 | ||
508 | For example, ``--server 10.8.0.0 255.255.255.0`` expands as follows: | |
509 | :: | |
510 | ||
511 | mode server | |
512 | tls-server | |
513 | push "topology [topology]" | |
514 | ||
515 | if dev tun AND (topology == net30 OR topology == p2p): | |
516 | ifconfig 10.8.0.1 10.8.0.2 | |
517 | if !nopool: | |
518 | ifconfig-pool 10.8.0.4 10.8.0.251 | |
519 | route 10.8.0.0 255.255.255.0 | |
520 | if client-to-client: | |
521 | push "route 10.8.0.0 255.255.255.0" | |
522 | else if topology == net30: | |
523 | push "route 10.8.0.1" | |
524 | ||
525 | if dev tap OR (dev tun AND topology == subnet): | |
526 | ifconfig 10.8.0.1 255.255.255.0 | |
527 | if !nopool: | |
528 | ifconfig-pool 10.8.0.2 10.8.0.253 255.255.255.0 | |
529 | push "route-gateway 10.8.0.1" | |
530 | if route-gateway unset: | |
531 | route-gateway 10.8.0.2 | |
532 | ||
533 | Don't use ``--server`` if you are ethernet bridging. Use | |
534 | ``--server-bridge`` instead. | |
535 | ||
536 | --server-bridge args | |
537 | A helper directive similar to ``--server`` which is designed to simplify | |
538 | the configuration of OpenVPN's server mode in ethernet bridging | |
539 | configurations. | |
540 | ||
541 | Valid syntaxes: | |
542 | :: | |
543 | ||
544 | server-bridge gateway netmask pool-start-IP pool-end-IP | |
545 | server-bridge [nogw] | |
546 | ||
547 | If ``--server-bridge`` is used without any parameters, it will enable a | |
548 | DHCP-proxy mode, where connecting OpenVPN clients will receive an IP | |
549 | address for their TAP adapter from the DHCP server running on the | |
550 | OpenVPN server-side LAN. Note that only clients that support the binding | |
551 | of a DHCP client with the TAP adapter (such as Windows) can support this | |
552 | mode. The optional :code:`nogw` flag (advanced) indicates that gateway | |
553 | information should not be pushed to the client. | |
554 | ||
555 | To configure ethernet bridging, you must first use your OS's bridging | |
556 | capability to bridge the TAP interface with the ethernet NIC interface. | |
557 | For example, on Linux this is done with the :code:`brctl` tool, and with | |
558 | Windows XP it is done in the Network Connections Panel by selecting the | |
559 | ethernet and TAP adapters and right-clicking on "Bridge Connections". | |
560 | ||
561 | Next you you must manually set the IP/netmask on the bridge interface. | |
562 | The ``gateway`` and ``netmask`` parameters to ``--server-bridge`` can be | |
563 | set to either the IP/netmask of the bridge interface, or the IP/netmask | |
564 | of the default gateway/router on the bridged subnet. | |
565 | ||
566 | Finally, set aside a IP range in the bridged subnet, denoted by | |
567 | ``pool-start-IP`` and ``pool-end-IP``, for OpenVPN to allocate to | |
568 | connecting clients. | |
569 | ||
570 | For example, ``server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 | |
571 | 10.8.0.254`` expands as follows: | |
572 | :: | |
573 | ||
574 | mode server | |
575 | tls-server | |
576 | ||
577 | ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0 | |
578 | push "route-gateway 10.8.0.4" | |
579 | ||
580 | In another example, ``--server-bridge`` (without parameters) expands as | |
581 | follows: | |
582 | :: | |
583 | ||
584 | mode server | |
585 | tls-server | |
586 | ||
587 | push "route-gateway dhcp" | |
588 | ||
589 | Or ``--server-bridge nogw`` expands as follows: | |
590 | :: | |
591 | ||
592 | mode server | |
593 | tls-server | |
594 | ||
8120e1ad DS |
595 | --server-ipv6 args |
596 | Convenience-function to enable a number of IPv6 related options at once, | |
597 | namely ``--ifconfig-ipv6``, ``--ifconfig-ipv6-pool`` and | |
598 | ``--push tun-ipv6``. | |
599 | ||
600 | Valid syntax: | |
601 | :: | |
602 | ||
603 | server-ipv6 ipv6addr/bits | |
604 | ||
605 | Pushing of the ``--tun-ipv6`` directive is done for older clients which | |
606 | require an explicit ``--tun-ipv6`` in their configuration. | |
607 | ||
f500c49c DS |
608 | --stale-routes-check args |
609 | Remove routes which haven't had activity for ``n`` seconds (i.e. the ageing | |
610 | time). This check is run every ``t`` seconds (i.e. check interval). | |
611 | ||
612 | Valid syntax: | |
613 | :: | |
614 | ||
615 | stale-routes-check n [t] | |
616 | ||
617 | If ``t`` is not present it defaults to ``n``. | |
618 | ||
619 | This option helps to keep the dynamic routing table small. See also | |
620 | ``--max-routes-per-client`` | |
621 | ||
622 | --username-as-common-name | |
66ad8727 SN |
623 | Use the authenticated username as the common-name, rather than the |
624 | common-name from the client certificate. Requires that some form of | |
625 | ``--auth-user-pass`` verification is in effect. As the replacement happens | |
626 | after ``--auth-user-pass`` verification, the verification script or | |
627 | plugin will still receive the common-name from the certificate. | |
628 | ||
629 | The common_name environment variable passed to scripts and plugins invoked | |
630 | after authentication (e.g, client-connect script) and file names parsed in | |
631 | client-config directory will match the username. | |
f500c49c DS |
632 | |
633 | --verify-client-cert mode | |
634 | Specify whether the client is required to supply a valid certificate. | |
635 | ||
636 | Possible ``mode`` options are: | |
637 | ||
638 | :code:`none` | |
639 | A client certificate is not required. the client needs to | |
640 | authenticate using username/password only. Be aware that using this | |
641 | directive is less secure than requiring certificates from all | |
642 | clients. | |
643 | ||
644 | If you use this directive, the entire responsibility of authentication | |
645 | will rest on your ``--auth-user-pass-verify`` script, so keep in mind | |
646 | that bugs in your script could potentially compromise the security of | |
647 | your VPN. | |
648 | ||
649 | ``--verify-client-cert none`` is functionally equivalent to | |
650 | ``--client-cert-not-required``. | |
651 | ||
652 | :code:`optional` | |
653 | A client may present a certificate but it is not required to do so. | |
654 | When using this directive, you should also use a | |
655 | ``--auth-user-pass-verify`` script to ensure that clients are | |
656 | authenticated using a certificate, a username and password, or | |
657 | possibly even both. | |
658 | ||
659 | Again, the entire responsibility of authentication will rest on your | |
660 | ``--auth-user-pass-verify`` script, so keep in mind that bugs in your | |
661 | script could potentially compromise the security of your VPN. | |
662 | ||
663 | :code:`require` | |
664 | This is the default option. A client is required to present a | |
665 | certificate, otherwise VPN access is refused. | |
666 | ||
667 | If you don't use this directive (or use ``--verify-client-cert require``) | |
668 | but you also specify an ``--auth-user-pass-verify`` script, then OpenVPN | |
669 | will perform double authentication. The client certificate verification | |
670 | AND the ``--auth-user-pass-verify`` script will need to succeed in order | |
671 | for a client to be authenticated and accepted onto the VPN. | |
672 | ||
673 | --vlan-tagging | |
674 | Server-only option. Turns the OpenVPN server instance into a switch that | |
675 | understands VLAN-tagging, based on IEEE 802.1Q. | |
676 | ||
677 | The server TAP device and each of the connecting clients is seen as a | |
678 | port of the switch. All client ports are in untagged mode and the server | |
679 | TAP device is VLAN-tagged, untagged or accepts both, depending on the | |
680 | ``--vlan-accept`` setting. | |
681 | ||
682 | Ethernet frames with a prepended 802.1Q tag are called "tagged". If the | |
683 | VLAN Identifier (VID) field in such a tag is non-zero, the frame is | |
684 | called "VLAN-tagged". If the VID is zero, but the Priority Control Point | |
685 | (PCP) field is non-zero, the frame is called "prio-tagged". If there is | |
686 | no 802.1Q tag, the frame is "untagged". | |
687 | ||
688 | Using the ``--vlan-pvid v`` option once per client (see | |
689 | --client-config-dir), each port can be associated with a certain VID. | |
690 | Packets can only be forwarded between ports having the same VID. | |
691 | Therefore, clients with differing VIDs are completely separated from | |
692 | one-another, even if ``--client-to-client`` is activated. | |
693 | ||
694 | The packet filtering takes place in the OpenVPN server. Clients should | |
695 | not have any VLAN tagging configuration applied. | |
696 | ||
697 | The ``--vlan-tagging`` option is off by default. While turned off, | |
698 | OpenVPN accepts any Ethernet frame and does not perform any special | |
699 | processing for VLAN-tagged packets. | |
700 | ||
701 | This option can only be activated in ``--dev tap mode``. | |
702 | ||
703 | --vlan-accept args | |
704 | Configure the VLAN tagging policy for the server TAP device. | |
705 | ||
706 | Valid syntax: | |
707 | :: | |
708 | ||
709 | vlan-accept all|tagged|untagged | |
710 | ||
711 | The following modes are available: | |
712 | ||
713 | :code:`tagged` | |
714 | Admit only VLAN-tagged frames. Only VLAN-tagged packets are accepted, | |
715 | while untagged or priority-tagged packets are dropped when entering | |
716 | the server TAP device. | |
717 | ||
718 | :code:`untagged` | |
719 | Admit only untagged and prio-tagged frames. VLAN-tagged packets are | |
720 | not accepted, while untagged or priority-tagged packets entering the | |
721 | server TAP device are tagged with the value configured for the global | |
722 | ``--vlan-pvid`` setting. | |
723 | ||
724 | :code:`all` (default) | |
725 | Admit all frames. All packets are admitted and then treated like | |
726 | untagged or tagged mode respectively. | |
727 | ||
728 | *Note*: | |
729 | Some vendors refer to switch ports running in :code:`tagged` mode | |
730 | as "trunk ports" and switch ports running in :code:`untagged` mode | |
731 | as "access ports". | |
732 | ||
733 | Packets forwarded from clients to the server are VLAN-tagged with the | |
734 | originating client's PVID, unless the VID matches the global | |
735 | ``--vlan-pvid``, in which case the tag is removed. | |
736 | ||
737 | If no *PVID* is configured for a given client (see --vlan-pvid) packets | |
738 | are tagged with 1 by default. | |
739 | ||
740 | --vlan-pvid v | |
741 | Specifies which VLAN identifier a "port" is associated with. Only valid | |
20c42b89 | 742 | when ``--vlan-tagging`` is specified. |
f500c49c DS |
743 | |
744 | In the client context, the setting specifies which VLAN ID a client is | |
745 | associated with. In the global context, the VLAN ID of the server TAP | |
746 | device is set. The latter only makes sense for ``--vlan-accept | |
747 | untagged`` and ``--vlan-accept all`` modes. | |
748 | ||
749 | Valid values for ``v`` go from :code:`1` through to :code:`4094`. The | |
750 | global value defaults to :code:`1`. If no ``--vlan-pvid`` is specified in | |
751 | the client context, the global value is inherited. | |
752 | ||
753 | In some switch implementations, the *PVID* is also referred to as "Native | |
754 | VLAN". |