1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
|
========
openvpn2
========
------------------------------------
OpenVPN 2 wrapper to OpenVPN 3 Linux
------------------------------------
:Manual section: 1
:Manual group: OpenVPN 3 Linux
SYNOPSIS
========
| ``openvpn2`` [ OPTIONS ]
| ``openvpn2`` ``-h`` | ``--help``
DESCRIPTION
===========
The **openvpn2** command line wrapper to OpenVPN 3 Linux attempts to provide a
similar command line interface as the classic **OpenVPN 2.x** releases. Since
**OpenVPN 3** does not support all the options available in **OpenVPN 2.x**,
some options is not available or will be ignored.
In addition the OpenVPN 3 Linux project provides only a client at the moment,
so all server side related options are not available.
OPTIONS
=======
-h, --help show this help message and exit
--auth ALG Authenticate packets with HMAC using message digest
algorithm alg (default=SHA1)
--auth-retry MODE
Defines how authentication failures should be handled.
Valid modes are:
:code:`none`
Disconnect on authentication failures (default)
:code:`nointeract`
Reuse already collected credentials
:code:`interact`
Ask for new credentials from the user
Currently, the OpenVPN 3 Linux client implementation
ignores this option.
--auth-user-pass Authenticate with server using username/password
--ca FILE Certificate authority file in .pem format containing
root certificate
--cd DIR Change working directory to the given directory
--cert FILE Certificate authority file in .pem format by a
Certificate Authority in ``--ca`` file
--cipher ALG Encrypt packets with cipher algorithm alg (default=BF-
CBC)
--client Configures client configuration mode (mandatory)
--comp-lzo <MODE> Use LZO compression
--compress <ALG> Compress using algorithm ALG
--config FILE Read configuration options from file
--daemon Run the VPN tunnel in the background
--dev DEV-NAME Virtual interface name to use for VPN tunnel.
Defaults to :code:`tun`. Usually ignored, as the
interface name is created on-the-fly in OpenVPN 3.
--dev-type DEV-TYPE Defines the virtual interface type. Only
:code:`tun` is supported, which is the default.
--dhcp-option OPTION Set DHCP options which can be picked up by the OS
configuring DNS, etc.
--extra-certs FILE Specify a file containing one or more PEM certs
(concatenated together) that complete the local
certificate chain.
--float Allow remote to change its IP address/port.
--hand-window SEC Handshake window. The TLS-based key exchange must
finalize within SEC seconds handshake initiation by
any peer. (Default 60 seconds)
--http-proxy ARGS
Connect to a remote host via a specified HTTP proxy.
This option takes 2 mandatory options, SERVER and PORT,
which defines the HTTP proxy and port to use.
Optional arguments are AUTH-FLAG which can be *auto-nct*
which enables clear-text passwords to be used.
OpenVPN 2.x also adds an optional AUTH-METHOD flag
as the last argument, this is auto-detected in
OpenVPN 3.
--http-proxy-user-pass FILE
Fetch HTTP proxy credentials from FILE
--ifconfig ARGS
Configures the TUN/TAP device for IPv4. This option
takes two mandatory arguments, the IPv4 address to use
and the netmask for the network.
--ifconfig-ipv6 ARGS
Configures the TUN/TAP device for IPv6. This option
takes one mandatory argument, the IPv6 address including
its PREFIX. An optional REMOTE_ENDPOINT can be given
at the end.
--ignore-unknown-options OPTION
If the listed OPTION(s) are not understood, the option
parser in the OpenVPN 3 Core library will ignore these
options instead of complaining about unknown or unused
options.
--inactive ARGS
This option takes one mandatory argument, SECONDS, which
defines how many seconds the tunnel can idle before
disconnecting. An optional BYTES argument can be added
which also takes the number of bytes passed over the
tunnel within SECONDS of inactivity. The traffic must
be higher than this minimum BYTES to keep the tunnel
alive.
--keepalive ARGS
Instructs the client to ping the server over the
OpenVPN Control Channel every PING_SECONDS. An optional
argument defines, RECONNECT_SECONDS how long it should go
before the client should attempt to reconnect if there
is no response from the server.
--key FILE
Local private key in .pem format
--key-direction DIR
Set key direction for static keys.
Valid values: :code:`0`, :code:`1`
--local HOST
Local host name or IP address to to bind against on
local side
--lport PORT TCP/UDP port number for local bind (default :code:`1194`)
--mode MODE Operational mode. Only ``client`` is accepted.
--mssfix BYTES Set upper bound on TCP MSS (Default tun-mtu size)
--ns-cert-type TYPE (DEPRECATED) Require that peer certificate is signed
with an explicit nsCertType designation. Migrate to
``--remote-cert-tls`` as soon as possible. Valid
values: :code:`client`, :code:`server`
--persist-tun Keep tun/tap device open across connection restarts
--ping SECS Ping remote once per SECS seconds
--ping-restart SECS Restart if n seconds pass without reception of remote
ping
--pkcs12 FILE PKCS#12 file containing local private key, local
certificate and optionally the root CA certificate
--port PORT TCP/UDP port number for both local and remote.
--profile-override OVERRIDE
OpenVPN 3 specific feature, allowing to set some local
overrides or disable some functionality. This option
takes two arguments, an *OVERRIDE-KEY* and an
*OVERRIDE-VALUE*. Valid keys and values are:
:code:`server-override`
A server host name
:code:`port-override`
A port number
:code:`proto-override`
Override connection protocol.
Valid values: :code:`tcp` or :code:`udp`
:code:`persist-tun`
Alternative approach to set `--persist-tun`.
:code:`ipv6`
Enable or disable IPv6 inside the tunnel.
Valid values: :code:`yes`, :code:`no` or :code:`default`
:code:`enable-legacy-algorithms`
Enables non-AEAD ciphers supported by the TLS library.
See ``openvpn3-config-manage``\(1) for details.
:code:`allow-compression`
Allows the connection to use compression. See
``openvpn3-config-manage``\(1) for details.
Valid values: :code:`yes`, :code:`no` or :code:`asym`
:code:`dns-fallback-google`
If set to true, the DNS resolver settings will include
Google DNS servers.
:code:`dns-setup-disabled`
Disable configuring pushed DNS settings.
Valid values: :code:`true` or :code:`false`
:code:`dns-sync-lookup`
Do synchronous DNS lookup instead of the default,
asynchronous.
Valid values: :code:`true` or :code:`false`
:code:`auth-fail-retry`
Try to reconnect even if the server rejected the
connection due to authentication failure.
Valid values: :code:`true` or :code:`false`
:code:`proxy-host`
Proxy server host name for the VPN tunnel
:code:`proxy-port`
Proxy server port number
:code:`proxy-username`
Username used for proxy authentication
:code:`proxy-password`
Password used for proxy authentication
:code:`proxy-auth-cleartext`
Valid values: :code:`true` or :code:`false`
These overrides are described further in
``openvpn3-config-manage``\(1)
--proto PROTO Use protocol PROTO for communicating with peer.
Valid values: :code:`udp`, :code:`tcp`
--push-peer-info Push client info to server
--redirect-gateway FLAGS
Automatically execute routing commands to redirect all
outgoing IP traffic through the VPN. Valid flags:
:code:`autolocal`, :code:`def1`, :code:`bypass-dhcp`,
:code:`bypass-dns`, :code:`block-local`, :code:`ipv4`,
:code:`!ipv4`, :code:`ipv6`, :code:`!ipv6`
--redirect-private FLAGS
Like ``--redirect-gateway``, but omit actually changing
default gateway. Valid flags: :code:`autolocal`,
:code:`def1`, :code:`bypass-dhcp`, :code:`bypass-dns`,
:code:`block-local`, :code:`ipv4`, :code:`!ipv4`,
:code:`ipv6`, :code:`!ipv6`
--remote ARGS
Defines the remote server to connect to. One
mandatory argument must be given, containing either
an *IP address* or an *hostname* to the server. An
optional *PORT* number can be given
(default: :code:`1194`) and at the end the *PROTOCOL*
can be specified (default: ``udp``). This option can
be given multiple times and the client will try all
remote entries until it is able to establish a
connection. The order of arguments are: *HOST/IP*,
*PORT* and *PROTOCOL*
--remote-cert-eku OID
Require the peer certificate to be signed with
explicit extended key usage. *OID* can be an object
identifier or OpenSSL string representation.
--remote-cert-ku ID
Require that the peer certificate was signed with
explicit key usage (*ID*). More than one ID can be
provided. Must be hexadecimal notation of integers
--remote-cert-tls TYPE
Require that peer certificate is signed with explicit
key usage and extended key usage based RFC3280 rules.
Valid values: :code:`client`, :code:`server`
--remote-random If multiple ``--remote`` options specified, choose one
randomly
--reneg-sec SECS Renegotiate data channel key after SECS seconds.
(Default: :code:`3600`)
--route ARGS
Add route to routing table after connection is
established. Multiple routes can be specified.
This option takes one mandatory argument, IP-ADDRESS
to route over the VPN. The two optional arguments
are NETMASK (default: :code:`255.255.255.255`) and the
gateway to use (defaults to use configured
``--route-gateway`` or the VPN server IP address).
--route-gateway <GW|dhcp>
Specify a default gateway for use with ``--route``.
See ``openvpn``\(8) man page for dhcp mode
--route-ipv6 ARGS
Add IPv6 route to routing table after connection is
established. Multiple routes can be specified.
This option takes one mandatory argument IP-RANGE/PREFIX.
An optional *GATEWAY* can be set, which overrides the
default server VPN IPv6 address and the second
argument which sets the route *METRIC* value.
--route-metric METRIC
Specify a default metric for use with ``--route``
--route-nopull Do not configure routes pushed by remote server
--server-poll-timeout SECS
How long to wait for a response from a remote server
during connection setup (Default: *120* seconds)
--setenv ARGS
Set a custom environmental variable to pass to script.
This takes two mandatory arguments, variable NAME
and VALUE.
--static-challenge ARGS
Enable static challenge/response protocol. This
takes one mandatory option, *MESSAGE*, which will
be presented to the user before the connection
attempt. An optional argument, *ECHO*, indicates
if the user input should be echoed back to the
user during input entry.
--tcp-queue-limit NUM
Maximum number (*NUM*)of queued TCP output packets
--tls-auth ARGS
Enables an additional HMAC authentication on TLS
control channel. This takes a mandatory argument,
*FILE*, which must be a shared secret between server
and client. The optional *KEY-DIRECTION* argument
defines which sub-key pair in *FILE* to use for HMAC
signing and verification.
Valid values are :code:`0` or :code:`1`.
--tls-cert-profile PROFILE
Sets certificate profile which defines acceptable
crypto algorithms. Valid profiles: legacy, preferred,
suiteb
--tls-client Enable TLS and assume client role during TLS
handshake. Implicitly added when using ``--client``
--tls-crypt FILE Encrypts the TLS control channel with a shared secret
key (FILE). This CANNOT be combined with ``--tls-auth``
--tls-timeout SECS Packet retransmit timeout on TLS control channel if
no ACK from remote within n seconds.
(Default: *2* seconds)
--topology TYPE Set tunnel topology type. Default is :code:`net30`.
Recommended: :code:`subnet`, but this must match the
server setting.
Valid topologies: :code:`subnet`, :code:`net30`
--tran-window SECS Transition window -- old data channel key can live
this many seconds after new after new key renegotiation
begins. (Default: :code:`3600` secs)
--tun-mtu SIZE Set TUN/TAP device MTU to SIZE and derive TCP/UDP from
it (default is 1500)
--verb LEVEL Set log verbosity level. Log levels are NOT compatible
with OpenVPN 2 ``--verb``
--verify-x509-name ARGS
Accept connections only with a host with a specific
X509 subject or CN match string. This option takes
one mandatory argument, which is a MATCH string and
an optional match FLAG.
FLAG can be:
:code:`name`
Match against complete X.509 Common Name field
:code:`name-prefix`
The MATCH value must be match the beginning of the
X.509 Common Name field. If the X.509 certificate
contains :code:`server-1.example.org`, it will be a
match if the MATCH value is :code:`server-`. It will
not be a match if values like :code:`server-2` or
:code:`.example.org` is used.
:code:`subject`
The MATCH value must be the full and complete
X.509 Subject field. This is the default behaviour.
TECH-PREVIEW OPTIONS
====================
These options are only present for testing new bleeding edge features. There are
no guarantees they will work, will not change or will not change behaviour in
the future. These options are *NOT* ready for production environments.
--enable-dco | --disable-dco
Enable or disabled the Data Channel Offload (DCO) kernel
acceleration module support. The default is disabled, but
this option is present for compatibility with OpenVPN 2.6.
The :code:`--enable-dco` option is OpenVPN 3 Linux specific
as this project does currently not automatically detect and
enable the DCO capability of the host.
IGNORED OPTIONS
===============
The options in this list will be silently ignored. Some of these options
have not yet been implemented in the OpenVPN 3 Core library and others
are not relevant any more. But none of these options will break any
existing configurations.
--auth-nocache Do not cache --askpass or --auth-user-pass in virtual
memory. Not applicable with OpenVPN 3 due to different
credentials storage model.
--chroot DIR Chroot to this directory after initialization. Not
applicable with OpenVPN 3, which uses a different
execution model.
--data-ciphers CIPHERLIST
OpenVPN 2.5 introduced this option has a replacement
to ``--ncp-ciphers``. This is primarily intended to
be used when migrating away from the prior default
BF-CBC cipher. With Negotiable Cipher Parameters
(NCP), this should not be needed in the future.
OpenVPN 3 also has a different way of handling this
situation and is believed to not have the same
connectivity issues as OpenVPN 2.4 and newer 2.x
releases could have against older OpenVPN 2.x
servers.
--data-ciphers-fallback ALG
This is tightly coupled to ``--data-ciphers`` and is
also not used nor supported by OpenVPN 3.
--dev-node NODE OpenVPN 2.x will use /dev/net/tun, /dev/tun, /dev/tap,
etc by default when creating the tun/tap interface. This
is handled differently in OpenVPN 3 Linux and is not
configurable by front-ends like ``openvpn2`` or
``openvpn3``, since the virtual network interface creation
is handled by the ``openvpn3-service-netcfg``\(8) service.
--down Run a script after the tunnel has been torn down.
Running scripts via OpenVPN 3 is not supported, and
using this option will display a warning. See the
NOTES section below for details.
--down-pre This is related to when the ``--down`` script is being
run during the disconnection. See the NOTES section
below regarding script execution in OpenVPN 3.
--explicit-exit-notify <ATTEMPTS>
On exit/restart, send exit signal to remote end.
Automatically configured with OpenVPN 3
--group GROUP Run OpenVPN with GROUP group credentials. Not needed
with OpenVPN 3 which uses a different privilege
separation approach
--mute-replay-warnings
OpenVPN 2.5 and older can hide warnings related to
replayed packets. Packet replays are not reported
in the same way in OpenVPN 3 Core library, so this
option makes no behavioural change.
--ncp-ciphers CIPHERLIST
OpenVPN 2.4 option renamed to ``--data-ciphers`` in
OpenVPN 2.5. Ignored in OpenVPN 3.
--nice LEVEL Change process priority. Not supported in OpenVPN 3
--nobind Do not bind to local address and port. This is default
behaviour in OpenVPN 3
--persist-key Do not re-read key files across connection restarts.
Not needed. OpenVPN 3 keeps keys as embedded file
elements in the configuration
--rcvbuf SIZE Set the TCP/UDP receive buffer size. Not supported in
OpenVPN 3
--resolv-retry SECS If hostname resolve fails for ``--remote``, retry
resolve for n seconds before failing. Not supported
by OpenVPN 3.
--script-security LEVEL
This option is ignored, as OpenVPN 3 itself does not
execute any external scripts.
--sndbuf SIZE Set the TCP/UDP send buffer size. Not supported in
OpenVPN 3.
--socket-flags FLAGS
Applies flags to the transport socket. Not supported
in OpenVPN 3.
--up Run a script after the tunnel has been established.
Running scripts via OpenVPN 3 is not supported, and
using this option will display a warning. See the
NOTES section below for details.
--user USER Run OpenVPN with USER user credentials. Not needed
with OpenVPN 3 which uses a different privilege
separation approach
NOTES
=====
SCRIPT EXECUTION
----------------
OpenVPN 3 does not implement any support for running external scripts or program
during its life cycle. This is by design. Running scripts is a security risk,
and needs to be handled carefully. In classic OpenVPN 2.x setups, scripts are
run with the same privileges as the ``openvpn``\(8) process. If the process is
started as root, the script may be run as root. Which is why the
``--script-security`` option is available and by default disabling running most
external programs.
This does not mean it is impossible to trigger programs to perform operations
when certain OpenVPN events occur. OpenVPN 3 Linux is using D-Bus actively and
it issues several signals as the state changes. It also means you can write
your own front-end doing its own calls how you prefer while starting and
managing the VPN session at the same time. This allows a much better
flexibility and allows one to adopt VPN session management into the execution
flow which is needed. And the implementation can do its own security
assessments on how it will tackle these scenarios.
There are at least three ways how to adopt to the OpenVPN 3 model:
1. Watching D-Bus StateChange signals for your own sessions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When a session is started, it is possible to subscribe to signals issued by the
VPN client process over D-Bus. It is only possible to subscribe to signals
related to the session owner's own sessions. These signals are sent by the
Session Manager (``net.openvpn.v3.sessions``,
``openvpn3-service-sessionmgr``\(8))
Example:
::
$ dbus-monitor --system --monitor sender=net.openvpn.v3.sessions,interface=net.openvpn.v3.sessions,member=StatusChange
2. Manage the life cycle of VPN sessions on your own
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This means wrapping the starting of VPN sessions on your own. Either you wrap
``openvpn3 session-start`` or ``openvpn2`` calls in your own scripts, or you can
connect directly to the Configuration Manager (``net.openvpn.v3.configuration``,
``openvpn3-service-configmgr``\(8)) and Session Manager
(``net.openvpn.v3.sessions``, ``openvpn3-service-sessionmgr``\(8)) to import
configuration profiles and start/stop VPN sessions as needed, as well as
subscribing to D-Bus signals as well to handle various the states a VPN session
will go through. This is fairly simple to do using the already available
openvpn3 Python module. Example code can be found in the
`OpenVPN 3 Linux source tree`_ [#srctree]_
or by studying the source code of ``openvpn2``\(1) and ``openvpn3-systemd``\(8),
which both are Python scripts.
Configurations and sessions managed via D-Bus by your own scripts can still be
further managed by the ``openvpn3``\(1) command line interface.
3. Subscribing to NetworkChange signals from `net.openvpn.v3.netcfg`_ [#netcfgsrv]_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is also a scripting possibility, which is more useful for system wide
script triggering. A program or script can subscribe to specific network change
events caused by OpenVPN sessions. These signals contains information about
virtual network interfaces which has been created or removed, IP addresses added
or removed from devices, routing configuration as well as DNS resolver changes.
For an example how to do this, see the `example script`_ [#examplescript]_
in the OpenVPN 3 Linux source directory.
**Please note** that, by default, this script must be run as ``root`` or the
``openvpn`` user on the system. It is possible to allow other users or groups
this privilege, by extending the D-Bus policy for the ``net.openvpn.v3.netcfg``
service. But granting this privilege too widely may result in unwanted
information leakage related to VPN interface configurations.
SEE ALSO
========
``openvpn``\(8)
``openvpn3``\(1)
``openvpn3-config-manage``\(1)
.. [#srctree] https://github.com/OpenVPN/openvpn3-linux/tree/master/src/tests/python
.. [#netcfgsrv] https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/dbus/dbus-service-net.openvpn.v3.netcfg.md
.. [#examplescript] https://github.com/OpenVPN/openvpn3-linux/blob/master/src/tests/python/netcfg-netchg-subscription
.. _OpenVPN 3 Linux source tree: https://github.com/OpenVPN/openvpn3-linux/tree/master/src/tests/python
.. _net.openvpn.v3.netcfg: https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/dbus/dbus-service-net.openvpn.v3.netcfg.md
.. _example script: https://github.com/OpenVPN/openvpn3-linux/blob/master/src/tests/python/netcfg-netchg-subscription
|
