]>
Commit | Line | Data |
---|---|---|
f500c49c DS |
1 | SCRIPTING INTEGRATION |
2 | ===================== | |
3 | ||
4 | OpenVPN can execute external scripts in various phases of the lifetime of | |
5 | the OpenVPN process. | |
6 | ||
7 | ||
8 | Script Order of Execution | |
9 | ------------------------- | |
10 | ||
11 | #. ``--up`` | |
12 | ||
13 | Executed after TCP/UDP socket bind and TUN/TAP open. | |
14 | ||
15 | #. ``--tls-verify`` | |
16 | ||
17 | Executed when we have a still untrusted remote peer. | |
18 | ||
19 | #. ``--ipchange`` | |
20 | ||
21 | Executed after connection authentication, or remote IP address change. | |
22 | ||
23 | #. ``--client-connect`` | |
24 | ||
25 | Executed in **--mode server** mode immediately after client | |
26 | authentication. | |
27 | ||
28 | #. ``--route-up`` | |
29 | ||
30 | Executed after connection authentication, either immediately after, or | |
31 | some number of seconds after as defined by the **--route-delay** option. | |
32 | ||
33 | #. ``--route-pre-down`` | |
34 | ||
35 | Executed right before the routes are removed. | |
36 | ||
37 | #. ``--client-disconnect`` | |
38 | ||
39 | Executed in ``--mode server`` mode on client instance shutdown. | |
40 | ||
41 | #. ``--down`` | |
42 | ||
43 | Executed after TCP/UDP and TUN/TAP close. | |
44 | ||
45 | #. ``--learn-address`` | |
46 | ||
47 | Executed in ``--mode server`` mode whenever an IPv4 address/route or MAC | |
48 | address is added to OpenVPN's internal routing table. | |
49 | ||
50 | #. ``--auth-user-pass-verify`` | |
51 | ||
52 | Executed in ``--mode server`` mode on new client connections, when the | |
53 | client is still untrusted. | |
54 | ||
23eec2d2 AS |
55 | #. ``--client-crresponse`` |
56 | ||
57 | Execute in ``--mode server`` whenever a client sends a | |
58 | :code:`CR_RESPONSE` message | |
59 | ||
f500c49c DS |
60 | SCRIPT HOOKS |
61 | ------------ | |
62 | ||
63 | --auth-user-pass-verify args | |
64 | Require the client to provide a username/password (possibly in addition | |
65 | to a client certificate) for authentication. | |
66 | ||
67 | Valid syntax: | |
68 | :: | |
69 | ||
70 | auth-user-pass-verify cmd method | |
71 | ||
72 | OpenVPN will run command ``cmd`` to validate the username/password | |
73 | provided by the client. | |
74 | ||
75 | ``cmd`` consists of a path to a script (or executable program), optionally | |
76 | followed by arguments. The path and arguments may be single- or | |
77 | double-quoted and/or escaped using a backslash, and should be separated | |
78 | by one or more spaces. | |
79 | ||
23eec2d2 | 80 | If ``method`` is set to :code:`via-env`, OpenVPN will call ``cmd`` |
f500c49c DS |
81 | with the environmental variables :code:`username` and :code:`password` |
82 | set to the username/password strings provided by the client. *Beware* | |
83 | that this method is insecure on some platforms which make the environment | |
84 | of a process publicly visible to other unprivileged processes. | |
85 | ||
86 | If ``method`` is set to :code:`via-file`, OpenVPN will write the username | |
87 | and password to the first two lines of a temporary file. The filename | |
23eec2d2 | 88 | will be passed as an argument to ``cmd``, and the file will be |
f500c49c DS |
89 | automatically deleted by OpenVPN after the script returns. The location |
90 | of the temporary file is controlled by the ``--tmp-dir`` option, and | |
91 | will default to the current directory if unspecified. For security, | |
92 | consider setting ``--tmp-dir`` to a volatile storage medium such as | |
93 | :code:`/dev/shm` (if available) to prevent the username/password file | |
94 | from touching the hard drive. | |
95 | ||
96 | The script should examine the username and password, returning a success | |
97 | exit code (:code:`0`) if the client's authentication request is to be | |
28e61030 AS |
98 | accepted, a failure code (:code:`1`) to reject the client, or a that |
99 | the authentication is deferred (:code:`2`). If the authentication is | |
100 | deferred, the script must fork/start a background or another non-blocking | |
101 | operation to continue the authentication in the background. When finshing | |
102 | the authentication, a :code:`1` or :code:`0` must be written to the | |
103 | file specified by the :code:`auth_control_file`. | |
104 | ||
c9474fa3 AS |
105 | If the file specified by :code:`auth_failed_reason_file` exists and has |
106 | non-empty content, the content of this file will be used as AUTH_FAILED | |
107 | message. To avoid race conditions, this file should be written before | |
108 | :code:`auth_control_file`. | |
109 | ||
110 | This auth fail reason can be something simple like "User has been permanently | |
111 | disabled" but there are also some special auth failed messages. | |
112 | ||
113 | The ``TEMP`` message indicates that the authentication | |
114 | temporarily failed and that the client should continue to retry to connect. | |
115 | The server can optionally give a user readable message and hint the client a | |
116 | behavior how to proceed. The keywords of the ``AUTH_FAILED,TEMP`` message | |
117 | are comma separated keys/values and provide a hint to the client how to | |
118 | proceed. Currently defined keywords are: | |
119 | ||
120 | ``backoff`` :code:`s` | |
121 | instructs the client to wait at least :code:`s` seconds before the next | |
122 | connection attempt. If the client already uses a higher delay for | |
123 | reconnection attempt, the delay will not be shortened. | |
124 | ||
125 | ``advance addr`` | |
126 | Instructs the client to reconnect to the next (IP) address of the | |
127 | current server. | |
128 | ||
129 | ``advance remote`` | |
130 | Instructs the client to skip the remaining IP addresses of the current | |
131 | server and instead connect to the next server specified in the | |
132 | configuration file. | |
133 | ||
134 | ``advance no`` | |
135 | Instructs the client to retry connecting to the same server again. | |
136 | ||
137 | For example, the message ``TEMP[backoff 42,advance no]: No free IP addresses`` | |
138 | indicates that the VPN connection can currently not succeed and instructs | |
139 | the client to retry in 42 seconds again. | |
140 | ||
28e61030 AS |
141 | When deferred authentication is in use, the script can also request |
142 | pending authentication by writing to the file specified by the | |
143 | :code:`auth_pending_file`. The first line must be the timeout in | |
144 | seconds, the required method on the second line (e.g. crtext) and | |
145 | third line must be the EXTRA as documented in the | |
146 | ``client-pending-auth`` section of `doc/management.txt`. | |
f500c49c DS |
147 | |
148 | This directive is designed to enable a plugin-style interface for | |
149 | extending OpenVPN's authentication capabilities. | |
150 | ||
151 | To protect against a client passing a maliciously formed username or | |
152 | password string, the username string must consist only of these | |
153 | characters: alphanumeric, underbar (':code:`_`'), dash (':code:`-`'), | |
154 | dot (':code:`.`'), or at (':code:`@`'). The password string can consist | |
155 | of any printable characters except for CR or LF. Any illegal characters | |
156 | in either the username or password string will be converted to | |
157 | underbar (':code:`_`'). | |
158 | ||
159 | Care must be taken by any user-defined scripts to avoid creating a | |
160 | security vulnerability in the way that these strings are handled. Never | |
161 | use these strings in such a way that they might be escaped or evaluated | |
162 | by a shell interpreter. | |
163 | ||
164 | For a sample script that performs PAM authentication, see | |
165 | :code:`sample-scripts/auth-pam.pl` in the OpenVPN source distribution. | |
166 | ||
23eec2d2 AS |
167 | --client-crresponse |
168 | Executed when the client sends a text based challenge response. | |
169 | ||
170 | Valid syntax: | |
171 | :: | |
172 | ||
173 | client-crresponse cmd | |
174 | ||
175 | OpenVPN will write the response of the client into a temporary file. | |
176 | The filename will be passed as an argument to ``cmd``, and the file will be | |
177 | automatically deleted by OpenVPN after the script returns. | |
178 | ||
179 | The response is passed as is from the client. The script needs to check | |
180 | itself if the input is valid, e.g. if the input is valid base64 encoding. | |
181 | ||
182 | The script can either directly write the result of the verification to | |
183 | :code:`auth_control_file or further defer it. See ``--auth-user-pass-verify`` | |
184 | for details. | |
185 | ||
20ce5e31 AS |
186 | For a sample script that implement TOTP (RFC 6238) based two-factor |
187 | authentication, see :code:`sample-scripts/totpauth.py`. | |
188 | ||
f500c49c DS |
189 | --client-connect cmd |
190 | Run command ``cmd`` on client connection. | |
191 | ||
192 | ``cmd`` consists of a path to a script (or executable program), optionally | |
193 | followed by arguments. The path and arguments may be single- or | |
194 | double-quoted and/or escaped using a backslash, and should be separated | |
195 | by one or more spaces. | |
196 | ||
197 | The command is passed the common name and IP address of the | |
198 | just-authenticated client as environmental variables (see environmental | |
199 | variable section below). The command is also passed the pathname of a | |
200 | freshly created temporary file as the last argument (after any arguments | |
201 | specified in ``cmd`` ), to be used by the command to pass dynamically | |
202 | generated config file directives back to OpenVPN. | |
203 | ||
204 | If the script wants to generate a dynamic config file to be applied on | |
205 | the server when the client connects, it should write it to the file | |
206 | named by the last argument. | |
207 | ||
208 | See the ``--client-config-dir`` option below for options which can be | |
209 | legally used in a dynamically generated config file. | |
210 | ||
211 | Note that the return value of ``script`` is significant. If ``script`` | |
212 | returns a non-zero error status, it will cause the client to be | |
213 | disconnected. | |
214 | ||
71d56aea AS |
215 | If a ``--client-connect`` wants to defer the generating of the |
216 | configuration then the script needs to use the | |
217 | :code:`client_connect_deferred_file` and | |
218 | :code:`client_connect_config_file` environment variables, and write | |
219 | status accordingly into these files. See the `Environmental Variables`_ | |
220 | section for more details. | |
221 | ||
f500c49c DS |
222 | --client-disconnect cmd |
223 | Like ``--client-connect`` but called on client instance shutdown. Will | |
224 | not be called unless the ``--client-connect`` script and plugins (if | |
225 | defined) were previously called on this instance with successful (0) | |
226 | status returns. | |
227 | ||
228 | The exception to this rule is if the ``--client-disconnect`` command or | |
229 | plugins are cascaded, and at least one client-connect function | |
230 | succeeded, then ALL of the client-disconnect functions for scripts and | |
231 | plugins will be called on client instance object deletion, even in cases | |
232 | where some of the related client-connect functions returned an error | |
233 | status. | |
234 | ||
50c7700d GD |
235 | The ``--client-disconnect`` command is not passed any extra arguments |
236 | (only those arguments specified in cmd, if any). | |
f500c49c DS |
237 | |
238 | --down cmd | |
239 | Run command ``cmd`` after TUN/TAP device close (post ``--user`` UID | |
240 | change and/or ``--chroot`` ). ``cmd`` consists of a path to script (or | |
241 | executable program), optionally followed by arguments. The path and | |
242 | arguments may be single- or double-quoted and/or escaped using a | |
243 | backslash, and should be separated by one or more spaces. | |
244 | ||
245 | Called with the same parameters and environmental variables as the | |
246 | ``--up`` option above. | |
247 | ||
248 | Note that if you reduce privileges by using ``--user`` and/or | |
249 | ``--group``, your ``--down`` script will also run at reduced privilege. | |
250 | ||
251 | --down-pre | |
252 | Call ``--down`` cmd/script before, rather than after, TUN/TAP close. | |
253 | ||
254 | --ipchange cmd | |
255 | Run command ``cmd`` when our remote ip-address is initially | |
256 | authenticated or changes. | |
257 | ||
258 | ``cmd`` consists of a path to a script (or executable program), optionally | |
259 | followed by arguments. The path and arguments may be single- or | |
260 | double-quoted and/or escaped using a backslash, and should be separated | |
261 | by one or more spaces. | |
262 | ||
263 | When ``cmd`` is executed two arguments are appended after any arguments | |
264 | specified in ``cmd`` , as follows: | |
265 | :: | |
266 | ||
267 | cmd ip address port number | |
268 | ||
269 | Don't use ``--ipchange`` in ``--mode server`` mode. Use a | |
270 | ``--client-connect`` script instead. | |
271 | ||
272 | See the `Environmental Variables`_ section below for additional | |
273 | parameters passed as environmental variables. | |
274 | ||
275 | If you are running in a dynamic IP address environment where the IP | |
276 | addresses of either peer could change without notice, you can use this | |
277 | script, for example, to edit the :code:`/etc/hosts` file with the current | |
278 | address of the peer. The script will be run every time the remote peer | |
279 | changes its IP address. | |
280 | ||
281 | Similarly if *our* IP address changes due to DHCP, we should configure | |
282 | our IP address change script (see man page for ``dhcpcd``\(8)) to | |
283 | deliver a ``SIGHUP`` or ``SIGUSR1`` signal to OpenVPN. OpenVPN will | |
284 | then re-establish a connection with its most recently authenticated | |
285 | peer on its new IP address. | |
286 | ||
287 | --learn-address cmd | |
288 | Run command ``cmd`` to validate client virtual addresses or routes. | |
289 | ||
290 | ``cmd`` consists of a path to a script (or executable program), optionally | |
291 | followed by arguments. The path and arguments may be single- or | |
292 | double-quoted and/or escaped using a backslash, and should be separated | |
293 | by one or more spaces. | |
294 | ||
295 | Three arguments will be appended to any arguments in ``cmd`` as follows: | |
296 | ||
297 | :code:`$1` - [operation] | |
298 | :code:`"add"`, :code:`"update"`, or :code:`"delete"` based on whether | |
299 | or not the address is being added to, modified, or deleted from | |
300 | OpenVPN's internal routing table. | |
301 | ||
302 | :code:`$2` - [address] | |
303 | The address being learned or unlearned. This can be an IPv4 address | |
304 | such as :code:`"198.162.10.14"`, an IPv4 subnet such as | |
305 | :code:`"198.162.10.0/24"`, or an ethernet MAC address (when | |
306 | ``--dev tap`` is being used) such as :code:`"00:FF:01:02:03:04"`. | |
307 | ||
308 | :code:`$3` - [common name] | |
309 | The common name on the certificate associated with the client linked | |
310 | to this address. Only present for :code:`"add"` or :code:`"update"` | |
311 | operations, not :code:`"delete"`. | |
312 | ||
313 | On :code:`"add"` or :code:`"update"` methods, if the script returns | |
314 | a failure code (non-zero), OpenVPN will reject the address and will not | |
315 | modify its internal routing table. | |
316 | ||
317 | Normally, the ``cmd`` script will use the information provided above to | |
318 | set appropriate firewall entries on the VPN TUN/TAP interface. Since | |
319 | OpenVPN provides the association between virtual IP or MAC address and | |
320 | the client's authenticated common name, it allows a user-defined script | |
321 | to configure firewall access policies with regard to the client's | |
322 | high-level common name, rather than the low level client virtual | |
323 | addresses. | |
324 | ||
325 | --route-up cmd | |
326 | Run command ``cmd`` after routes are added, subject to ``--route-delay``. | |
327 | ||
328 | ``cmd`` consists of a path to a script (or executable program), optionally | |
329 | followed by arguments. The path and arguments may be single- or | |
330 | double-quoted and/or escaped using a backslash, and should be separated | |
331 | by one or more spaces. | |
332 | ||
333 | See the `Environmental Variables`_ section below for additional | |
334 | parameters passed as environmental variables. | |
335 | ||
336 | --route-pre-down cmd | |
337 | Run command ``cmd`` before routes are removed upon disconnection. | |
338 | ||
339 | ``cmd`` consists of a path to a script (or executable program), optionally | |
340 | followed by arguments. The path and arguments may be single- or | |
341 | double-quoted and/or escaped using a backslash, and should be separated | |
342 | by one or more spaces. | |
343 | ||
344 | See the `Environmental Variables`_ section below for additional | |
345 | parameters passed as environmental variables. | |
346 | ||
347 | --setenv args | |
348 | Set a custom environmental variable :code:`name=value` to pass to script. | |
349 | ||
350 | Valid syntaxes: | |
351 | :: | |
352 | ||
353 | setenv name value | |
354 | setenv FORWARD_COMPATIBLE 1 | |
355 | setenv opt config_option | |
356 | ||
357 | By setting :code:`FORWARD_COMPATIBLE` to :code:`1`, the config file | |
358 | syntax checking is relaxed so that unknown directives will trigger a | |
359 | warning but not a fatal error, on the assumption that a given unknown | |
360 | directive might be valid in future OpenVPN versions. | |
361 | ||
362 | This option should be used with caution, as there are good security | |
363 | reasons for having OpenVPN fail if it detects problems in a config file. | |
364 | Having said that, there are valid reasons for wanting new software | |
365 | features to gracefully degrade when encountered by older software | |
366 | versions. | |
367 | ||
368 | It is also possible to tag a single directive so as not to trigger a | |
369 | fatal error if the directive isn't recognized. To do this, prepend the | |
370 | following before the directive: ``setenv opt`` | |
371 | ||
372 | Versions prior to OpenVPN 2.3.3 will always ignore options set with the | |
373 | ``setenv opt`` directive. | |
374 | ||
375 | See also ``--ignore-unknown-option`` | |
376 | ||
377 | --setenv-safe args | |
378 | Set a custom environmental variable :code:`OPENVPN_name` to :code:`value` | |
379 | to pass to scripts. | |
380 | ||
381 | Valid syntaxes: | |
382 | :: | |
383 | ||
384 | setenv-safe name value | |
385 | ||
386 | This directive is designed to be pushed by the server to clients, and | |
387 | the prepending of :code:`OPENVPN_` to the environmental variable is a | |
388 | safety precaution to prevent a :code:`LD_PRELOAD` style attack from a | |
389 | malicious or compromised server. | |
390 | ||
391 | --tls-verify cmd | |
392 | Run command ``cmd`` to verify the X509 name of a pending TLS connection | |
393 | that has otherwise passed all other tests of certification (except for | |
394 | revocation via ``--crl-verify`` directive; the revocation test occurs | |
395 | after the ``--tls-verify`` test). | |
396 | ||
397 | ``cmd`` should return :code:`0` to allow the TLS handshake to proceed, | |
398 | or :code:`1` to fail. | |
399 | ||
400 | ``cmd`` consists of a path to a script (or executable program), optionally | |
401 | followed by arguments. The path and arguments may be single- or | |
402 | double-quoted and/or escaped using a backslash, and should be separated | |
403 | by one or more spaces. | |
404 | ||
405 | When ``cmd`` is executed two arguments are appended after any arguments | |
406 | specified in ``cmd``, as follows: | |
407 | :: | |
408 | ||
409 | cmd certificate_depth subject | |
410 | ||
411 | These arguments are, respectively, the current certificate depth and the | |
412 | X509 subject distinguished name (dn) of the peer. | |
413 | ||
414 | This feature is useful if the peer you want to trust has a certificate | |
415 | which was signed by a certificate authority who also signed many other | |
416 | certificates, where you don't necessarily want to trust all of them, but | |
417 | rather be selective about which peer certificate you will accept. This | |
418 | feature allows you to write a script which will test the X509 name on a | |
419 | certificate and decide whether or not it should be accepted. For a | |
420 | simple perl script which will test the common name field on the | |
421 | certificate, see the file ``verify-cn`` in the OpenVPN distribution. | |
422 | ||
423 | See the `Environmental Variables`_ section below for additional | |
424 | parameters passed as environmental variables. | |
425 | ||
426 | --up cmd | |
427 | Run command ``cmd`` after successful TUN/TAP device open (pre ``--user`` | |
428 | UID change). | |
429 | ||
430 | ``cmd`` consists of a path to a script (or executable program), optionally | |
431 | followed by arguments. The path and arguments may be single- or | |
432 | double-quoted and/or escaped using a backslash, and should be separated | |
433 | by one or more spaces. | |
434 | ||
435 | The up command is useful for specifying route commands which route IP | |
436 | traffic destined for private subnets which exist at the other end of the | |
437 | VPN connection into the tunnel. | |
438 | ||
439 | For ``--dev tun`` execute as: | |
440 | :: | |
441 | ||
3780ce0e | 442 | cmd tun_dev tun_mtu 0 ifconfig_local_ip ifconfig_remote_ip [init | restart] |
f500c49c DS |
443 | |
444 | For ``--dev tap`` execute as: | |
445 | :: | |
446 | ||
3780ce0e | 447 | cmd tap_dev tap_mtu 0 ifconfig_local_ip ifconfig_netmask [init | restart] |
f500c49c DS |
448 | |
449 | See the `Environmental Variables`_ section below for additional | |
3780ce0e AS |
450 | parameters passed as environmental variables. The ``0`` argument |
451 | used to be ``link_mtu`` which is no longer passed to scripts - to | |
452 | keep the argument order, it was replaced with ``0``. | |
f500c49c DS |
453 | |
454 | Note that if ``cmd`` includes arguments, all OpenVPN-generated arguments | |
455 | will be appended to them to build an argument list with which the | |
456 | executable will be called. | |
457 | ||
458 | Typically, ``cmd`` will run a script to add routes to the tunnel. | |
459 | ||
460 | Normally the up script is called after the TUN/TAP device is opened. In | |
461 | this context, the last command line parameter passed to the script will | |
462 | be *init.* If the ``--up-restart`` option is also used, the up script | |
463 | will be called for restarts as well. A restart is considered to be a | |
464 | partial reinitialization of OpenVPN where the TUN/TAP instance is | |
465 | preserved (the ``--persist-tun`` option will enable such preservation). | |
466 | A restart can be generated by a SIGUSR1 signal, a ``--ping-restart`` | |
467 | timeout, or a connection reset when the TCP protocol is enabled with the | |
468 | ``--proto`` option. If a restart occurs, and ``--up-restart`` has been | |
469 | specified, the up script will be called with *restart* as the last | |
470 | parameter. | |
471 | ||
472 | *NOTE:* | |
473 | On restart, OpenVPN will not pass the full set of environment | |
474 | variables to the script. Namely, everything related to routing and | |
475 | gateways will not be passed, as nothing needs to be done anyway - all | |
476 | the routing setup is already in place. Additionally, the up-restart | |
477 | script will run with the downgraded UID/GID settings (if configured). | |
478 | ||
479 | The following standalone example shows how the ``--up`` script can be | |
480 | called in both an initialization and restart context. (*NOTE:* for | |
481 | security reasons, don't run the following example unless UDP port 9999 | |
482 | is blocked by your firewall. Also, the example will run indefinitely, so | |
483 | you should abort with control-c). | |
484 | ||
485 | :: | |
486 | ||
487 | openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 \ | |
488 | --up 'echo up' --down 'echo down' --persist-tun \ | |
489 | --up-restart | |
490 | ||
491 | Note that OpenVPN also provides the ``--ifconfig`` option to | |
492 | automatically ifconfig the TUN device, eliminating the need to define an | |
493 | ``--up`` script, unless you also want to configure routes in the | |
494 | ``--up`` script. | |
495 | ||
496 | If ``--ifconfig`` is also specified, OpenVPN will pass the ifconfig | |
497 | local and remote endpoints on the command line to the ``--up`` script so | |
498 | that they can be used to configure routes such as: | |
499 | ||
500 | :: | |
501 | ||
502 | route add -net 10.0.0.0 netmask 255.255.255.0 gw $5 | |
503 | ||
504 | --up-delay | |
505 | Delay TUN/TAP open and possible ``--up`` script execution until after | |
506 | TCP/UDP connection establishment with peer. | |
507 | ||
508 | In ``--proto udp`` mode, this option normally requires the use of | |
509 | ``--ping`` to allow connection initiation to be sensed in the absence of | |
510 | tunnel data, since UDP is a "connectionless" protocol. | |
511 | ||
512 | On Windows, this option will delay the TAP-Win32 media state | |
513 | transitioning to "connected" until connection establishment, i.e. the | |
514 | receipt of the first authenticated packet from the peer. | |
515 | ||
516 | --up-restart | |
517 | Enable the ``--up`` and ``--down`` scripts to be called for restarts as | |
518 | well as initial program start. This option is described more fully above | |
519 | in the ``--up`` option documentation. | |
520 | ||
521 | String Types and Remapping | |
522 | -------------------------- | |
523 | ||
524 | In certain cases, OpenVPN will perform remapping of characters in | |
525 | strings. Essentially, any characters outside the set of permitted | |
526 | characters for each string type will be converted to underbar ('\_'). | |
527 | ||
528 | *Q: Why is string remapping necessary?* | |
529 | It's an important security feature to prevent the malicious | |
530 | coding of strings from untrusted sources to be passed as parameters to | |
531 | scripts, saved in the environment, used as a common name, translated to | |
532 | a filename, etc. | |
533 | ||
534 | *Q: Can string remapping be disabled?* | |
535 | Yes, by using the ``--no-name-remapping`` option, however this | |
536 | should be considered an advanced option. | |
537 | ||
538 | Here is a brief rundown of OpenVPN's current string types and the | |
539 | permitted character class for each string: | |
540 | ||
541 | *X509 Names* | |
542 | Alphanumeric, underbar ('\_'), dash ('-'), dot ('.'), at | |
543 | ('@'), colon (':'), slash ('/'), and equal ('='). Alphanumeric is | |
544 | defined as a character which will cause the C library isalnum() function | |
545 | to return true. | |
546 | ||
547 | *Common Names* | |
548 | Alphanumeric, underbar ('\_'), dash ('-'), dot ('.'), and at ('@'). | |
549 | ||
550 | *--auth-user-pass username* | |
551 | Same as Common Name, with one exception: | |
552 | starting with OpenVPN 2.0.1, the username is passed to the | |
553 | :code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` plugin in its raw form, | |
554 | without string remapping. | |
555 | ||
556 | *--auth-user-pass password* | |
557 | Any "printable" character except CR or LF. Printable is defined to be | |
558 | a character which will cause the C library isprint() function to | |
559 | return true. | |
560 | ||
561 | *--client-config-dir filename as derived from common name or`username* | |
562 | Alphanumeric, underbar ('\_'), dash ('-'), and dot ('.') except for "." | |
563 | or ".." as standalone strings. As of v2.0.1-rc6, the at ('@') character | |
564 | has been added as well for compatibility with the common name character | |
565 | class. | |
566 | ||
567 | *Environmental variable names* | |
568 | Alphanumeric or underbar ('\_'). | |
569 | ||
570 | *Environmental variable values* | |
571 | Any printable character. | |
572 | ||
573 | For all cases, characters in a string which are not members of the legal | |
574 | character class for that string type will be remapped to underbar | |
575 | ('\_'). Â | |
576 | ||
577 | ||
578 | Environmental Variables | |
579 | ----------------------- | |
580 | ||
581 | Once set, a variable is persisted indefinitely until it is reset by a | |
582 | new value or a restart, | |
583 | ||
584 | As of OpenVPN 2.0-beta12, in server mode, environmental variables set by | |
585 | OpenVPN are scoped according to the client objects they are associated | |
586 | with, so there should not be any issues with scripts having access to | |
587 | stale, previously set variables which refer to different client | |
588 | instances. | |
589 | ||
590 | :code:`bytes_received` | |
591 | Total number of bytes received from client during VPN session. Set prior | |
592 | to execution of the ``--client-disconnect`` script. | |
593 | ||
594 | :code:`bytes_sent` | |
595 | Total number of bytes sent to client during VPN session. Set prior to | |
596 | execution of the ``--client-disconnect`` script. | |
597 | ||
71d56aea AS |
598 | :code:`client_connect_config_file` |
599 | The path to the configuration file that should be written to by the | |
600 | ``--client-connect`` script (optional, if per-session configuration | |
601 | is desired). This is the same file name as passed via command line | |
602 | argument on the call to the ``--client-connect`` script. | |
603 | ||
604 | :code:`client_connect_deferred_file` | |
605 | This file can be optionally written to in order to to communicate a | |
606 | status code of the ``--client-connect`` script or plgin. Only the | |
607 | first character in the file is relevant. It must be either :code:`1` | |
608 | to indicate normal script execution, :code:`0` indicates an error (in | |
609 | the same way that a non zero exit status does) or :code:`2` to indicate | |
610 | that the script deferred returning the config file. | |
611 | ||
612 | For deferred (background) handling, the script or plugin MUST write | |
613 | :code:`2` to the file to indicate the deferral and then return with | |
614 | exit code :code:`0` to signal ``deferred handler started OK``. | |
615 | ||
616 | A background process or similar must then take care of writing the | |
617 | configuration to the file indicated by the | |
618 | :code:`client_connect_config_file` environment variable and when | |
619 | finished, write the a :code:`1` to this file (or :code:`0` in case of | |
620 | an error). | |
621 | ||
622 | The absence of any character in the file when the script finishes | |
623 | executing is interpreted the same as :code:`1`. This allows scripts | |
624 | that are not written to support the defer mechanism to be used | |
625 | unmodified. | |
626 | ||
f500c49c DS |
627 | :code:`common_name` |
628 | The X509 common name of an authenticated client. Set prior to execution | |
629 | of ``--client-connect``, ``--client-disconnect`` and | |
630 | ``--auth-user-pass-verify`` scripts. | |
631 | ||
632 | :code:`config` | |
633 | Name of first ``--config`` file. Set on program initiation and reset on | |
634 | SIGHUP. | |
635 | ||
636 | :code:`daemon` | |
637 | Set to "1" if the ``--daemon`` directive is specified, or "0" otherwise. | |
638 | Set on program initiation and reset on SIGHUP. | |
639 | ||
640 | :code:`daemon_log_redirect` | |
641 | Set to "1" if the ``--log`` or ``--log-append`` directives are | |
642 | specified, or "0" otherwise. Set on program initiation and reset on | |
643 | SIGHUP. | |
644 | ||
645 | :code:`dev` | |
646 | The actual name of the TUN/TAP device, including a unit number if it | |
647 | exists. Set prior to ``--up`` or ``--down`` script execution. | |
648 | ||
649 | :code:`dev_idx` | |
650 | On Windows, the device index of the TUN/TAP adapter (to be used in | |
651 | netsh.exe calls which sometimes just do not work right with interface | |
652 | names). Set prior to ``--up`` or ``--down`` script execution. | |
653 | ||
b3e0d95d HH |
654 | :code:`dns_*` |
655 | The ``--dns`` configuration options will be made available to script | |
656 | execution through this set of environment variables. Variables appear | |
657 | only if the corresponding option has a value assigned. For the semantics | |
658 | of each individual variable, please refer to the documentation for ``--dns``. | |
659 | ||
660 | :: | |
661 | ||
662 | dns_search_domain_{n} | |
424ae590 HH |
663 | dns_server_{n}_address_{m} |
664 | dns_server_{n}_port_{m} | |
b3e0d95d | 665 | dns_server_{n}_resolve_domain_{m} |
b3e0d95d HH |
666 | dns_server_{n}_dnssec |
667 | dns_server_{n}_transport | |
668 | dns_server_{n}_sni | |
669 | ||
f500c49c DS |
670 | :code:`foreign_option_{n}` |
671 | An option pushed via ``--push`` to a client which does not natively | |
672 | support it, such as ``--dhcp-option`` on a non-Windows system, will be | |
673 | recorded to this environmental variable sequence prior to ``--up`` | |
674 | script execution. | |
675 | ||
676 | :code:`ifconfig_broadcast` | |
677 | The broadcast address for the virtual ethernet segment which is derived | |
678 | from the ``--ifconfig`` option when ``--dev tap`` is used. Set prior to | |
679 | OpenVPN calling the :code:`ifconfig` or :code:`netsh` (windows version | |
680 | of ifconfig) commands which normally occurs prior to ``--up`` script | |
681 | execution. | |
682 | ||
683 | :code:`ifconfig_ipv6_local` | |
684 | The local VPN endpoint IPv6 address specified in the | |
685 | ``--ifconfig-ipv6`` option (first parameter). Set prior to OpenVPN | |
686 | calling the :code:`ifconfig` or code:`netsh` (windows version of | |
687 | ifconfig) commands which normally occurs prior to ``--up`` script | |
688 | execution. | |
689 | ||
690 | :code:`ifconfig_ipv6_netbits` | |
691 | The prefix length of the IPv6 network on the VPN interface. Derived | |
692 | from the /nnn parameter of the IPv6 address in the ``--ifconfig-ipv6`` | |
693 | option (first parameter). Set prior to OpenVPN calling the | |
694 | :code:`ifconfig` or :code:`netsh` (windows version of ifconfig) | |
695 | commands which normally occurs prior to ``--up`` script execution. | |
696 | ||
697 | :code:`ifconfig_ipv6_remote` | |
698 | The remote VPN endpoint IPv6 address specified in the | |
699 | ``--ifconfig-ipv6`` option (second parameter). Set prior to OpenVPN | |
700 | calling the :code:`ifconfig` or :code:`netsh` (windows version of | |
701 | ifconfig) commands which normally occurs prior to ``--up`` script | |
702 | execution. | |
703 | ||
704 | :code:`ifconfig_local` | |
705 | The local VPN endpoint IP address specified in the ``--ifconfig`` | |
706 | option (first parameter). Set prior to OpenVPN calling the | |
707 | :code:`ifconfig` or :code:`netsh` (windows version of ifconfig) | |
708 | commands which normally occurs prior to ``--up`` script execution. | |
709 | ||
710 | :code:`ifconfig_remote` | |
711 | The remote VPN endpoint IP address specified in the ``--ifconfig`` | |
712 | option (second parameter) when ``--dev tun`` is used. Set prior to | |
713 | OpenVPN calling the :code:`ifconfig` or :code:`netsh` (windows version | |
714 | of ifconfig) commands which normally occurs prior to ``--up`` script | |
715 | execution. | |
716 | ||
717 | :code:`ifconfig_netmask` | |
718 | The subnet mask of the virtual ethernet segment that is specified as | |
719 | the second parameter to ``--ifconfig`` when ``--dev tap`` is being | |
720 | used. Set prior to OpenVPN calling the :code:`ifconfig` or | |
721 | :code:`netsh` (windows version of ifconfig) commands which normally | |
722 | occurs prior to ``--up`` script execution. | |
723 | ||
724 | :code:`ifconfig_pool_local_ip` | |
725 | The local virtual IP address for the TUN/TAP tunnel taken from an | |
726 | ``--ifconfig-push`` directive if specified, or otherwise from the | |
727 | ifconfig pool (controlled by the ``--ifconfig-pool`` config file | |
728 | directive). Only set for ``--dev tun`` tunnels. This option is set on | |
729 | the server prior to execution of the ``--client-connect`` and | |
730 | ``--client-disconnect`` scripts. | |
731 | ||
732 | :code:`ifconfig_pool_netmask` | |
733 | The virtual IP netmask for the TUN/TAP tunnel taken from an | |
734 | ``--ifconfig-push`` directive if specified, or otherwise from the | |
735 | ifconfig pool (controlled by the ``--ifconfig-pool`` config file | |
736 | directive). Only set for ``--dev tap`` tunnels. This option is set on | |
737 | the server prior to execution of the ``--client-connect`` and | |
738 | ``--client-disconnect`` scripts. | |
739 | ||
740 | :code:`ifconfig_pool_remote_ip` | |
741 | The remote virtual IP address for the TUN/TAP tunnel taken from an | |
742 | ``--ifconfig-push`` directive if specified, or otherwise from the | |
743 | ifconfig pool (controlled by the ``--ifconfig-pool`` config file | |
744 | directive). This option is set on the server prior to execution of the | |
745 | ``--client-connect`` and ``--client-disconnect`` scripts. | |
746 | ||
747 | :code:`link_mtu` | |
3780ce0e AS |
748 | No longer passed to scripts since OpenVPN 2.6.0. Used to be the |
749 | maximum packet size (not including the IP header) of tunnel data in | |
750 | UDP tunnel transport mode. | |
f500c49c DS |
751 | |
752 | :code:`local` | |
753 | The ``--local`` parameter. Set on program initiation and reset on | |
754 | SIGHUP. | |
755 | ||
756 | :code:`local_port` | |
757 | The local port number or name, specified by ``--port`` or ``--lport``. | |
758 | Set on program initiation and reset on SIGHUP. | |
759 | ||
760 | :code:`password` | |
761 | The password provided by a connecting client. Set prior to | |
762 | ``--auth-user-pass-verify`` script execution only when the ``via-env`` | |
763 | modifier is specified, and deleted from the environment after the script | |
764 | returns. | |
765 | ||
766 | :code:`proto` | |
767 | The ``--proto`` parameter. Set on program initiation and reset on | |
768 | SIGHUP. | |
769 | ||
770 | :code:`remote_{n}` | |
771 | The ``--remote`` parameter. Set on program initiation and reset on | |
772 | SIGHUP. | |
773 | ||
774 | :code:`remote_port_{n}` | |
775 | The remote port number, specified by ``--port`` or ``--rport``. Set on | |
776 | program initiation and reset on SIGHUP. | |
777 | ||
778 | :code:`route_net_gateway` | |
779 | The pre-existing default IP gateway in the system routing table. Set | |
780 | prior to ``--up`` script execution. | |
781 | ||
782 | :code:`route_vpn_gateway` | |
783 | The default gateway used by ``--route`` options, as specified in either | |
784 | the ``--route-gateway`` option or the second parameter to | |
785 | ``--ifconfig`` when ``--dev tun`` is specified. Set prior to ``--up`` | |
786 | script execution. | |
787 | ||
788 | :code:`route_{parm}_{n}` | |
789 | A set of variables which define each route to be added, and are set | |
790 | prior to ``--up`` script execution. | |
791 | ||
792 | ``parm`` will be one of :code:`network`, :code:`netmask"`, | |
793 | :code:`gateway`, or :code:`metric`. | |
794 | ||
795 | ``n`` is the OpenVPN route number, starting from 1. | |
796 | ||
797 | If the network or gateway are resolvable DNS names, their IP address | |
798 | translations will be recorded rather than their names as denoted on the | |
799 | command line or configuration file. | |
800 | ||
801 | :code:`route_ipv6_{parm}_{n}` | |
802 | A set of variables which define each IPv6 route to be added, and are | |
803 | set prior to **--up** script execution. | |
804 | ||
bfb28845 JS |
805 | ``parm`` will be one of :code:`network`, :code:`gateway` or |
806 | :code:`metric`. ``route_ipv6_network_{n}`` contains :code:`netmask` | |
807 | as :code:`/nnn`, unlike IPv4 where it is passed in a separate environment | |
808 | variable. | |
f500c49c DS |
809 | |
810 | ``n`` is the OpenVPN route number, starting from 1. | |
811 | ||
812 | If the network or gateway are resolvable DNS names, their IP address | |
813 | translations will be recorded rather than their names as denoted on the | |
814 | command line or configuration file. | |
815 | ||
f500c49c DS |
816 | :code:`script_context` |
817 | Set to "init" or "restart" prior to up/down script execution. For more | |
818 | information, see documentation for ``--up``. | |
819 | ||
820 | :code:`script_type` | |
821 | Prior to execution of any script, this variable is set to the type of | |
822 | script being run. It can be one of the following: :code:`up`, | |
823 | :code:`down`, :code:`ipchange`, :code:`route-up`, :code:`tls-verify`, | |
824 | :code:`auth-user-pass-verify`, :code:`client-connect`, | |
825 | :code:`client-disconnect` or :code:`learn-address`. Set prior to | |
826 | execution of any script. | |
827 | ||
828 | :code:`signal` | |
829 | The reason for exit or restart. Can be one of :code:`sigusr1`, | |
830 | :code:`sighup`, :code:`sigterm`, :code:`sigint`, :code:`inactive` | |
831 | (controlled by ``--inactive`` option), :code:`ping-exit` (controlled | |
832 | by ``--ping-exit`` option), :code:`ping-restart` (controlled by | |
833 | ``--ping-restart`` option), :code:`connection-reset` (triggered on TCP | |
834 | connection reset), :code:`error` or :code:`unknown` (unknown signal). | |
835 | This variable is set just prior to down script execution. | |
836 | ||
837 | :code:`time_ascii` | |
838 | Client connection timestamp, formatted as a human-readable time string. | |
839 | Set prior to execution of the ``--client-connect`` script. | |
840 | ||
841 | :code:`time_duration` | |
842 | The duration (in seconds) of the client session which is now | |
843 | disconnecting. Set prior to execution of the ``--client-disconnect`` | |
844 | script. | |
845 | ||
846 | :code:`time_unix` | |
847 | Client connection timestamp, formatted as a unix integer date/time | |
848 | value. Set prior to execution of the ``--client-connect`` script. | |
849 | ||
850 | :code:`tls_digest_{n}` / :code:`tls_digest_sha256_{n}` | |
851 | Contains the certificate SHA1 / SHA256 fingerprint, where ``n`` is the | |
852 | verification level. Only set for TLS connections. Set prior to execution | |
853 | of ``--tls-verify`` script. | |
854 | ||
855 | :code:`tls_id_{n}` | |
856 | A series of certificate fields from the remote peer, where ``n`` is the | |
857 | verification level. Only set for TLS connections. Set prior to execution | |
858 | of ``--tls-verify`` script. | |
859 | ||
860 | :code:`tls_serial_{n}` | |
861 | The serial number of the certificate from the remote peer, where ``n`` | |
862 | is the verification level. Only set for TLS connections. Set prior to | |
863 | execution of ``--tls-verify`` script. This is in the form of a decimal | |
864 | string like "933971680", which is suitable for doing serial-based OCSP | |
865 | queries (with OpenSSL, do not prepend "0x" to the string) If something | |
866 | goes wrong while reading the value from the certificate it will be an | |
867 | empty string, so your code should check that. See the | |
868 | :code:`contrib/OCSP_check/OCSP_check.sh` script for an example. | |
869 | ||
870 | :code:`tls_serial_hex_{n}` | |
871 | Like :code:`tls_serial_{n}`, but in hex form (e.g. | |
872 | :code:`12:34:56:78:9A`). | |
873 | ||
874 | :code:`tun_mtu` | |
875 | The MTU of the TUN/TAP device. Set prior to ``--up`` or ``--down`` | |
876 | script execution. | |
877 | ||
878 | :code:`trusted_ip` / :code:`trusted_ip6`) | |
879 | Actual IP address of connecting client or peer which has been | |
880 | authenticated. Set prior to execution of ``--ipchange``, | |
881 | ``--client-connect`` and ``--client-disconnect`` scripts. If using ipv6 | |
882 | endpoints (udp6, tcp6), :code:`trusted_ip6` will be set instead. | |
883 | ||
884 | :code:`trusted_port` | |
885 | Actual port number of connecting client or peer which has been | |
886 | authenticated. Set prior to execution of ``--ipchange``, | |
887 | ``--client-connect`` and ``--client-disconnect`` scripts. | |
888 | ||
889 | :code:`untrusted_ip` / :code:`untrusted_ip6` | |
890 | Actual IP address of connecting client or peer which has not been | |
891 | authenticated yet. Sometimes used to *nmap* the connecting host in a | |
892 | ``--tls-verify`` script to ensure it is firewalled properly. Set prior | |
893 | to execution of ``--tls-verify`` and ``--auth-user-pass-verify`` | |
894 | scripts. If using ipv6 endpoints (udp6, tcp6), :code:`untrusted_ip6` | |
895 | will be set instead. | |
896 | ||
897 | :code:`untrusted_port` | |
898 | Actual port number of connecting client or peer which has not been | |
899 | authenticated yet. Set prior to execution of ``--tls-verify`` and | |
900 | ``--auth-user-pass-verify`` scripts. | |
901 | ||
902 | :code:`username` | |
903 | The username provided by a connecting client. Set prior to | |
904 | ``--auth-user-pass-verify`` script execution only when the | |
905 | :code:`via-env` modifier is specified. | |
906 | ||
907 | :code:`X509_{n}_{subject_field}` | |
908 | An X509 subject field from the remote peer certificate, where ``n`` is | |
909 | the verification level. Only set for TLS connections. Set prior to | |
910 | execution of ``--tls-verify`` script. This variable is similar to | |
911 | :code:`tls_id_{n}` except the component X509 subject fields are broken | |
912 | out, and no string remapping occurs on these field values (except for | |
913 | remapping of control characters to ":code:`_`"). For example, the | |
914 | following variables would be set on the OpenVPN server using the sample | |
915 | client certificate in sample-keys (client.crt). Note that the | |
916 | verification level is 0 for the client certificate and 1 for the CA | |
917 | certificate. | |
918 | ||
919 | :: | |
920 | ||
921 | X509_0_emailAddress=me@myhost.mydomain | |
922 | X509_0_CN=Test-Client | |
923 | X509_0_O=OpenVPN-TEST | |
924 | X509_0_ST=NA | |
925 | X509_0_C=KG | |
926 | X509_1_emailAddress=me@myhost.mydomain | |
927 | X509_1_O=OpenVPN-TEST | |
928 | X509_1_L=BISHKEK | |
929 | X509_1_ST=NA | |
930 | X509_1_C=KG |