5904 lines
345 KiB
HTML
5904 lines
345 KiB
HTML
<?xml version="1.0" encoding="utf-8" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="generator" content="Docutils 0.16: http://docutils.sourceforge.net/" />
|
|
<title>openvpn</title>
|
|
<style type="text/css">
|
|
|
|
/*
|
|
:Author: David Goodger (goodger@python.org)
|
|
:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $
|
|
:Copyright: This stylesheet has been placed in the public domain.
|
|
|
|
Default cascading style sheet for the HTML output of Docutils.
|
|
|
|
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
|
|
customize this style sheet.
|
|
*/
|
|
|
|
/* used to remove borders from tables and images */
|
|
.borderless, table.borderless td, table.borderless th {
|
|
border: 0 }
|
|
|
|
table.borderless td, table.borderless th {
|
|
/* Override padding for "table.docutils td" with "! important".
|
|
The right padding separates the table cells. */
|
|
padding: 0 0.5em 0 0 ! important }
|
|
|
|
.first {
|
|
/* Override more specific margin styles with "! important". */
|
|
margin-top: 0 ! important }
|
|
|
|
.last, .with-subtitle {
|
|
margin-bottom: 0 ! important }
|
|
|
|
.hidden {
|
|
display: none }
|
|
|
|
.subscript {
|
|
vertical-align: sub;
|
|
font-size: smaller }
|
|
|
|
.superscript {
|
|
vertical-align: super;
|
|
font-size: smaller }
|
|
|
|
a.toc-backref {
|
|
text-decoration: none ;
|
|
color: black }
|
|
|
|
blockquote.epigraph {
|
|
margin: 2em 5em ; }
|
|
|
|
dl.docutils dd {
|
|
margin-bottom: 0.5em }
|
|
|
|
object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
|
|
overflow: hidden;
|
|
}
|
|
|
|
/* Uncomment (and remove this text!) to get bold-faced definition list terms
|
|
dl.docutils dt {
|
|
font-weight: bold }
|
|
*/
|
|
|
|
div.abstract {
|
|
margin: 2em 5em }
|
|
|
|
div.abstract p.topic-title {
|
|
font-weight: bold ;
|
|
text-align: center }
|
|
|
|
div.admonition, div.attention, div.caution, div.danger, div.error,
|
|
div.hint, div.important, div.note, div.tip, div.warning {
|
|
margin: 2em ;
|
|
border: medium outset ;
|
|
padding: 1em }
|
|
|
|
div.admonition p.admonition-title, div.hint p.admonition-title,
|
|
div.important p.admonition-title, div.note p.admonition-title,
|
|
div.tip p.admonition-title {
|
|
font-weight: bold ;
|
|
font-family: sans-serif }
|
|
|
|
div.attention p.admonition-title, div.caution p.admonition-title,
|
|
div.danger p.admonition-title, div.error p.admonition-title,
|
|
div.warning p.admonition-title, .code .error {
|
|
color: red ;
|
|
font-weight: bold ;
|
|
font-family: sans-serif }
|
|
|
|
/* Uncomment (and remove this text!) to get reduced vertical space in
|
|
compound paragraphs.
|
|
div.compound .compound-first, div.compound .compound-middle {
|
|
margin-bottom: 0.5em }
|
|
|
|
div.compound .compound-last, div.compound .compound-middle {
|
|
margin-top: 0.5em }
|
|
*/
|
|
|
|
div.dedication {
|
|
margin: 2em 5em ;
|
|
text-align: center ;
|
|
font-style: italic }
|
|
|
|
div.dedication p.topic-title {
|
|
font-weight: bold ;
|
|
font-style: normal }
|
|
|
|
div.figure {
|
|
margin-left: 2em ;
|
|
margin-right: 2em }
|
|
|
|
div.footer, div.header {
|
|
clear: both;
|
|
font-size: smaller }
|
|
|
|
div.line-block {
|
|
display: block ;
|
|
margin-top: 1em ;
|
|
margin-bottom: 1em }
|
|
|
|
div.line-block div.line-block {
|
|
margin-top: 0 ;
|
|
margin-bottom: 0 ;
|
|
margin-left: 1.5em }
|
|
|
|
div.sidebar {
|
|
margin: 0 0 0.5em 1em ;
|
|
border: medium outset ;
|
|
padding: 1em ;
|
|
background-color: #ffffee ;
|
|
width: 40% ;
|
|
float: right ;
|
|
clear: right }
|
|
|
|
div.sidebar p.rubric {
|
|
font-family: sans-serif ;
|
|
font-size: medium }
|
|
|
|
div.system-messages {
|
|
margin: 5em }
|
|
|
|
div.system-messages h1 {
|
|
color: red }
|
|
|
|
div.system-message {
|
|
border: medium outset ;
|
|
padding: 1em }
|
|
|
|
div.system-message p.system-message-title {
|
|
color: red ;
|
|
font-weight: bold }
|
|
|
|
div.topic {
|
|
margin: 2em }
|
|
|
|
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
|
|
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
|
|
margin-top: 0.4em }
|
|
|
|
h1.title {
|
|
text-align: center }
|
|
|
|
h2.subtitle {
|
|
text-align: center }
|
|
|
|
hr.docutils {
|
|
width: 75% }
|
|
|
|
img.align-left, .figure.align-left, object.align-left, table.align-left {
|
|
clear: left ;
|
|
float: left ;
|
|
margin-right: 1em }
|
|
|
|
img.align-right, .figure.align-right, object.align-right, table.align-right {
|
|
clear: right ;
|
|
float: right ;
|
|
margin-left: 1em }
|
|
|
|
img.align-center, .figure.align-center, object.align-center {
|
|
display: block;
|
|
margin-left: auto;
|
|
margin-right: auto;
|
|
}
|
|
|
|
table.align-center {
|
|
margin-left: auto;
|
|
margin-right: auto;
|
|
}
|
|
|
|
.align-left {
|
|
text-align: left }
|
|
|
|
.align-center {
|
|
clear: both ;
|
|
text-align: center }
|
|
|
|
.align-right {
|
|
text-align: right }
|
|
|
|
/* reset inner alignment in figures */
|
|
div.align-right {
|
|
text-align: inherit }
|
|
|
|
/* div.align-center * { */
|
|
/* text-align: left } */
|
|
|
|
.align-top {
|
|
vertical-align: top }
|
|
|
|
.align-middle {
|
|
vertical-align: middle }
|
|
|
|
.align-bottom {
|
|
vertical-align: bottom }
|
|
|
|
ol.simple, ul.simple {
|
|
margin-bottom: 1em }
|
|
|
|
ol.arabic {
|
|
list-style: decimal }
|
|
|
|
ol.loweralpha {
|
|
list-style: lower-alpha }
|
|
|
|
ol.upperalpha {
|
|
list-style: upper-alpha }
|
|
|
|
ol.lowerroman {
|
|
list-style: lower-roman }
|
|
|
|
ol.upperroman {
|
|
list-style: upper-roman }
|
|
|
|
p.attribution {
|
|
text-align: right ;
|
|
margin-left: 50% }
|
|
|
|
p.caption {
|
|
font-style: italic }
|
|
|
|
p.credits {
|
|
font-style: italic ;
|
|
font-size: smaller }
|
|
|
|
p.label {
|
|
white-space: nowrap }
|
|
|
|
p.rubric {
|
|
font-weight: bold ;
|
|
font-size: larger ;
|
|
color: maroon ;
|
|
text-align: center }
|
|
|
|
p.sidebar-title {
|
|
font-family: sans-serif ;
|
|
font-weight: bold ;
|
|
font-size: larger }
|
|
|
|
p.sidebar-subtitle {
|
|
font-family: sans-serif ;
|
|
font-weight: bold }
|
|
|
|
p.topic-title {
|
|
font-weight: bold }
|
|
|
|
pre.address {
|
|
margin-bottom: 0 ;
|
|
margin-top: 0 ;
|
|
font: inherit }
|
|
|
|
pre.literal-block, pre.doctest-block, pre.math, pre.code {
|
|
margin-left: 2em ;
|
|
margin-right: 2em }
|
|
|
|
pre.code .ln { color: grey; } /* line numbers */
|
|
pre.code, code { background-color: #eeeeee }
|
|
pre.code .comment, code .comment { color: #5C6576 }
|
|
pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
|
|
pre.code .literal.string, code .literal.string { color: #0C5404 }
|
|
pre.code .name.builtin, code .name.builtin { color: #352B84 }
|
|
pre.code .deleted, code .deleted { background-color: #DEB0A1}
|
|
pre.code .inserted, code .inserted { background-color: #A3D289}
|
|
|
|
span.classifier {
|
|
font-family: sans-serif ;
|
|
font-style: oblique }
|
|
|
|
span.classifier-delimiter {
|
|
font-family: sans-serif ;
|
|
font-weight: bold }
|
|
|
|
span.interpreted {
|
|
font-family: sans-serif }
|
|
|
|
span.option {
|
|
white-space: nowrap }
|
|
|
|
span.pre {
|
|
white-space: pre }
|
|
|
|
span.problematic {
|
|
color: red }
|
|
|
|
span.section-subtitle {
|
|
/* font-size relative to parent (h1..h6 element) */
|
|
font-size: 80% }
|
|
|
|
table.citation {
|
|
border-left: solid 1px gray;
|
|
margin-left: 1px }
|
|
|
|
table.docinfo {
|
|
margin: 2em 4em }
|
|
|
|
table.docutils {
|
|
margin-top: 0.5em ;
|
|
margin-bottom: 0.5em }
|
|
|
|
table.footnote {
|
|
border-left: solid 1px black;
|
|
margin-left: 1px }
|
|
|
|
table.docutils td, table.docutils th,
|
|
table.docinfo td, table.docinfo th {
|
|
padding-left: 0.5em ;
|
|
padding-right: 0.5em ;
|
|
vertical-align: top }
|
|
|
|
table.docutils th.field-name, table.docinfo th.docinfo-name {
|
|
font-weight: bold ;
|
|
text-align: left ;
|
|
white-space: nowrap ;
|
|
padding-left: 0 }
|
|
|
|
/* "booktabs" style (no vertical lines) */
|
|
table.docutils.booktabs {
|
|
border: 0px;
|
|
border-top: 2px solid;
|
|
border-bottom: 2px solid;
|
|
border-collapse: collapse;
|
|
}
|
|
table.docutils.booktabs * {
|
|
border: 0px;
|
|
}
|
|
table.docutils.booktabs th {
|
|
border-bottom: thin solid;
|
|
text-align: left;
|
|
}
|
|
|
|
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
|
|
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
|
|
font-size: 100% }
|
|
|
|
ul.auto-toc {
|
|
list-style-type: none }
|
|
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="document" id="openvpn">
|
|
<h1 class="title">openvpn</h1>
|
|
<h2 class="subtitle" id="secure-ip-tunnel-daemon">Secure IP tunnel daemon</h2>
|
|
<table class="docinfo" frame="void" rules="none">
|
|
<col class="docinfo-name" />
|
|
<col class="docinfo-content" />
|
|
<tbody valign="top">
|
|
<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">8</td>
|
|
</tr>
|
|
<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">System Manager's Manual</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="section" id="synopsis">
|
|
<h1>SYNOPSIS</h1>
|
|
<div class="line-block">
|
|
<div class="line"><tt class="docutils literal">openvpn</tt> [ options ... ]</div>
|
|
<div class="line"><tt class="docutils literal">openvpn</tt> <tt class="docutils literal"><span class="pre">--help</span></tt></div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="introduction">
|
|
<h1>INTRODUCTION</h1>
|
|
<p>OpenVPN is an open source VPN daemon by James Yonan. Because OpenVPN
|
|
tries to be a universal VPN tool offering a great deal of flexibility,
|
|
there are a lot of options on this manual page. If you're new to
|
|
OpenVPN, you might want to skip ahead to the examples section where you
|
|
will see how to construct simple VPNs on the command line without even
|
|
needing a configuration file.</p>
|
|
<p>Also note that there's more documentation and examples on the OpenVPN
|
|
web site: <a class="reference external" href="https://openvpn.net/">https://openvpn.net/</a></p>
|
|
<p>And if you would like to see a shorter version of this manual, see the
|
|
openvpn usage message which can be obtained by running <strong>openvpn</strong>
|
|
without any parameters.</p>
|
|
</div>
|
|
<div class="section" id="description">
|
|
<h1>DESCRIPTION</h1>
|
|
<p>OpenVPN is a robust and highly flexible VPN daemon. OpenVPN supports
|
|
SSL/TLS security, ethernet bridging, TCP or UDP tunnel transport through
|
|
proxies or NAT, support for dynamic IP addresses and DHCP, scalability
|
|
to hundreds or thousands of users, and portability to most major OS
|
|
platforms.</p>
|
|
<p>OpenVPN is tightly bound to the OpenSSL library, and derives much of its
|
|
crypto capabilities from it.</p>
|
|
<p>OpenVPN supports conventional encryption using a pre-shared secret key
|
|
<strong>(Static Key mode)</strong> or public key security <strong>(SSL/TLS mode)</strong> using
|
|
client & server certificates. OpenVPN also supports non-encrypted
|
|
TCP/UDP tunnels.</p>
|
|
<p>OpenVPN is designed to work with the <strong>TUN/TAP</strong> virtual networking
|
|
interface that exists on most platforms.</p>
|
|
<p>Overall, OpenVPN aims to offer many of the key features of IPSec but
|
|
with a relatively lightweight footprint.</p>
|
|
</div>
|
|
<div class="section" id="options">
|
|
<h1>OPTIONS</h1>
|
|
<p>OpenVPN allows any option to be placed either on the command line or in
|
|
a configuration file. Though all command line options are preceded by a
|
|
double-leading-dash ("--"), this prefix can be removed when an option is
|
|
placed in a configuration file.</p>
|
|
<div class="section" id="generic-options">
|
|
<h2>Generic Options</h2>
|
|
<p>This section covers generic options which are accessible regardless of
|
|
which mode OpenVPN is configured as.</p>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--help</span></kbd></td>
|
|
<td>Show options.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--auth-nocache</span></kbd></td>
|
|
<td><p class="first">Don't cache <tt class="docutils literal"><span class="pre">--askpass</span></tt> or <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> username/passwords in
|
|
virtual memory.</p>
|
|
<p>If specified, this directive will cause OpenVPN to immediately forget
|
|
username/password inputs after they are used. As a result, when OpenVPN
|
|
needs a username/password, it will prompt for input from stdin, which
|
|
may be multiple times during the duration of an OpenVPN session.</p>
|
|
<p>When using <tt class="docutils literal"><span class="pre">--auth-nocache</span></tt> in combination with a user/password file
|
|
and <tt class="docutils literal"><span class="pre">--chroot</span></tt> or <tt class="docutils literal"><span class="pre">--daemon</span></tt>, make sure to use an absolute path.</p>
|
|
<p class="last">This directive does not affect the <tt class="docutils literal"><span class="pre">--http-proxy</span></tt> username/password.
|
|
It is always cached.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--cd <var>dir</var></span></kbd></td>
|
|
<td><p class="first">Change directory to <tt class="docutils literal">dir</tt> prior to reading any files such as
|
|
configuration files, key files, scripts, etc. <tt class="docutils literal">dir</tt> should be an
|
|
absolute path, with a leading "/", and without any references to the
|
|
current directory such as <code>.</code> or <code>..</code>.</p>
|
|
<p class="last">This option is useful when you are running OpenVPN in <tt class="docutils literal"><span class="pre">--daemon</span></tt> mode,
|
|
and you want to consolidate all of your OpenVPN control files in one
|
|
location.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--chroot <var>dir</var></span></kbd></td>
|
|
<td><p class="first">Chroot to <tt class="docutils literal">dir</tt> after initialization. <tt class="docutils literal"><span class="pre">--chroot</span></tt> essentially
|
|
redefines <tt class="docutils literal">dir</tt> as being the top level directory tree (/). OpenVPN
|
|
will therefore be unable to access any files outside this tree. This can
|
|
be desirable from a security standpoint.</p>
|
|
<p>Since the chroot operation is delayed until after initialization, most
|
|
OpenVPN options that reference files will operate in a pre-chroot
|
|
context.</p>
|
|
<p>In many cases, the <tt class="docutils literal">dir</tt> parameter can point to an empty directory,
|
|
however complications can result when scripts or restarts are executed
|
|
after the chroot operation.</p>
|
|
<p class="last">Note: The SSL library will probably need /dev/urandom to be available
|
|
inside the chroot directory <tt class="docutils literal">dir</tt>. This is because SSL libraries
|
|
occasionally need to collect fresh random. Newer linux kernels and some
|
|
BSDs implement a getrandom() or getentropy() syscall that removes the
|
|
need for /dev/urandom to be available.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--config <var>file</var></span></kbd></td>
|
|
<td><p class="first">Load additional config options from <tt class="docutils literal">file</tt> where each line corresponds
|
|
to one command line option, but with the leading '--' removed.</p>
|
|
<p>If <tt class="docutils literal"><span class="pre">--config</span> file</tt> is the only option to the openvpn command, the
|
|
<tt class="docutils literal"><span class="pre">--config</span></tt> can be removed, and the command can be given as <tt class="docutils literal">openvpn
|
|
file</tt></p>
|
|
<p>Note that configuration files can be nested to a reasonable depth.</p>
|
|
<p>Double quotation or single quotation characters ("", '') can be used to
|
|
enclose single parameters containing whitespace, and "#" or ";"
|
|
characters in the first column can be used to denote comments.</p>
|
|
<p>Note that OpenVPN 2.0 and higher performs backslash-based shell escaping
|
|
for characters not in single quotations, so the following mappings
|
|
should be observed:</p>
|
|
<pre class="literal-block">
|
|
\\ Maps to a single backslash character (\).
|
|
\" Pass a literal doublequote character ("), don't
|
|
interpret it as enclosing a parameter.
|
|
\[SPACE] Pass a literal space or tab character, don't
|
|
interpret it as a parameter delimiter.
|
|
</pre>
|
|
<p>For example on Windows, use double backslashes to represent pathnames:</p>
|
|
<pre class="literal-block">
|
|
secret "c:\\OpenVPN\\secret.key"
|
|
</pre>
|
|
<p>For examples of configuration files, see
|
|
<a class="reference external" href="https://openvpn.net/community-resources/how-to/">https://openvpn.net/community-resources/how-to/</a></p>
|
|
<p>Here is an example configuration file:</p>
|
|
<pre class="last literal-block">
|
|
#
|
|
# Sample OpenVPN configuration file for
|
|
# using a pre-shared static key.
|
|
#
|
|
# '#' or ';' may be used to delimit comments.
|
|
|
|
# Use a dynamic tun device.
|
|
dev tun
|
|
|
|
# Our remote peer
|
|
remote mypeer.mydomain
|
|
|
|
# 10.1.0.1 is our local VPN endpoint
|
|
# 10.1.0.2 is our remote VPN endpoint
|
|
ifconfig 10.1.0.1 10.1.0.2
|
|
|
|
# Our pre-shared static key
|
|
secret static.key
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--daemon <var>progname</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Become a daemon after all initialization functions are completed. This
|
|
option will cause all message and error output to be sent to the syslog
|
|
file (such as <code>/var/log/messages</code>), except for the output of
|
|
scripts and ifconfig commands, which will go to <code>/dev/null</code> unless
|
|
otherwise redirected. The syslog redirection occurs immediately at the
|
|
point that <tt class="docutils literal"><span class="pre">--daemon</span></tt> is parsed on the command line even though the
|
|
daemonization point occurs later. If one of the <tt class="docutils literal"><span class="pre">--log</span></tt> options is
|
|
present, it will supersede syslog redirection.</p>
|
|
<p>The optional <tt class="docutils literal">progname</tt> parameter will cause OpenVPN to report its
|
|
program name to the system logger as <tt class="docutils literal">progname</tt>. This can be useful in
|
|
linking OpenVPN messages in the syslog file with specific tunnels. When
|
|
unspecified, <tt class="docutils literal">progname</tt> defaults to "openvpn".</p>
|
|
<p>When OpenVPN is run with the <tt class="docutils literal"><span class="pre">--daemon</span></tt> option, it will try to delay
|
|
daemonization until the majority of initialization functions which are
|
|
capable of generating fatal errors are complete. This means that
|
|
initialization scripts can test the return status of the openvpn command
|
|
for a fairly reliable indication of whether the command has correctly
|
|
initialized and entered the packet forwarding event loop.</p>
|
|
<p>In OpenVPN, the vast majority of errors which occur after initialization
|
|
are non-fatal.</p>
|
|
<p>Note: as soon as OpenVPN has daemonized, it can not ask for usernames,
|
|
passwords, or key pass phrases anymore. This has certain consequences,
|
|
namely that using a password-protected private key will fail unless the
|
|
<tt class="docutils literal"><span class="pre">--askpass</span></tt> option is used to tell OpenVPN to ask for the pass phrase
|
|
(this requirement is new in v2.3.7, and is a consequence of calling
|
|
daemon() before initializing the crypto layer).</p>
|
|
<p class="last">Further, using <tt class="docutils literal"><span class="pre">--daemon</span></tt> together with <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> (entered
|
|
on console) and <tt class="docutils literal"><span class="pre">--auth-nocache</span></tt> will fail as soon as key
|
|
renegotiation (and reauthentication) occurs.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--disable-occ</span></kbd></td>
|
|
<td><p class="first">Don't output a warning message if option inconsistencies are detected
|
|
between peers. An example of an option inconsistency would be where one
|
|
peer uses <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> while the other peer uses <tt class="docutils literal"><span class="pre">--dev</span> tap</tt>.</p>
|
|
<p class="last">Use of this option is discouraged, but is provided as a temporary fix in
|
|
situations where a recent version of OpenVPN must connect to an old
|
|
version.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--engine <var>engine-name</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Enable OpenSSL hardware-based crypto engine functionality.</p>
|
|
<p class="last">If <tt class="docutils literal"><span class="pre">engine-name</span></tt> is specified, use a specific crypto engine. Use the
|
|
<tt class="docutils literal"><span class="pre">--show-engines</span></tt> standalone option to list the crypto engines which
|
|
are supported by OpenSSL.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--fast-io</span></kbd></td>
|
|
<td><p class="first">(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
|
|
poll/epoll/select prior to the write operation. The purpose of such a
|
|
call would normally be to block until the device or socket is ready to
|
|
accept the write. Such blocking is unnecessary on some platforms which
|
|
don't support write blocking on UDP sockets or TUN/TAP devices. In such
|
|
cases, one can optimize the event loop by avoiding the poll/epoll/select
|
|
call, improving CPU efficiency by 5% to 10%.</p>
|
|
<p class="last">This option can only be used on non-Windows systems, when <tt class="docutils literal"><span class="pre">--proto</span>
|
|
udp</tt> is specified, and when <tt class="docutils literal"><span class="pre">--shaper</span></tt> is NOT specified.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--group <var>group</var></span></kbd></td>
|
|
<td>Similar to the <tt class="docutils literal"><span class="pre">--user</span></tt> option, this option changes the group ID of
|
|
the OpenVPN process to <tt class="docutils literal">group</tt> after initialization.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ignore-unknown-option <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
ignore-unknown-options opt1 opt2 opt3 ... optN
|
|
</pre>
|
|
<p>When one of options <tt class="docutils literal">opt1 ... optN</tt> is encountered in the configuration
|
|
file the configuration file parsing does not fail if this OpenVPN version
|
|
does not support the option. Multiple <tt class="docutils literal"><span class="pre">--ignore-unknown-option</span></tt> options
|
|
can be given to support a larger number of options to ignore.</p>
|
|
<p>This option should be used with caution, as there are good security
|
|
reasons for having OpenVPN fail if it detects problems in a config file.
|
|
Having said that, there are valid reasons for wanting new software
|
|
features to gracefully degrade when encountered by older software
|
|
versions.</p>
|
|
<p class="last"><tt class="docutils literal"><span class="pre">--ignore-unknown-option</span></tt> is available since OpenVPN 2.3.3.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--iproute <var>cmd</var></span></kbd></td>
|
|
<td>Set alternate command to execute instead of default <tt class="docutils literal">iproute2</tt> command.
|
|
May be used in order to execute OpenVPN in unprivileged environment.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--keying-material-exporter <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Save Exported Keying Material [RFC5705] of len bytes (must be between 16
|
|
and 4095 bytes) using <tt class="docutils literal">label</tt> in environment
|
|
(<code>exported_keying_material</code>) for use by plugins in
|
|
<code>OPENVPN_PLUGIN_TLS_FINAL</code> callback.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
keying-material-exporter label len
|
|
</pre>
|
|
<p class="last">Note that exporter <tt class="docutils literal">labels</tt> have the potential to collide with existing
|
|
PRF labels. In order to prevent this, labels <em>MUST</em> begin with
|
|
<code>EXPORTER</code>.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--mlock</span></kbd></td>
|
|
<td><p class="first">Disable paging by calling the POSIX mlockall function. Requires that
|
|
OpenVPN be initially run as root (though OpenVPN can subsequently
|
|
downgrade its UID using the <tt class="docutils literal"><span class="pre">--user</span></tt> option).</p>
|
|
<p>Using this option ensures that key material and tunnel data are never
|
|
written to disk due to virtual memory paging operations which occur
|
|
under most modern operating systems. It ensures that even if an attacker
|
|
was able to crack the box running OpenVPN, he would not be able to scan
|
|
the system swap file to recover previously used ephemeral keys, which
|
|
are used for a period of time governed by the <tt class="docutils literal"><span class="pre">--reneg</span></tt> options (see
|
|
below), then are discarded.</p>
|
|
<p>The downside of using <tt class="docutils literal"><span class="pre">--mlock</span></tt> is that it will reduce the amount of
|
|
physical memory available to other applications.</p>
|
|
<p class="last">The limit on how much memory can be locked and how that limit
|
|
is enforced are OS-dependent. On Linux the default limit that an
|
|
unprivileged process may lock (RLIMIT_MEMLOCK) is low, and if
|
|
privileges are dropped later, future memory allocations will very
|
|
likely fail. The limit can be increased using ulimit or systemd
|
|
directives depending on how OpenVPN is started.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--nice <var>n</var></span></kbd></td>
|
|
<td>Change process priority after initialization (<tt class="docutils literal">n</tt> greater than 0 is
|
|
lower priority, <tt class="docutils literal">n</tt> less than zero is higher priority).</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--persist-key</span></kbd></td>
|
|
<td><p class="first">Don't re-read key files across <code>SIGUSR1</code> or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>.</p>
|
|
<p>This option can be combined with <tt class="docutils literal"><span class="pre">--user</span> nobody</tt> to allow restarts
|
|
triggered by the <code>SIGUSR1</code> signal. Normally if you drop root
|
|
privileges in OpenVPN, the daemon cannot be restarted since it will now
|
|
be unable to re-read protected key files.</p>
|
|
<p class="last">This option solves the problem by persisting keys across <code>SIGUSR1</code>
|
|
resets, so they don't need to be re-read.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--remap-usr1 <var>signal</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Control whether internally or externally generated <code>SIGUSR1</code> signals
|
|
are remapped to <code>SIGHUP</code> (restart without persisting state) or
|
|
SIGTERM (exit).</p>
|
|
<p class="last"><tt class="docutils literal">signal</tt> can be set to <code>SIGHUP</code> or <code>SIGTERM</code>. By default,
|
|
no remapping occurs.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--script-security <var>level</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">This directive offers policy-level control over OpenVPN's usage of
|
|
external programs and scripts. Lower <tt class="docutils literal">level</tt> values are more
|
|
restrictive, higher values are more permissive. Settings for <tt class="docutils literal">level</tt>:</p>
|
|
<dl class="docutils">
|
|
<dt><code>0</code></dt>
|
|
<dd>Strictly no calling of external programs.</dd>
|
|
<dt><code>1</code></dt>
|
|
<dd>(Default) Only call built-in executables such as ifconfig,
|
|
ip, route, or netsh.</dd>
|
|
<dt><code>2</code></dt>
|
|
<dd>Allow calling of built-in executables and user-defined
|
|
scripts.</dd>
|
|
<dt><code>3</code></dt>
|
|
<dd>Allow passwords to be passed to scripts via environmental
|
|
variables (potentially unsafe).</dd>
|
|
</dl>
|
|
<p>OpenVPN releases before v2.3 also supported a <tt class="docutils literal">method</tt> flag which
|
|
indicated how OpenVPN should call external commands and scripts. This
|
|
could be either <code>execve</code> or <code>system</code>. As of OpenVPN 2.3, this
|
|
flag is no longer accepted. In most *nix environments the execve()
|
|
approach has been used without any issues.</p>
|
|
<p>Some directives such as <tt class="docutils literal"><span class="pre">--up</span></tt> allow options to be passed to the
|
|
external script. In these cases make sure the script name does not
|
|
contain any spaces or the configuration parser will choke because it
|
|
can't determine where the script name ends and script options start.</p>
|
|
<p>To run scripts in Windows in earlier OpenVPN versions you needed to
|
|
either add a full path to the script interpreter which can parse the
|
|
script or use the <tt class="docutils literal">system</tt> flag to run these scripts. As of OpenVPN
|
|
2.3 it is now a strict requirement to have full path to the script
|
|
interpreter when running non-executables files. This is not needed for
|
|
executable files, such as .exe, .com, .bat or .cmd files. For example,
|
|
if you have a Visual Basic script, you must use this syntax now:</p>
|
|
<pre class="literal-block">
|
|
--up 'C:\\Windows\\System32\\wscript.exe C:\\Program\ Files\\OpenVPN\\config\\my-up-script.vbs'
|
|
</pre>
|
|
<p>Please note the single quote marks and the escaping of the backslashes
|
|
(\) and the space character.</p>
|
|
<p class="last">The reason the support for the <code>system</code> flag was removed is due to
|
|
the security implications with shell expansions when executing scripts
|
|
via the <code>system()</code> call.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--setcon <var>context</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Apply SELinux <tt class="docutils literal">context</tt> after initialization. This essentially
|
|
provides the ability to restrict OpenVPN's rights to only network I/O
|
|
operations, thanks to SELinux. This goes further than <tt class="docutils literal"><span class="pre">--user</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">--chroot</span></tt> in that those two, while being great security features,
|
|
unfortunately do not protect against privilege escalation by
|
|
exploitation of a vulnerable system call. You can of course combine all
|
|
three, but please note that since setcon requires access to /proc you
|
|
will have to provide it inside the chroot directory (e.g. with mount
|
|
--bind).</p>
|
|
<p>Since the setcon operation is delayed until after initialization,
|
|
OpenVPN can be restricted to just network-related system calls, whereas
|
|
by applying the context before startup (such as the OpenVPN one provided
|
|
in the SELinux Reference Policies) you will have to allow many things
|
|
required only during initialization.</p>
|
|
<p class="last">Like with chroot, complications can result when scripts or restarts are
|
|
executed after the setcon operation, which is why you should really
|
|
consider using the <tt class="docutils literal"><span class="pre">--persist-key</span></tt> and <tt class="docutils literal"><span class="pre">--persist-tun</span></tt> options.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--status <var>args</var></span></kbd></td>
|
|
<td><p class="first">Write operational status to <tt class="docutils literal">file</tt> every <tt class="docutils literal">n</tt> seconds.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
status file
|
|
status file n
|
|
</pre>
|
|
<p>Status can also be written to the syslog by sending a <code>SIGUSR2</code>
|
|
signal.</p>
|
|
<p>With multi-client capability enabled on a server, the status file
|
|
includes a list of clients and a routing table. The output format can be
|
|
controlled by the <tt class="docutils literal"><span class="pre">--status-version</span></tt> option in that case.</p>
|
|
<p class="last">For clients or instances running in point-to-point mode, it will contain
|
|
the traffic statistics.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--status-version <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Set the status file format version number to <tt class="docutils literal">n</tt>.</p>
|
|
<p>This only affects the status file on servers with multi-client
|
|
capability enabled. Valid status version values:</p>
|
|
<dl class="last docutils">
|
|
<dt><code>1</code></dt>
|
|
<dd>Traditional format (default). The client list contains the
|
|
following fields comma-separated: Common Name, Real Address, Bytes
|
|
Received, Bytes Sent, Connected Since.</dd>
|
|
<dt><code>2</code></dt>
|
|
<dd>A more reliable format for external processing. Compared to
|
|
version <code>1</code>, the client list contains some additional fields:
|
|
Virtual Address, Virtual IPv6 Address, Username, Client ID, Peer ID,
|
|
Data Channel Cipher. Future versions may extend the number of fields.</dd>
|
|
<dt><code>3</code></dt>
|
|
<dd>Identical to <code>2</code>, but fields are tab-separated.</dd>
|
|
</dl>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--test-crypto</span></kbd></td>
|
|
<td><p class="first">Do a self-test of OpenVPN's crypto options by encrypting and decrypting
|
|
test packets using the data channel encryption options specified above.
|
|
This option does not require a peer to function, and therefore can be
|
|
specified without <tt class="docutils literal"><span class="pre">--dev</span></tt> or <tt class="docutils literal"><span class="pre">--remote</span></tt>.</p>
|
|
<p>The typical usage of <tt class="docutils literal"><span class="pre">--test-crypto</span></tt> would be something like this:</p>
|
|
<pre class="literal-block">
|
|
openvpn --test-crypto --secret key
|
|
</pre>
|
|
<p>or</p>
|
|
<pre class="literal-block">
|
|
openvpn --test-crypto --secret key --verb 9
|
|
</pre>
|
|
<p class="last">This option is very useful to test OpenVPN after it has been ported to a
|
|
new platform, or to isolate problems in the compiler, OpenSSL crypto
|
|
library, or OpenVPN's crypto code. Since it is a self-test mode,
|
|
problems with encryption and authentication can be debugged
|
|
independently of network and tunnel issues.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--tmp-dir <var>dir</var></span></kbd></td>
|
|
<td><p class="first">Specify a directory <tt class="docutils literal">dir</tt> for temporary files. This directory will be
|
|
used by openvpn processes and script to communicate temporary data with
|
|
openvpn main process. Note that the directory must be writable by the
|
|
OpenVPN process after it has dropped it's root privileges.</p>
|
|
<p>This directory will be used by in the following cases:</p>
|
|
<ul class="last simple">
|
|
<li><tt class="docutils literal"><span class="pre">--client-connect</span></tt> scripts and <code>OPENVPN_PLUGIN_CLIENT_CONNECT</code>
|
|
plug-in hook to dynamically generate client-specific configuration
|
|
<code>client_connect_config_file</code> and return success/failure via
|
|
<code>client_connect_deferred_file</code> when using deferred client connect
|
|
method</li>
|
|
<li><code>OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY</code> plug-in hooks returns
|
|
success/failure via <code>auth_control_file</code> when using deferred auth
|
|
method</li>
|
|
<li><code>OPENVPN_PLUGIN_ENABLE_PF</code> plugin hook to pass filtering rules
|
|
via <tt class="docutils literal">pf_file</tt></li>
|
|
</ul>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--use-prediction-resistance</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Enable prediction resistance on mbed TLS's RNG.</p>
|
|
<p>Enabling prediction resistance causes the RNG to reseed in each call for
|
|
random. Reseeding this often can quickly deplete the kernel entropy
|
|
pool.</p>
|
|
<p class="last">If you need this option, please consider running a daemon that adds
|
|
entropy to the kernel pool.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--user <var>user</var></span></kbd></td>
|
|
<td><p class="first">Change the user ID of the OpenVPN process to <tt class="docutils literal">user</tt> after
|
|
initialization, dropping privileges in the process. This option is
|
|
useful to protect the system in the event that some hostile party was
|
|
able to gain control of an OpenVPN session. Though OpenVPN's security
|
|
features make this unlikely, it is provided as a second line of defense.</p>
|
|
<p class="last">By setting <tt class="docutils literal">user</tt> to <code>nobody</code> or somebody similarly unprivileged,
|
|
the hostile party would be limited in what damage they could cause. Of
|
|
course once you take away privileges, you cannot return them to an
|
|
OpenVPN session. This means, for example, that if you want to reset an
|
|
OpenVPN daemon with a <code>SIGUSR1</code> signal (for example in response to
|
|
a DHCP reset), you should make use of one or more of the <tt class="docutils literal"><span class="pre">--persist</span></tt>
|
|
options to ensure that OpenVPN doesn't need to execute any privileged
|
|
operations in order to restart (such as re-reading key files or running
|
|
<tt class="docutils literal">ifconfig</tt> on the TUN device).</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--writepid <var>file</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Write OpenVPN's main process ID to <tt class="docutils literal">file</tt>.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="log-options">
|
|
<h2>Log options</h2>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--echo <var>parms</var></span></kbd></td>
|
|
<td><p class="first">Echo <tt class="docutils literal">parms</tt> to log output.</p>
|
|
<p class="last">Designed to be used to send messages to a controlling application which
|
|
is receiving the OpenVPN log output.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--errors-to-stderr</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Output errors to stderr instead of stdout unless log output is
|
|
redirected by one of the <tt class="docutils literal"><span class="pre">--log</span></tt> options.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--log <var>file</var></span></kbd></td>
|
|
<td><p class="first">Output logging messages to <tt class="docutils literal">file</tt>, including output to stdout/stderr
|
|
which is generated by called scripts. If <tt class="docutils literal">file</tt> already exists it will
|
|
be truncated. This option takes effect immediately when it is parsed in
|
|
the command line and will supersede syslog output if <tt class="docutils literal"><span class="pre">--daemon</span></tt> or
|
|
<tt class="docutils literal"><span class="pre">--inetd</span></tt> is also specified. This option is persistent over the entire
|
|
course of an OpenVPN instantiation and will not be reset by
|
|
<code>SIGHUP</code>, <code>SIGUSR1</code>, or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>.</p>
|
|
<p class="last">Note that on Windows, when OpenVPN is started as a service, logging
|
|
occurs by default without the need to specify this option.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--log-append <var>file</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Append logging messages to <tt class="docutils literal">file</tt>. If <tt class="docutils literal">file</tt> does not exist, it will
|
|
be created. This option behaves exactly like <tt class="docutils literal"><span class="pre">--log</span></tt> except that it
|
|
appends to rather than truncating the log file.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--machine-readable-output</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Always write timestamps and message flags to log messages, even when
|
|
they otherwise would not be prefixed. In particular, this applies to log
|
|
messages sent to stdout.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--mute <var>n</var></span></kbd></td>
|
|
<td>Log at most <tt class="docutils literal">n</tt> consecutive messages in the same category. This is
|
|
useful to limit repetitive logging of similar message types.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--mute-replay-warnings</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Silence the output of replay warnings, which are a common false alarm on
|
|
WiFi networks. This option preserves the security of the replay
|
|
protection code without the verbosity associated with warnings about
|
|
duplicate packets.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--suppress-timestamps</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Avoid writing timestamps to log messages, even when they otherwise would
|
|
be prepended. In particular, this applies to log messages sent to
|
|
stdout.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--syslog <var>progname</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Direct log output to system logger, but do not become a daemon. See
|
|
<tt class="docutils literal"><span class="pre">--daemon</span></tt> directive above for description of <tt class="docutils literal">progname</tt> parameter.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--verb <var>n</var></span></kbd></td>
|
|
<td><p class="first">Set output verbosity to <tt class="docutils literal">n</tt> (default <code>1</code>). Each level shows all
|
|
info from the previous levels. Level <code>3</code> is recommended if you want
|
|
a good summary of what's happening without being swamped by output.</p>
|
|
<dl class="last docutils">
|
|
<dt><code>0</code></dt>
|
|
<dd>No output except fatal errors.</dd>
|
|
<dt><code>1</code> to <code>4</code></dt>
|
|
<dd>Normal usage range.</dd>
|
|
<dt><code>5</code></dt>
|
|
<dd>Outputs <code>R</code> and <code>W</code> characters to the console for
|
|
each packet read and write, uppercase is used for TCP/UDP
|
|
packets and lowercase is used for TUN/TAP packets.</dd>
|
|
<dt><code>6</code> to <code>11</code></dt>
|
|
<dd>Debug info range (see <code>errlevel.h</code> in the source code for
|
|
additional information on debug levels).</dd>
|
|
</dl>
|
|
</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="protocol-options">
|
|
<h2>Protocol options</h2>
|
|
<p>Options in this section affect features available in the OpenVPN wire
|
|
protocol. Many of these options also define the encryption options
|
|
of the data channel in the OpenVPN wire protocol. These options must be
|
|
configured in a compatible way between both the local and remote side.</p>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--allow-compression <var>mode</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">As described in the <tt class="docutils literal"><span class="pre">--compress</span></tt> option, compression is a potentially
|
|
dangerous option. This option allows controlling the behaviour of
|
|
OpenVPN when compression is used and allowed.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
allow-compression
|
|
allow-compression mode
|
|
</pre>
|
|
<p>The <tt class="docutils literal">mode</tt> argument can be one of the following values:</p>
|
|
<dl class="last docutils">
|
|
<dt><code>asym</code> (default)</dt>
|
|
<dd>OpenVPN will only <em>decompress downlink packets</em> but <em>not compress
|
|
uplink packets</em>. This also allows migrating to disable compression
|
|
when changing both server and client configurations to remove
|
|
compression at the same time is not a feasible option.</dd>
|
|
<dt><code>no</code></dt>
|
|
<dd>OpenVPN will refuse any non-stub compression.</dd>
|
|
<dt><code>yes</code></dt>
|
|
<dd>OpenVPN will send and receive compressed packets.</dd>
|
|
</dl>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--auth <var>alg</var></span></kbd></td>
|
|
<td><p class="first">Authenticate data channel packets and (if enabled) <tt class="docutils literal"><span class="pre">tls-auth</span></tt> control
|
|
channel packets with HMAC using message digest algorithm <tt class="docutils literal">alg</tt>. (The
|
|
default is <tt class="docutils literal">SHA1</tt> ). HMAC is a commonly used message authentication
|
|
algorithm (MAC) that uses a data string, a secure hash algorithm and a
|
|
key to produce a digital signature.</p>
|
|
<p>The OpenVPN data channel protocol uses encrypt-then-mac (i.e. first
|
|
encrypt a packet then HMAC the resulting ciphertext), which prevents
|
|
padding oracle attacks.</p>
|
|
<p>If an AEAD cipher mode (e.g. GCM) is chosen then the specified <tt class="docutils literal"><span class="pre">--auth</span></tt>
|
|
algorithm is ignored for the data channel and the authentication method
|
|
of the AEAD cipher is used instead. Note that <tt class="docutils literal">alg</tt> still specifies
|
|
the digest used for <tt class="docutils literal"><span class="pre">tls-auth</span></tt>.</p>
|
|
<p>In static-key encryption mode, the HMAC key is included in the key file
|
|
generated by <tt class="docutils literal"><span class="pre">--genkey</span></tt>. In TLS mode, the HMAC key is dynamically
|
|
generated and shared between peers via the TLS control channel. If
|
|
OpenVPN receives a packet with a bad HMAC it will drop the packet. HMAC
|
|
usually adds 16 or 20 bytes per packet. Set <tt class="docutils literal">alg=none</tt> to disable
|
|
authentication.</p>
|
|
<p class="last">For more information on HMAC see
|
|
<a class="reference external" href="http://www.cs.ucsd.edu/users/mihir/papers/hmac.html">http://www.cs.ucsd.edu/users/mihir/papers/hmac.html</a></p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--cipher <var>alg</var></span></kbd></td>
|
|
<td><p class="first">This option is deprecated for server-client mode. <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt>
|
|
or possibly <cite>--data-ciphers-fallback`</cite> should be used instead.</p>
|
|
<p>Encrypt data channel packets with cipher algorithm <tt class="docutils literal">alg</tt>.</p>
|
|
<p>The default is <code>BF-CBC</code>, an abbreviation for Blowfish in Cipher
|
|
Block Chaining mode. When cipher negotiation (NCP) is allowed,
|
|
OpenVPN 2.4 and newer on both client and server side will automatically
|
|
upgrade to <code>AES-256-GCM</code>. See <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">--ncp-disable</span></tt> for more details on NCP.</p>
|
|
<p>Using <code>BF-CBC</code> is no longer recommended, because of its 64-bit
|
|
block size. This small block size allows attacks based on collisions, as
|
|
demonstrated by SWEET32. See
|
|
<a class="reference external" href="https://community.openvpn.net/openvpn/wiki/SWEET32">https://community.openvpn.net/openvpn/wiki/SWEET32</a>
|
|
for details. Due to this, support for <code>BF-CBC</code>, <code>DES</code>,
|
|
<code>CAST5</code>, <code>IDEA</code> and <code>RC2</code> ciphers will be removed in
|
|
OpenVPN 2.6.</p>
|
|
<p>To see other ciphers that are available with OpenVPN, use the
|
|
<tt class="docutils literal"><span class="pre">--show-ciphers</span></tt> option.</p>
|
|
<p class="last">Set <tt class="docutils literal">alg</tt> to <code>none</code> to disable encryption.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--compress <var>algorithm</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first"><strong>DEPRECATED</strong> Enable a compression algorithm. Compression is generally
|
|
not recommended. VPN tunnels which use compression are susceptible to
|
|
the VORALCE attack vector.</p>
|
|
<p>The <tt class="docutils literal">algorithm</tt> parameter may be <code>lzo</code>, <code>lz4</code>,
|
|
<code>lz4-v2</code>, <code>stub</code>, <code>stub-v2</code> or empty.
|
|
LZO and LZ4 are different compression algorithms, with LZ4 generally
|
|
offering the best performance with least CPU usage.</p>
|
|
<p>The <code>lz4-v2</code> and <code>stub-v2</code> variants implement a better
|
|
framing that does not add overhead when packets cannot be compressed. All
|
|
other variants always add one extra framing byte compared to no
|
|
compression framing.</p>
|
|
<p>If the <tt class="docutils literal">algorithm</tt> parameter is <code>stub</code>, <code>stub-v2</code> or empty,
|
|
compression will be turned off, but the packet framing for compression
|
|
will still be enabled, allowing a different setting to be pushed later.
|
|
Additionally, <code>stub</code> and <code>stub-v2</code> wil disable announcing
|
|
<tt class="docutils literal">lzo</tt> and <tt class="docutils literal">lz4</tt> compression support via <em>IV_</em> variables to the
|
|
server.</p>
|
|
<p>Note: the <code>stub</code> (or empty) option is NOT compatible with the older
|
|
option <tt class="docutils literal"><span class="pre">--comp-lzo</span> no</tt>.</p>
|
|
<p><strong>*Security Considerations*</strong></p>
|
|
<p class="last">Compression and encryption is a tricky combination. If an attacker knows
|
|
or is able to control (parts of) the plain-text of packets that contain
|
|
secrets, the attacker might be able to extract the secret if compression
|
|
is enabled. See e.g. the <em>CRIME</em> and <em>BREACH</em> attacks on TLS and
|
|
<em>VORACLE</em> on VPNs which also leverage to break encryption. If you are not
|
|
entirely sure that the above does not apply to your traffic, you are
|
|
advised to <em>not</em> enable compression.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--comp-lzo <var>mode</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first"><strong>DEPRECATED</strong> Enable LZO compression algorithm. Compression is
|
|
generally not recommended. VPN tunnels which uses compression are
|
|
suspectible to the VORALCE attack vector.</p>
|
|
<p>Use LZO compression -- may add up to 1 byte per packet for incompressible
|
|
data. <tt class="docutils literal">mode</tt> may be <code>yes</code>, <code>no</code>, or <code>adaptive</code>
|
|
(default).</p>
|
|
<p>In a server mode setup, it is possible to selectively turn compression
|
|
on or off for individual clients.</p>
|
|
<p>First, make sure the client-side config file enables selective
|
|
compression by having at least one <tt class="docutils literal"><span class="pre">--comp-lzo</span></tt> directive, such as
|
|
<tt class="docutils literal"><span class="pre">--comp-lzo</span> no</tt>. This will turn off compression by default, but allow
|
|
a future directive push from the server to dynamically change the
|
|
<code>on</code>/<code>off</code>/<code>adaptive</code> setting.</p>
|
|
<p>Next in a <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file, specify the compression setting
|
|
for the client, for example:</p>
|
|
<pre class="literal-block">
|
|
comp-lzo yes
|
|
push "comp-lzo yes"
|
|
</pre>
|
|
<p class="last">The first line sets the <tt class="docutils literal"><span class="pre">comp-lzo</span></tt> setting for the server side of the
|
|
link, the second sets the client side.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--comp-noadapt</span></kbd></td>
|
|
<td><p class="first"><strong>DEPRECATED</strong> When used in conjunction with <tt class="docutils literal"><span class="pre">--comp-lzo</span></tt>, this option
|
|
will disable OpenVPN's adaptive compression algorithm. Normally, adaptive
|
|
compression is enabled with <tt class="docutils literal"><span class="pre">--comp-lzo</span></tt>.</p>
|
|
<p class="last">Adaptive compression tries to optimize the case where you have
|
|
compression enabled, but you are sending predominantly incompressible
|
|
(or pre-compressed) packets over the tunnel, such as an FTP or rsync
|
|
transfer of a large, compressed file. With adaptive compression, OpenVPN
|
|
will periodically sample the compression process to measure its
|
|
efficiency. If the data being sent over the tunnel is already
|
|
compressed, the compression efficiency will be very low, triggering
|
|
openvpn to disable compression for a period of time until the next
|
|
re-sample test.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--key-direction</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Alternative way of specifying the optional direction parameter for the
|
|
<tt class="docutils literal"><span class="pre">--tls-auth</span></tt> and <tt class="docutils literal"><span class="pre">--secret</span></tt> options. Useful when using inline files
|
|
(See section on inline files).</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--keysize <var>n</var></span></kbd></td>
|
|
<td><p class="first"><strong>DEPRECATED</strong> This option will be removed in OpenVPN 2.6.</p>
|
|
<p class="last">Size of cipher key in bits (optional). If unspecified, defaults to
|
|
cipher-specific default. The <tt class="docutils literal"><span class="pre">--show-ciphers</span></tt> option (see below) shows
|
|
all available OpenSSL ciphers, their default key sizes, and whether the
|
|
key size can be changed. Use care in changing a cipher's default key
|
|
size. Many ciphers have not been extensively cryptanalyzed with
|
|
non-standard key lengths, and a larger key may offer no real guarantee
|
|
of greater security, or may even reduce security.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--data-ciphers <var>cipher-list</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Restrict the allowed ciphers to be negotiated to the ciphers in
|
|
<tt class="docutils literal"><span class="pre">cipher-list</span></tt>. <tt class="docutils literal"><span class="pre">cipher-list</span></tt> is a colon-separated list of ciphers,
|
|
and defaults to <code>AES-256-GCM:AES-128-GCM</code>.</p>
|
|
<p>For servers, the first cipher from <tt class="docutils literal"><span class="pre">cipher-list</span></tt> that is also
|
|
supported by the client will be pushed to clients that support cipher
|
|
negotiation.</p>
|
|
<p>Cipher negotiation is enabled in client-server mode only. I.e. if
|
|
<tt class="docutils literal"><span class="pre">--mode</span></tt> is set to 'server' (server-side, implied by setting
|
|
<tt class="docutils literal"><span class="pre">--server</span></tt> ), or if <tt class="docutils literal"><span class="pre">--pull</span></tt> is specified (client-side, implied by
|
|
setting --client).</p>
|
|
<p>If no common cipher is found during cipher negotiation, the connection
|
|
is terminated. To support old clients/old servers that do not provide any
|
|
cipher negotiation support see <tt class="docutils literal"><span class="pre">--data-ciphers-fallback</span></tt>.</p>
|
|
<p>Additionally, to allow for more smooth transition, if NCP is enabled,
|
|
OpenVPN will inherit the cipher of the peer if that cipher is different
|
|
from the local <tt class="docutils literal"><span class="pre">--cipher</span></tt> setting, but the peer cipher is one of the
|
|
ciphers specified in <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt>. E.g. a non-NCP client (<=v2.3,
|
|
or with --ncp-disabled set) connecting to a NCP server (v2.4+) with
|
|
<tt class="docutils literal"><span class="pre">--cipher</span> <span class="pre">BF-CBC</span></tt> and <tt class="docutils literal"><span class="pre">--data-ciphers</span> <span class="pre">AES-256-GCM:AES-256-CBC</span></tt> set can
|
|
either specify <tt class="docutils literal"><span class="pre">--cipher</span> <span class="pre">BF-CBC</span></tt> or <tt class="docutils literal"><span class="pre">--cipher</span> <span class="pre">AES-256-CBC</span></tt> and both
|
|
will work.</p>
|
|
<p>Note for using NCP with an OpenVPN 2.4 peer: This list must include the
|
|
<code>AES-256-GCM</code> and <code>AES-128-GCM</code> ciphers.</p>
|
|
<p>This list is restricted to be 127 chars long after conversion to OpenVPN
|
|
ciphers.</p>
|
|
<p class="last">This option was called <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt> in OpenVPN 2.4 but has been renamed
|
|
to <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> in OpenVPN 2.5 to more accurately reflect its meaning.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--data-ciphers-fallback <var>alg</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Configure a cipher that is used to fall back to if we could not determine
|
|
which cipher the peer is willing to use.</p>
|
|
<p class="last">This option should only be needed to
|
|
connect to peers that are running OpenVPN 2.3 and older version, and
|
|
have been configured with <cite>--enable-small</cite>
|
|
(typically used on routers or other embedded devices).</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--ncp-disable</span></kbd></td>
|
|
<td><strong>DEPRECATED</strong> Disable "Negotiable Crypto Parameters". This completely
|
|
disables cipher negotiation.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--secret <var>args</var></span></kbd></td>
|
|
<td><p class="first">Enable Static Key encryption mode (non-TLS). Use pre-shared secret
|
|
<tt class="docutils literal">file</tt> which was generated with <tt class="docutils literal"><span class="pre">--genkey</span></tt>.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
secret file
|
|
secret file direction
|
|
</pre>
|
|
<p>The optional <tt class="docutils literal">direction</tt> parameter enables the use of 4 distinct keys
|
|
(HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that each
|
|
data flow direction has a different set of HMAC and cipher keys. This
|
|
has a number of desirable security properties including eliminating
|
|
certain kinds of DoS and message replay attacks.</p>
|
|
<p>When the <tt class="docutils literal">direction</tt> parameter is omitted, 2 keys are used
|
|
bidirectionally, one for HMAC and the other for encryption/decryption.</p>
|
|
<p>The <tt class="docutils literal">direction</tt> parameter should always be complementary on either
|
|
side of the connection, i.e. one side should use <code>0</code> and the other
|
|
should use <code>1</code>, or both sides should omit it altogether.</p>
|
|
<p>The <tt class="docutils literal">direction</tt> parameter requires that <tt class="docutils literal">file</tt> contains a 2048 bit
|
|
key. While pre-1.5 versions of OpenVPN generate 1024 bit key files, any
|
|
version of OpenVPN which supports the <tt class="docutils literal">direction</tt> parameter, will also
|
|
support 2048 bit key file generation using the <tt class="docutils literal"><span class="pre">--genkey</span></tt> option.</p>
|
|
<p>Static key encryption mode has certain advantages, the primary being
|
|
ease of configuration.</p>
|
|
<p>There are no certificates or certificate authorities or complicated
|
|
negotiation handshakes and protocols. The only requirement is that you
|
|
have a pre-existing secure channel with your peer (such as <tt class="docutils literal">ssh</tt>) to
|
|
initially copy the key. This requirement, along with the fact that your
|
|
key never changes unless you manually generate a new one, makes it
|
|
somewhat less secure than TLS mode (see below). If an attacker manages
|
|
to steal your key, everything that was ever encrypted with it is
|
|
compromised. Contrast that to the perfect forward secrecy features of
|
|
TLS mode (using Diffie Hellman key exchange), where even if an attacker
|
|
was able to steal your private key, he would gain no information to help
|
|
him decrypt past sessions.</p>
|
|
<p class="last">Another advantageous aspect of Static Key encryption mode is that it is
|
|
a handshake-free protocol without any distinguishing signature or
|
|
feature (such as a header or protocol handshake sequence) that would
|
|
mark the ciphertext packets as being generated by OpenVPN. Anyone
|
|
eavesdropping on the wire would see nothing but random-looking data.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tran-window <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Transition window -- our old key can live this many seconds after a new
|
|
a key renegotiation begins (default <code>3600</code> seconds). This feature
|
|
allows for a graceful transition from old to new key, and removes the key
|
|
renegotiation sequence from the critical path of tunnel data forwarding.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="client-options">
|
|
<h2>Client Options</h2>
|
|
<p>The client options are used when connecting to an OpenVPN server configured
|
|
to use <tt class="docutils literal"><span class="pre">--server</span></tt>, <tt class="docutils literal"><span class="pre">--server-bridge</span></tt>, or <tt class="docutils literal"><span class="pre">--mode</span> server</tt> in its
|
|
configuration.</p>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--allow-pull-fqdn</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Allow client to pull DNS names from server (rather than being limited to
|
|
IP address) for <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>, <tt class="docutils literal"><span class="pre">--route</span></tt>, and <tt class="docutils literal"><span class="pre">--route-gateway</span></tt>.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--allow-recursive-routing</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>When this option is set, OpenVPN will not drop incoming tun packets with
|
|
same destination as host.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--auth-token <var>token</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">This is not an option to be used directly in any configuration files,
|
|
but rather push this option from a <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script or a
|
|
<tt class="docutils literal"><span class="pre">--plugin</span></tt> which hooks into the <code>OPENVPN_PLUGIN_CLIENT_CONNECT</code>
|
|
or <code>OPENVPN_PLUGIN_CLIENT_CONNECT_V2</code> calls. This option provides a
|
|
possibility to replace the clients password with an authentication token
|
|
during the lifetime of the OpenVPN client.</p>
|
|
<p>Whenever the connection is renegotiated and the
|
|
<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script or <tt class="docutils literal"><span class="pre">--plugin</span></tt> making use of the
|
|
<code>OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY</code> hook is triggered, it will
|
|
pass over this token as the password instead of the password the user
|
|
provided. The authentication token can only be reset by a full reconnect
|
|
where the server can push new options to the client. The password the
|
|
user entered is never preserved once an authentication token has been
|
|
set. If the OpenVPN server side rejects the authentication token then
|
|
the client will receive an <code>AUTH_FAILED</code> and disconnect.</p>
|
|
<p>The purpose of this is to enable two factor authentication methods, such
|
|
as HOTP or TOTP, to be used without needing to retrieve a new OTP code
|
|
each time the connection is renegotiated. Another use case is to cache
|
|
authentication data on the client without needing to have the users
|
|
password cached in memory during the life time of the session.</p>
|
|
<p>To make use of this feature, the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script or
|
|
<tt class="docutils literal"><span class="pre">--plugin</span></tt> needs to put</p>
|
|
<pre class="literal-block">
|
|
push "auth-token UNIQUE_TOKEN_VALUE"
|
|
</pre>
|
|
<p>into the file/buffer for dynamic configuration data. This will then make
|
|
the OpenVPN server to push this value to the client, which replaces the
|
|
local password with the <tt class="docutils literal">UNIQUE_TOKEN_VALUE</tt>.</p>
|
|
<p class="last">Newer clients (2.4.7+) will fall back to the original password method
|
|
after a failed auth. Older clients will keep using the token value and
|
|
react according to <tt class="docutils literal"><span class="pre">--auth-retry</span></tt></p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--auth-token-user <var>base64username</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Companion option to <tt class="docutils literal"><span class="pre">--auth-token</span></tt>. This options allows to override
|
|
the username used by the client when reauthenticating with the <tt class="docutils literal"><span class="pre">auth-token</span></tt>.
|
|
It also allows to use <tt class="docutils literal"><span class="pre">--auth-token</span></tt> in setups that normally do not use
|
|
username and password.</p>
|
|
<p class="last">The username has to be base64 encoded.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--auth-user-pass</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Authenticate with server using username/password.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
auth-user-pass
|
|
auth-user-pass up
|
|
</pre>
|
|
<p>If <tt class="docutils literal">up</tt> is present, it must be a file containing username/password on 2
|
|
lines. If the password line is missing, OpenVPN will prompt for one.</p>
|
|
<p>If <tt class="docutils literal">up</tt> is omitted, username/password will be prompted from the
|
|
console.</p>
|
|
<p class="last">The server configuration must specify an <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt>
|
|
script to verify the username/password provided by the client.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--auth-retry <var>type</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Controls how OpenVPN responds to username/password verification errors
|
|
such as the client-side response to an <code>AUTH_FAILED</code> message from
|
|
the server or verification failure of the private key password.</p>
|
|
<p>Normally used to prevent auth errors from being fatal on the client
|
|
side, and to permit username/password requeries in case of error.</p>
|
|
<p>An <code>AUTH_FAILED</code> message is generated by the server if the client
|
|
fails <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> authentication, or if the server-side
|
|
<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script returns an error status when the client
|
|
tries to connect.</p>
|
|
<p><tt class="docutils literal">type</tt> can be one of:</p>
|
|
<dl class="docutils">
|
|
<dt><code>none</code></dt>
|
|
<dd>Client will exit with a fatal error (this is the default).</dd>
|
|
<dt><code>nointeract</code></dt>
|
|
<dd>Client will retry the connection without requerying
|
|
for an <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> username/password. Use this option for
|
|
unattended clients.</dd>
|
|
<dt><code>interact</code></dt>
|
|
<dd>Client will requery for an <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt>
|
|
username/password and/or private key password before attempting a
|
|
reconnection.</dd>
|
|
</dl>
|
|
<p class="last">Note that while this option cannot be pushed, it can be controlled from
|
|
the management interface.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--client</span></kbd></td>
|
|
<td><p class="first">A helper directive designed to simplify the configuration of OpenVPN's
|
|
client mode. This directive is equivalent to:</p>
|
|
<pre class="last literal-block">
|
|
pull
|
|
tls-client
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--client-nat <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">This pushable client option sets up a stateless one-to-one NAT rule on
|
|
packet addresses (not ports), and is useful in cases where routes or
|
|
ifconfig settings pushed to the client would create an IP numbering
|
|
conflict.</p>
|
|
<p>Examples:</p>
|
|
<pre class="literal-block">
|
|
client-nat snat 192.168.0.0/255.255.0.0
|
|
client-nat dnat 10.64.0.0/255.255.0.0
|
|
</pre>
|
|
<p><tt class="docutils literal">network/netmask</tt> (for example <code>192.168.0.0/255.255.0.0</code>) defines
|
|
the local view of a resource from the client perspective, while
|
|
<tt class="docutils literal">alias/netmask</tt> (for example <code>10.64.0.0/255.255.0.0</code>) defines the
|
|
remote view from the server perspective.</p>
|
|
<p>Use <code>snat</code> (source NAT) for resources owned by the client and
|
|
<code>dnat</code> (destination NAT) for remote resources.</p>
|
|
<p class="last">Set <tt class="docutils literal"><span class="pre">--verb</span> 6</tt> for debugging info showing the transformation of
|
|
src/dest addresses in packets.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--connect-retry <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Wait <tt class="docutils literal">n</tt> seconds between connection attempts (default <code>5</code>).
|
|
Repeated reconnection attempts are slowed down after 5 retries per
|
|
remote by doubling the wait time after each unsuccessful attempt. An
|
|
optional argument <tt class="docutils literal">max</tt> specifies the maximum value of wait time in
|
|
seconds at which it gets capped (default <code>300</code>).</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--connect-retry-max <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><tt class="docutils literal">n</tt> specifies the number of times each <tt class="docutils literal"><span class="pre">--remote</span></tt> or
|
|
<tt class="docutils literal"><connection></tt> entry is tried. Specifying <tt class="docutils literal">n</tt> as <code>1</code> would try
|
|
each entry exactly once. A successful connection resets the counter.
|
|
(default <em>unlimited</em>).</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--connect-timeout <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>See <tt class="docutils literal"><span class="pre">--server-poll-timeout</span></tt>.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--explicit-exit-notify <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">In UDP client mode or point-to-point mode, send server/peer an exit
|
|
notification if tunnel is restarted or OpenVPN process is exited. In
|
|
client mode, on exit/restart, this option will tell the server to
|
|
immediately close its client instance object rather than waiting for a
|
|
timeout.</p>
|
|
<p>The <strong>n</strong> parameter (default <code>1</code> if not present) controls the
|
|
maximum number of attempts that the client will try to resend the exit
|
|
notification message.</p>
|
|
<p>In UDP server mode, send <code>RESTART</code> control channel command to
|
|
connected clients. The <tt class="docutils literal">n</tt> parameter (default <code>1</code> if not present)
|
|
controls client behavior. With <tt class="docutils literal">n</tt> = <code>1</code> client will attempt to
|
|
reconnect to the same server, with <tt class="docutils literal">n</tt> = <code>2</code> client will advance
|
|
to the next server.</p>
|
|
<p class="last">OpenVPN will not send any exit notifications unless this option is
|
|
enabled.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--inactive <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Causes OpenVPN to exit after <tt class="docutils literal">n</tt> seconds of inactivity on the TUN/TAP
|
|
device. The time length of inactivity is measured since the last
|
|
incoming or outgoing tunnel packet. The default value is 0 seconds,
|
|
which disables this feature.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
inactive n
|
|
inactive n bytes
|
|
</pre>
|
|
<p>If the optional <tt class="docutils literal">bytes</tt> parameter is included, exit if less than
|
|
<tt class="docutils literal">bytes</tt> of combined in/out traffic are produced on the tun/tap device
|
|
in <tt class="docutils literal">n</tt> seconds.</p>
|
|
<p class="last">In any case, OpenVPN's internal ping packets (which are just keepalives)
|
|
and TLS control packets are not considered "activity", nor are they
|
|
counted as traffic, as they are used internally by OpenVPN and are not
|
|
an indication of actual user activity.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--proto-force <var>p</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>When iterating through connection profiles, only consider profiles using
|
|
protocol <tt class="docutils literal">p</tt> (<code>tcp</code> | <code>udp</code>).</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--pull</span></kbd></td>
|
|
<td><p class="first">This option must be used on a client which is connecting to a
|
|
multi-client server. It indicates to OpenVPN that it should accept
|
|
options pushed by the server, provided they are part of the legal set of
|
|
pushable options (note that the <tt class="docutils literal"><span class="pre">--pull</span></tt> option is implied by
|
|
<tt class="docutils literal"><span class="pre">--client</span></tt> ).</p>
|
|
<p class="last">In particular, <tt class="docutils literal"><span class="pre">--pull</span></tt> allows the server to push routes to the
|
|
client, so you should not use <tt class="docutils literal"><span class="pre">--pull</span></tt> or <tt class="docutils literal"><span class="pre">--client</span></tt> in situations
|
|
where you don't trust the server to have control over the client's
|
|
routing table.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--pull-filter <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Filter options on the client pushed by the server to the client.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
pull-filter accept text
|
|
pull-filter ignore text
|
|
pull-filter reject text
|
|
</pre>
|
|
<p>Filter options received from the server if the option starts with
|
|
<code>text</code>. The action flag <code>accept</code> allows the option,
|
|
<code>ignore</code> removes it and <code>reject</code> flags an error and triggers
|
|
a <code>SIGUSR1</code> restart. The filters may be specified multiple times,
|
|
and each filter is applied in the order it is specified. The filtering of
|
|
each option stops as soon as a match is found. Unmatched options are accepted
|
|
by default.</p>
|
|
<p>Prefix comparison is used to match <code>text</code> against the received option so
|
|
that</p>
|
|
<pre class="literal-block">
|
|
pull-filter ignore "route"
|
|
</pre>
|
|
<p>would remove all pushed options starting with <tt class="docutils literal">route</tt> which would
|
|
include, for example, <tt class="docutils literal"><span class="pre">route-gateway</span></tt>. Enclose <em>text</em> in quotes to
|
|
embed spaces.</p>
|
|
<pre class="literal-block">
|
|
pull-filter accept "route 192.168.1."
|
|
pull-filter ignore "route "
|
|
</pre>
|
|
<p>would remove all routes that do not start with <tt class="docutils literal">192.168.1</tt>.</p>
|
|
<p class="last"><em>Note</em> that <code>reject</code> may result in a repeated cycle of failure and
|
|
reconnect, unless multiple remotes are specified and connection to the
|
|
next remote succeeds. To silently ignore an option pushed by the server,
|
|
use <code>ignore</code>.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--push-peer-info</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Push additional information about the client to server. The following
|
|
data is always pushed to the server:</p>
|
|
<dl class="docutils">
|
|
<dt><code>IV_VER=<version></code></dt>
|
|
<dd>The client OpenVPN version</dd>
|
|
<dt><code>IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]</code></dt>
|
|
<dd>The client OS platform</dd>
|
|
<dt><code>IV_LZO_STUB=1</code></dt>
|
|
<dd>If client was built with LZO stub capability</dd>
|
|
<dt><code>IV_LZ4=1</code></dt>
|
|
<dd>If the client supports LZ4 compressions.</dd>
|
|
<dt><code>IV_PROTO</code></dt>
|
|
<dd><p class="first">Details about protocol extensions that the peer supports. The
|
|
variable is a bitfield and the bits are defined as follows
|
|
(starting a bit 0 for the first (unused) bit:</p>
|
|
<ul class="last simple">
|
|
<li>bit 1: The peer supports peer-id floating mechanism</li>
|
|
<li>bit 2: The client expects a push-reply and the server may
|
|
send this reply without waiting for a push-request first.</li>
|
|
<li>bit 3: The client is capable of doing key derivation using
|
|
RFC5705 key material exporter.</li>
|
|
<li>bit 4: The client is capable of accepting additional arguments
|
|
to the <cite>AUTH_PENDING</cite> message.</li>
|
|
</ul>
|
|
</dd>
|
|
<dt><code>IV_NCP=2</code></dt>
|
|
<dd>Negotiable ciphers, client supports <tt class="docutils literal"><span class="pre">--cipher</span></tt> pushed by
|
|
the server, a value of 2 or greater indicates client supports
|
|
<em>AES-GCM-128</em> and <em>AES-GCM-256</em>.</dd>
|
|
<dt><code>IV_CIPHERS=<ncp-ciphers></code></dt>
|
|
<dd>The client announces the list of supported ciphers configured with the
|
|
<tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> option to the server.</dd>
|
|
<dt><code>IV_GUI_VER=<gui_id> <version></code></dt>
|
|
<dd>The UI version of a UI if one is running, for example
|
|
<code>de.blinkt.openvpn 0.5.47</code> for the Android app.</dd>
|
|
<dt><code>IV_SSO=[crtext,][openurl,][proxy_url]</code></dt>
|
|
<dd>Additional authentication methods supported by the client.
|
|
This may be set by the client UI/GUI using <tt class="docutils literal"><span class="pre">--setenv</span></tt></dd>
|
|
</dl>
|
|
<p>When <tt class="docutils literal"><span class="pre">--push-peer-info</span></tt> is enabled the additional information consists
|
|
of the following data:</p>
|
|
<dl class="last docutils">
|
|
<dt><code>IV_HWADDR=<string></code></dt>
|
|
<dd>This is intended to be a unique and persistent ID of the client.
|
|
The string value can be any readable ASCII string up to 64 bytes.
|
|
OpenVPN 2.x and some other implementations use the MAC address of
|
|
the client's interface used to reach the default gateway. If this
|
|
string is generated by the client, it should be consistent and
|
|
preserved across independent session and preferably
|
|
re-installations and upgrades.</dd>
|
|
<dt><code>IV_SSL=<version string></code></dt>
|
|
<dd>The ssl version used by the client, e.g.
|
|
<code>OpenSSL 1.0.2f 28 Jan 2016</code>.</dd>
|
|
<dt><code>IV_PLAT_VER=x.y</code></dt>
|
|
<dd>The version of the operating system, e.g. 6.1 for Windows 7.</dd>
|
|
<dt><code>UV_<name>=<value></code></dt>
|
|
<dd>Client environment variables whose names start with
|
|
<code>UV_</code></dd>
|
|
</dl>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--remote <var>args</var></span></kbd></td>
|
|
<td><p class="first">Remote host name or IP address, port and protocol.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
remote host
|
|
remote host port
|
|
remote host port proto
|
|
</pre>
|
|
<p>The <tt class="docutils literal">port</tt> and <tt class="docutils literal">proto</tt> arguments are optional. The OpenVPN client
|
|
will try to connect to a server at <tt class="docutils literal">host:port</tt>. The <tt class="docutils literal">proto</tt> argument
|
|
indicates the protocol to use when connecting with the remote, and may be
|
|
<code>tcp</code> or <code>udp</code>. To enforce IPv4 or IPv6 connections add a
|
|
<code>4</code> or <code>6</code> suffix; like <code>udp4</code> / <code>udp6</code>
|
|
/ <code>tcp4</code> / <code>tcp6</code>.</p>
|
|
<p>On the client, multiple <tt class="docutils literal"><span class="pre">--remote</span></tt> options may be specified for
|
|
redundancy, each referring to a different OpenVPN server, in the order
|
|
specified by the list of <tt class="docutils literal"><span class="pre">--remote</span></tt> options. Specifying multiple
|
|
<tt class="docutils literal"><span class="pre">--remote</span></tt> options for this purpose is a special case of the more
|
|
general connection-profile feature. See the <tt class="docutils literal"><connection></tt>
|
|
documentation below.</p>
|
|
<p>The client will move on to the next host in the list, in the event of
|
|
connection failure. Note that at any given time, the OpenVPN client will
|
|
at most be connected to one server.</p>
|
|
<p>Examples:</p>
|
|
<pre class="literal-block">
|
|
remote server1.example.net
|
|
remote server1.example.net 1194
|
|
remote server2.example.net 1194 tcp
|
|
</pre>
|
|
<dl class="docutils">
|
|
<dt><em>Note:</em></dt>
|
|
<dd><p class="first">Since UDP is connectionless, connection failure is defined by
|
|
the <tt class="docutils literal"><span class="pre">--ping</span></tt> and <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> options.</p>
|
|
<p class="last">Also, if you use multiple <tt class="docutils literal"><span class="pre">--remote</span></tt> options, AND you are dropping
|
|
root privileges on the client with <tt class="docutils literal"><span class="pre">--user</span></tt> and/or <tt class="docutils literal"><span class="pre">--group</span></tt> AND
|
|
the client is running a non-Windows OS, if the client needs to switch
|
|
to a different server, and that server pushes back different TUN/TAP
|
|
or route settings, the client may lack the necessary privileges to
|
|
close and reopen the TUN/TAP interface. This could cause the client
|
|
to exit with a fatal error.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>If <tt class="docutils literal"><span class="pre">--remote</span></tt> is unspecified, OpenVPN will listen for packets from any
|
|
IP address, but will not act on those packets unless they pass all
|
|
authentication tests. This requirement for authentication is binding on
|
|
all potential peers, even those from known and supposedly trusted IP
|
|
addresses (it is very easy to forge a source IP address on a UDP
|
|
packet).</p>
|
|
<p>When used in TCP mode, <tt class="docutils literal"><span class="pre">--remote</span></tt> will act as a filter, rejecting
|
|
connections from any host which does not match <tt class="docutils literal">host</tt>.</p>
|
|
<p class="last">If <tt class="docutils literal">host</tt> is a DNS name which resolves to multiple IP addresses,
|
|
OpenVPN will try them in the order that the system getaddrinfo()
|
|
presents them, so priorization and DNS randomization is done by the
|
|
system library. Unless an IP version is forced by the protocol
|
|
specification (4/6 suffix), OpenVPN will try both IPv4 and IPv6
|
|
addresses, in the order getaddrinfo() returns them.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--remote-random</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>When multiple <tt class="docutils literal"><span class="pre">--remote</span></tt> address/ports are specified, or if connection
|
|
profiles are being used, initially randomize the order of the list as a
|
|
kind of basic load-balancing measure.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--remote-random-hostname</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Prepend a random string (6 bytes, 12 hex characters) to hostname to
|
|
prevent DNS caching. For example, "foo.bar.gov" would be modified to
|
|
"<random-chars>.foo.bar.gov".</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--resolv-retry <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">If hostname resolve fails for <tt class="docutils literal"><span class="pre">--remote</span></tt>, retry resolve for <tt class="docutils literal">n</tt>
|
|
seconds before failing.</p>
|
|
<p>Set <tt class="docutils literal">n</tt> to "infinite" to retry indefinitely.</p>
|
|
<p class="last">By default, <tt class="docutils literal"><span class="pre">--resolv-retry</span> infinite</tt> is enabled. You can disable by
|
|
setting n=0.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--single-session</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">After initially connecting to a remote peer, disallow any new
|
|
connections. Using this option means that a remote peer cannot connect,
|
|
disconnect, and then reconnect.</p>
|
|
<p>If the daemon is reset by a signal or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>, it will allow
|
|
one new connection.</p>
|
|
<p class="last"><tt class="docutils literal"><span class="pre">--single-session</span></tt> can be used with <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> or <tt class="docutils literal"><span class="pre">--inactive</span></tt>
|
|
to create a single dynamic session that will exit when finished.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--server-poll-timeout <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>When connecting to a remote server do not wait for more than <tt class="docutils literal">n</tt>
|
|
seconds for a response before trying the next server. The default value
|
|
is 120s. This timeout includes proxy and TCP connect timeouts.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--static-challenge <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Enable static challenge/response protocol</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
static-challenge text echo
|
|
</pre>
|
|
<p>The <tt class="docutils literal">text</tt> challenge text is presented to the user which describes what
|
|
information is requested. The <tt class="docutils literal">echo</tt> flag indicates if the user's
|
|
input should be echoed on the screen. Valid <tt class="docutils literal">echo</tt> values are
|
|
<code>0</code> or <code>1</code>.</p>
|
|
<p class="last">See management-notes.txt in the OpenVPN distribution for a description of
|
|
the OpenVPN challenge/response protocol.</p>
|
|
</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--show-proxy-settings</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Show sensed HTTP or SOCKS proxy settings. Currently, only Windows
|
|
clients support this option.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--http-proxy <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Connect to remote host through an HTTP proxy. This requires at least an
|
|
address <tt class="docutils literal">server</tt> and <tt class="docutils literal">port</tt> argument. If HTTP Proxy-Authenticate
|
|
is required, a file name to an <tt class="docutils literal">authfile</tt> file containing a username
|
|
and password on 2 lines can be given, or <code>stdin</code> to prompt from
|
|
console. Its content can also be specified in the config file with the
|
|
<tt class="docutils literal"><span class="pre">--http-proxy-user-pass</span></tt> option. (See section on inline files)</p>
|
|
<p>The last optional argument is an <tt class="docutils literal"><span class="pre">auth-method</span></tt> which should be one
|
|
of <code>none</code>, <code>basic</code>, or <code>ntlm</code>.</p>
|
|
<p>HTTP Digest authentication is supported as well, but only via the
|
|
<code>auto</code> or <code>auto-nct</code> flags (below). This must replace
|
|
the <tt class="docutils literal">authfile</tt> argument.</p>
|
|
<p>The <code>auto</code> flag causes OpenVPN to automatically determine the
|
|
<tt class="docutils literal"><span class="pre">auth-method</span></tt> and query stdin or the management interface for
|
|
username/password credentials, if required. This flag exists on OpenVPN
|
|
2.1 or higher.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">auto-nct</span></tt> flag (no clear-text auth) instructs OpenVPN to
|
|
automatically determine the authentication method, but to reject weak
|
|
authentication protocols such as HTTP Basic Authentication.</p>
|
|
<p>Examples:</p>
|
|
<pre class="last literal-block">
|
|
http-proxy proxy.example.net 3128
|
|
http-proxy proxy.example.net 3128 authfile.txt
|
|
http-proxy proxy.example.net 3128 stdin
|
|
http-proxy proxy.example.net 3128 auto basic
|
|
http-proxy proxy.example.net 3128 auto-nct ntlm
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--http-proxy-option <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Set extended HTTP proxy options. Requires an option <tt class="docutils literal">type</tt> as argument
|
|
and an optional <tt class="docutils literal">parameter</tt> to the type. Repeat to set multiple
|
|
options.</p>
|
|
<dl class="docutils">
|
|
<dt><code>VERSION</code> <tt class="docutils literal">version</tt></dt>
|
|
<dd>Set HTTP version number to <tt class="docutils literal">version</tt> (default <code>1.0</code>).</dd>
|
|
<dt><code>AGENT</code> <tt class="docutils literal"><span class="pre">user-agent</span></tt></dt>
|
|
<dd>Set HTTP "User-Agent" string to <tt class="docutils literal"><span class="pre">user-agent</span></tt>.</dd>
|
|
<dt><code>CUSTOM-HEADER</code> <tt class="docutils literal">name</tt> <tt class="docutils literal">content</tt></dt>
|
|
<dd>Adds the custom Header with <tt class="docutils literal">name</tt> as name and <tt class="docutils literal">content</tt> as
|
|
the content of the custom HTTP header.</dd>
|
|
</dl>
|
|
<p>Examples:</p>
|
|
<pre class="last literal-block">
|
|
http-proxy-option VERSION 1.1
|
|
http-proxy-option AGENT OpenVPN/2.4
|
|
http-proxy-option X-Proxy-Flag some-flags
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--socks-proxy <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Connect to remote host through a Socks5 proxy. A required <tt class="docutils literal">server</tt>
|
|
argument is needed. Optionally a <tt class="docutils literal">port</tt> (default <code>1080</code>) and
|
|
<tt class="docutils literal">authfile</tt> can be given. The <tt class="docutils literal">authfile</tt> is a file containing a
|
|
username and password on 2 lines, or <code>stdin</code> can be used to
|
|
prompt from console.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="server-options">
|
|
<h2>Server Options</h2>
|
|
<p>Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is
|
|
supported, and can be enabled with the <tt class="docutils literal"><span class="pre">--mode</span> server</tt> option. In
|
|
server mode, OpenVPN will listen on a single port for incoming client
|
|
connections. All client connections will be routed through a single tun
|
|
or tap interface. This mode is designed for scalability and should be
|
|
able to support hundreds or even thousands of clients on sufficiently
|
|
fast hardware. SSL/TLS authentication must be used in this mode.</p>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--auth-gen-token <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Returns an authentication token to successfully authenticated clients.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
auth-gen-token [lifetime] [external-auth]
|
|
</pre>
|
|
<p>After successful user/password authentication, the OpenVPN server will
|
|
with this option generate a temporary authentication token and push that
|
|
to the client. On the following renegotiations, the OpenVPN client will pass
|
|
this token instead of the users password. On the server side the server
|
|
will do the token authentication internally and it will NOT do any
|
|
additional authentications against configured external user/password
|
|
authentication mechanisms.</p>
|
|
<p>The tokens implemented by this mechanism include an initial timestamp and
|
|
a renew timestamp and are secured by HMAC.</p>
|
|
<p>The <tt class="docutils literal">lifetime</tt> argument defines how long the generated token is valid.
|
|
The lifetime is defined in seconds. If lifetime is not set or it is set
|
|
to <code>0</code>, the token will never expire.</p>
|
|
<p>The token will expire either after the configured <tt class="docutils literal">lifetime</tt> of the
|
|
token is reached or after not being renewed for more than 2 *
|
|
<tt class="docutils literal"><span class="pre">reneg-sec</span></tt> seconds. Clients will be sent renewed tokens on every TLS
|
|
renogiation to keep the client's token updated. This is done to
|
|
invalidate a token if a client is disconnected for a sufficently long
|
|
time, while at the same time permitting much longer token lifetimes for
|
|
active clients.</p>
|
|
<p>This feature is useful for environments which are configured to use One
|
|
Time Passwords (OTP) as part of the user/password authentications and
|
|
that authentication mechanism does not implement any auth-token support.</p>
|
|
<p>When the <code>external-auth</code> keyword is present the normal
|
|
authentication method will always be called even if auth-token succeeds.
|
|
Normally other authentications method are skipped if auth-token
|
|
verification suceeds or fails.</p>
|
|
<p>This option postpones this decision to the external authentication
|
|
methods and checks the validity of the account and do other checks.</p>
|
|
<p>In this mode the environment will have a <tt class="docutils literal">session_id</tt> variable that
|
|
holds the session id from auth-gen-token. Also an environment variable
|
|
<tt class="docutils literal">session_state</tt> is present. This variable indicates whether the
|
|
auth-token has succeeded or not. It can have the following values:</p>
|
|
<dl class="docutils">
|
|
<dt><code>Initial</code></dt>
|
|
<dd>No token from client.</dd>
|
|
<dt><code>Authenticated</code></dt>
|
|
<dd>Token is valid and not expired.</dd>
|
|
<dt><code>Expired</code></dt>
|
|
<dd>Token is valid but has expired.</dd>
|
|
<dt><code>Invalid</code></dt>
|
|
<dd>Token is invalid (failed HMAC or wrong length)</dd>
|
|
<dt><code>AuthenticatedEmptyUser</code> / <code>ExpiredEmptyUser</code></dt>
|
|
<dd>The token is not valid with the username sent from the client but
|
|
would be valid (or expired) if we assume an empty username was
|
|
used instead. These two cases are a workaround for behaviour in
|
|
OpenVPN 3. If this workaround is not needed these two cases should
|
|
be handled in the same way as <code>Invalid</code>.</dd>
|
|
</dl>
|
|
<p class="last"><strong>Warning:</strong> Use this feature only if you want your authentication
|
|
method called on every verification. Since the external authentication
|
|
is called it needs to also indicate a success or failure of the
|
|
authentication. It is strongly recommended to return an authentication
|
|
failure in the case of the Invalid/Expired auth-token with the
|
|
external-auth option unless the client could authenticate in another
|
|
acceptable way (e.g. client certificate), otherwise returning success
|
|
will lead to authentication bypass (as does returning success on a wrong
|
|
password from a script).</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--auth-gen-token-secret <var>file</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Specifies a file that holds a secret for the HMAC used in
|
|
<tt class="docutils literal"><span class="pre">--auth-gen-token</span></tt> If <tt class="docutils literal">file</tt> is not present OpenVPN will generate a
|
|
random secret on startup. This file should be used if auth-token should
|
|
validate after restarting a server or if client should be able to roam
|
|
between multiple OpenVPN servers with their auth-token.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--auth-user-pass-optional</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Allow connections by clients that do not specify a username/password.
|
|
Normally, when <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> or
|
|
<tt class="docutils literal"><span class="pre">--management-client-auth</span></tt> are specified (or an authentication plugin
|
|
module), the OpenVPN server daemon will require connecting clients to
|
|
specify a username and password. This option makes the submission of a
|
|
username/password by clients optional, passing the responsibility to the
|
|
user-defined authentication module/script to accept or deny the client
|
|
based on other factors (such as the setting of X509 certificate fields).
|
|
When this option is used, and a connecting client does not submit a
|
|
username/password, the user-defined authentication module/script will
|
|
see the username and password as being set to empty strings (""). The
|
|
authentication module/script MUST have logic to detect this condition
|
|
and respond accordingly.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ccd-exclusive</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Require, as a condition of authentication, that a connecting client has
|
|
a <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--client-config-dir <var>dir</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Specify a directory <tt class="docutils literal">dir</tt> for custom client config files. After a
|
|
connecting client has been authenticated, OpenVPN will look in this
|
|
directory for a file having the same name as the client's X509 common
|
|
name. If a matching file exists, it will be opened and parsed for
|
|
client-specific configuration options. If no matching file is found,
|
|
OpenVPN will instead try to open and parse a default file called
|
|
"DEFAULT", which may be provided but is not required. Note that the
|
|
configuration files must be readable by the OpenVPN process after it has
|
|
dropped it's root privileges.</p>
|
|
<p>This file can specify a fixed IP address for a given client using
|
|
<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt>, as well as fixed subnets owned by the client using
|
|
<tt class="docutils literal"><span class="pre">--iroute</span></tt>.</p>
|
|
<p>One of the useful properties of this option is that it allows client
|
|
configuration files to be conveniently created, edited, or removed while
|
|
the server is live, without needing to restart the server.</p>
|
|
<p class="last">The following options are legal in a client-specific context: <tt class="docutils literal"><span class="pre">--push</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--push-reset</span></tt>, <tt class="docutils literal"><span class="pre">--push-remove</span></tt>, <tt class="docutils literal"><span class="pre">--iroute</span></tt>, <tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--vlan-pvid</span></tt> and <tt class="docutils literal"><span class="pre">--config</span></tt>.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--client-to-client</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Because the OpenVPN server mode handles multiple clients through a
|
|
single tun or tap interface, it is effectively a router. The
|
|
<tt class="docutils literal"><span class="pre">--client-to-client</span></tt> flag tells OpenVPN to internally route
|
|
client-to-client traffic rather than pushing all client-originating
|
|
traffic to the TUN/TAP interface.</p>
|
|
<p class="last">When this option is used, each client will "see" the other clients which
|
|
are currently connected. Otherwise, each client will only see the
|
|
server. Don't use this option if you want to firewall tunnel traffic
|
|
using custom, per-client rules.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--disable</span></kbd></td>
|
|
<td><p class="first">Disable a particular client (based on the common name) from connecting.
|
|
Don't use this option to disable a client due to key or password
|
|
compromise. Use a CRL (certificate revocation list) instead (see the
|
|
<tt class="docutils literal"><span class="pre">--crl-verify</span></tt> option).</p>
|
|
<p class="last">This option must be associated with a specific client instance, which
|
|
means that it must be specified either in a client instance config file
|
|
using <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> or dynamically generated using a
|
|
<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--connect-freq <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Allow a maximum of <tt class="docutils literal">n</tt> new connections per <tt class="docutils literal">sec</tt> seconds from
|
|
clients.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
connect-freq n sec
|
|
</pre>
|
|
<p>This is designed to contain DoS attacks which flood the server
|
|
with connection requests using certificates which will ultimately fail
|
|
to authenticate.</p>
|
|
<p>This is an imperfect solution however, because in a real DoS scenario,
|
|
legitimate connections might also be refused.</p>
|
|
<p class="last">For the best protection against DoS attacks in server mode, use
|
|
<tt class="docutils literal"><span class="pre">--proto</span> udp</tt> and either <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> or <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt>.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--duplicate-cn</span></kbd></td>
|
|
<td>Allow multiple clients with the same common name to concurrently
|
|
connect. In the absence of this option, OpenVPN will disconnect a client
|
|
instance upon connection of a new client having the same common name.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ifconfig-pool <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Set aside a pool of subnets to be dynamically allocated to connecting
|
|
clients, similar to a DHCP server.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
ifconfig-pool start-IP end-IP [netmask]
|
|
</pre>
|
|
<p class="last">For tun-style tunnels, each client
|
|
will be given a /30 subnet (for interoperability with Windows clients).
|
|
For tap-style tunnels, individual addresses will be allocated, and the
|
|
optional <tt class="docutils literal">netmask</tt> parameter will also be pushed to clients.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ifconfig-ipv6-pool <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Specify an IPv6 address pool for dynamic assignment to clients.</p>
|
|
<p>Valid args:</p>
|
|
<pre class="literal-block">
|
|
ifconfig-ipv6-pool ipv6addr/bits
|
|
</pre>
|
|
<p class="last">The pool starts at <tt class="docutils literal">ipv6addr</tt> and matches the offset determined from
|
|
the start of the IPv4 pool. If the host part of the given IPv6
|
|
address is <tt class="docutils literal">0</tt>, the pool starts at <tt class="docutils literal">ipv6addr</tt> +1.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ifconfig-pool-persist <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Persist/unpersist ifconfig-pool data to <tt class="docutils literal">file</tt>, at <tt class="docutils literal">seconds</tt>
|
|
intervals (default <code>600</code>), as well as on program startup and shutdown.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
ifconfig-pool-persist file [seconds]
|
|
</pre>
|
|
<p>The goal of this option is to provide a long-term association between
|
|
clients (denoted by their common name) and the virtual IP address
|
|
assigned to them from the ifconfig-pool. Maintaining a long-term
|
|
association is good for clients because it allows them to effectively
|
|
use the <tt class="docutils literal"><span class="pre">--persist-tun</span></tt> option.</p>
|
|
<p><tt class="docutils literal">file</tt> is a comma-delimited ASCII file, formatted as
|
|
<code><Common-Name>,<IP-address></code>.</p>
|
|
<p>If <tt class="docutils literal">seconds</tt> = <code>0</code>, <tt class="docutils literal">file</tt> will be treated as read-only. This
|
|
is useful if you would like to treat <tt class="docutils literal">file</tt> as a configuration file.</p>
|
|
<p class="last">Note that the entries in this file are treated by OpenVPN as
|
|
<em>suggestions</em> only, based on past associations between a common name and
|
|
IP address. They do not guarantee that the given common name will always
|
|
receive the given IP address. If you want guaranteed assignment, use
|
|
<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt></p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ifconfig-push <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Push virtual IP endpoints for client tunnel, overriding the
|
|
<tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> dynamic allocation.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
ifconfig-push local remote-netmask [alias]
|
|
</pre>
|
|
<p>The parameters <tt class="docutils literal">local</tt> and <tt class="docutils literal"><span class="pre">remote-netmask</span></tt> are set according to the
|
|
<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> directive which you want to execute on the client machine
|
|
to configure the remote end of the tunnel. Note that the parameters
|
|
<tt class="docutils literal">local</tt> and <tt class="docutils literal"><span class="pre">remote-netmask</span></tt> are from the perspective of the client,
|
|
not the server. They may be DNS names rather than IP addresses, in which
|
|
case they will be resolved on the server at the time of client
|
|
connection.</p>
|
|
<p>The optional <tt class="docutils literal">alias</tt> parameter may be used in cases where NAT causes
|
|
the client view of its local endpoint to differ from the server view. In
|
|
this case <tt class="docutils literal"><span class="pre">local/remote-netmask</span></tt> will refer to the server view while
|
|
<tt class="docutils literal"><span class="pre">alias/remote-netmask</span></tt> will refer to the client view.</p>
|
|
<p>This option must be associated with a specific client instance, which
|
|
means that it must be specified either in a client instance config file
|
|
using <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> or dynamically generated using a
|
|
<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</p>
|
|
<p>Remember also to include a <tt class="docutils literal"><span class="pre">--route</span></tt> directive in the main OpenVPN
|
|
config file which encloses <tt class="docutils literal">local</tt>, so that the kernel will know to
|
|
route it to the server's TUN/TAP interface.</p>
|
|
<p>OpenVPN's internal client IP address selection algorithm works as
|
|
follows:</p>
|
|
<ol class="last arabic simple">
|
|
<li>Use <tt class="docutils literal"><span class="pre">--client-connect</span> script</tt> generated file for static IP
|
|
(first choice).</li>
|
|
<li>Use <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file for static IP (next choice).</li>
|
|
<li>Use <tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> allocation for dynamic IP (last
|
|
choice).</li>
|
|
</ol>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ifconfig-ipv6-push <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">for <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> per-client static IPv6 interface
|
|
configuration, see <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> and <tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt> for
|
|
more details.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="last literal-block">
|
|
ifconfig-ipv6-push ipv6addr/bits ipv6remote
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--inetd <var>args</var></span></kbd></td>
|
|
<td><p class="first">Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
inetd
|
|
inetd wait
|
|
inetd nowait
|
|
inetd wait progname
|
|
</pre>
|
|
<p>Use this option when OpenVPN is being run from the inetd or <tt class="docutils literal">xinetd</tt>(8)
|
|
server.</p>
|
|
<p>The <code>wait</code> and <code>nowait</code> option must match what is specified
|
|
in the inetd/xinetd config file. The <code>nowait</code> mode can only be used
|
|
with <tt class="docutils literal"><span class="pre">--proto</span> <span class="pre">tcp-server</span></tt> The default is <code>wait</code>. The
|
|
<code>nowait</code> mode can be used to instantiate the OpenVPN daemon as a
|
|
classic TCP server, where client connection requests are serviced on a
|
|
single port number. For additional information on this kind of
|
|
configuration, see the OpenVPN FAQ:
|
|
<a class="reference external" href="https://community.openvpn.net/openvpn/wiki/325-openvpn-as-a--forking-tcp-server-which-can-service-multiple-clients-over-a-single-tcp-port">https://community.openvpn.net/openvpn/wiki/325-openvpn-as-a--forking-tcp-server-which-can-service-multiple-clients-over-a-single-tcp-port</a></p>
|
|
<p>This option precludes the use of <tt class="docutils literal"><span class="pre">--daemon</span></tt>, <tt class="docutils literal"><span class="pre">--local</span></tt> or
|
|
<tt class="docutils literal"><span class="pre">--remote</span></tt>. Note that this option causes message and error output to
|
|
be handled in the same way as the <tt class="docutils literal"><span class="pre">--daemon</span></tt> option. The optional
|
|
<tt class="docutils literal">progname</tt> parameter is also handled exactly as in <tt class="docutils literal"><span class="pre">--daemon</span></tt>.</p>
|
|
<p class="last">Also note that in <tt class="docutils literal">wait</tt> mode, each OpenVPN tunnel requires a separate
|
|
TCP/UDP port and a separate inetd or xinetd entry. See the OpenVPN 1.x
|
|
HOWTO for an example on using OpenVPN with xinetd:
|
|
<a class="reference external" href="https://openvpn.net/community-resources/1xhowto/">https://openvpn.net/community-resources/1xhowto/</a></p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--multihome</span></kbd></td>
|
|
<td><p class="first">Configure a multi-homed UDP server. This option needs to be used when a
|
|
server has more than one IP address (e.g. multiple interfaces, or
|
|
secondary IP addresses), and is not using <tt class="docutils literal"><span class="pre">--local</span></tt> to force binding
|
|
to one specific address only. This option will add some extra lookups to
|
|
the packet path to ensure that the UDP reply packets are always sent
|
|
from the address that the client is talking to. This is not supported on
|
|
all platforms, and it adds more processing, so it's not enabled by
|
|
default.</p>
|
|
<dl class="last docutils">
|
|
<dt><em>Notes:</em></dt>
|
|
<dd><ul class="first last simple">
|
|
<li>This option is only relevant for UDP servers.</li>
|
|
<li>If you do an IPv6+IPv4 dual-stack bind on a Linux machine with
|
|
multiple IPv4 address, connections to IPv4 addresses will not
|
|
work right on kernels before 3.15, due to missing kernel
|
|
support for the IPv4-mapped case (some distributions have
|
|
ported this to earlier kernel versions, though).</li>
|
|
</ul>
|
|
</dd>
|
|
</dl>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--iroute <var>args</var></span></kbd></td>
|
|
<td><p class="first">Generate an internal route to a specific client. The <tt class="docutils literal">netmask</tt>
|
|
parameter, if omitted, defaults to <code>255.255.255.255</code>.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
iroute network [netmask]
|
|
</pre>
|
|
<p>This directive can be used to route a fixed subnet from the server to a
|
|
particular client, regardless of where the client is connecting from.
|
|
Remember that you must also add the route to the system routing table as
|
|
well (such as by using the <tt class="docutils literal"><span class="pre">--route</span></tt> directive). The reason why two
|
|
routes are needed is that the <tt class="docutils literal"><span class="pre">--route</span></tt> directive routes the packet
|
|
from the kernel to OpenVPN. Once in OpenVPN, the <tt class="docutils literal"><span class="pre">--iroute</span></tt> directive
|
|
routes to the specific client.</p>
|
|
<p>This option must be specified either in a client instance config file
|
|
using <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> or dynamically generated using a
|
|
<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</p>
|
|
<p class="last">The <tt class="docutils literal"><span class="pre">--iroute</span></tt> directive also has an important interaction with
|
|
<tt class="docutils literal"><span class="pre">--push</span> "route <span class="pre">..."</span></tt>. <tt class="docutils literal"><span class="pre">--iroute</span></tt> essentially defines a subnet which
|
|
is owned by a particular client (we will call this client <em>A</em>). If you
|
|
would like other clients to be able to reach <em>A</em>'s subnet, you can use
|
|
<tt class="docutils literal"><span class="pre">--push</span> "route <span class="pre">..."</span></tt> together with <tt class="docutils literal"><span class="pre">--client-to-client</span></tt> to effect
|
|
this. In order for all clients to see <em>A</em>'s subnet, OpenVPN must push
|
|
this route to all clients EXCEPT for <em>A</em>, since the subnet is already
|
|
owned by <em>A</em>. OpenVPN accomplishes this by not not pushing a route to
|
|
a client if it matches one of the client's iroutes.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--iroute-ipv6 <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">for <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> per-client static IPv6 route configuration,
|
|
see <tt class="docutils literal"><span class="pre">--iroute</span></tt> for more details how to setup and use this, and how
|
|
<tt class="docutils literal"><span class="pre">--iroute</span></tt> and <tt class="docutils literal"><span class="pre">--route</span></tt> interact.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="last literal-block">
|
|
iroute-ipv6 ipv6addr/bits
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--max-clients <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Limit server to a maximum of <tt class="docutils literal">n</tt> concurrent clients.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--max-routes-per-client <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Allow a maximum of <tt class="docutils literal">n</tt> internal routes per client (default
|
|
<code>256</code>). This is designed to help contain DoS attacks where an
|
|
authenticated client floods the server with packets appearing to come
|
|
from many unique MAC addresses, forcing the server to deplete virtual
|
|
memory as its internal routing table expands. This directive can be used
|
|
in a <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file or auto-generated by a
|
|
<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script to override the global value for a particular
|
|
client.</p>
|
|
<p class="last">Note that this directive affects OpenVPN's internal routing table, not
|
|
the kernel routing table.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--opt-verify</span></kbd></td>
|
|
<td><p class="first">Clients that connect with options that are incompatible with those of the
|
|
server will be disconnected.</p>
|
|
<p>Options that will be compared for compatibility include <tt class="docutils literal"><span class="pre">dev-type</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">link-mtu</span></tt>, <tt class="docutils literal"><span class="pre">tun-mtu</span></tt>, <tt class="docutils literal">proto</tt>, <tt class="docutils literal">ifconfig</tt>,
|
|
<tt class="docutils literal"><span class="pre">comp-lzo</span></tt>, <tt class="docutils literal">fragment</tt>, <tt class="docutils literal">keydir</tt>, <tt class="docutils literal">cipher</tt>,
|
|
<tt class="docutils literal">auth</tt>, <tt class="docutils literal">keysize</tt>, <tt class="docutils literal">secret</tt>, <tt class="docutils literal"><span class="pre">no-replay</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">tls-auth</span></tt>, <tt class="docutils literal"><span class="pre">key-method</span></tt>, <tt class="docutils literal"><span class="pre">tls-server</span></tt>
|
|
and <tt class="docutils literal"><span class="pre">tls-client</span></tt>.</p>
|
|
<p class="last">This option requires that <tt class="docutils literal"><span class="pre">--disable-occ</span></tt> NOT be used.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--port-share <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Share OpenVPN TCP with another service</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
port-share host port [dir]
|
|
</pre>
|
|
<p>When run in TCP server mode, share the OpenVPN port with another
|
|
application, such as an HTTPS server. If OpenVPN senses a connection to
|
|
its port which is using a non-OpenVPN protocol, it will proxy the
|
|
connection to the server at <tt class="docutils literal">host</tt>:<tt class="docutils literal">port</tt>. Currently only designed to
|
|
work with HTTP/HTTPS, though it would be theoretically possible to
|
|
extend to other protocols such as ssh.</p>
|
|
<p><tt class="docutils literal">dir</tt> specifies an optional directory where a temporary file with name
|
|
N containing content C will be dynamically generated for each proxy
|
|
connection, where N is the source IP:port of the client connection and C
|
|
is the source IP:port of the connection to the proxy receiver. This
|
|
directory can be used as a dictionary by the proxy receiver to determine
|
|
the origin of the connection. Each generated file will be automatically
|
|
deleted when the proxied connection is torn down.</p>
|
|
<p class="last">Not implemented on Windows.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--push <var>option</var></span></kbd></td>
|
|
<td><p class="first">Push a config file option back to the client for remote execution. Note
|
|
that <tt class="docutils literal">option</tt> must be enclosed in double quotes (<code>""</code>). The
|
|
client must specify <tt class="docutils literal"><span class="pre">--pull</span></tt> in its config file. The set of options
|
|
which can be pushed is limited by both feasibility and security. Some
|
|
options such as those which would execute scripts are banned, since they
|
|
would effectively allow a compromised server to execute arbitrary code
|
|
on the client. Other options such as TLS or MTU parameters cannot be
|
|
pushed because the client needs to know them before the connection to the
|
|
server can be initiated.</p>
|
|
<p class="last">This is a partial list of options which can currently be pushed:
|
|
<tt class="docutils literal"><span class="pre">--route</span></tt>, <tt class="docutils literal"><span class="pre">--route-gateway</span></tt>, <tt class="docutils literal"><span class="pre">--route-delay</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--redirect-gateway</span></tt>, <tt class="docutils literal"><span class="pre">--ip-win32</span></tt>, <tt class="docutils literal"><span class="pre">--dhcp-option</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--inactive</span></tt>, <tt class="docutils literal"><span class="pre">--ping</span></tt>, <tt class="docutils literal"><span class="pre">--ping-exit</span></tt>, <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--setenv</span></tt>, <tt class="docutils literal"><span class="pre">--auth-token</span></tt>, <tt class="docutils literal"><span class="pre">--persist-key</span></tt>, <tt class="docutils literal"><span class="pre">--persist-tun</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--echo</span></tt>, <tt class="docutils literal"><span class="pre">--comp-lzo</span></tt>, <tt class="docutils literal"><span class="pre">--socket-flags</span></tt>, <tt class="docutils literal"><span class="pre">--sndbuf</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--rcvbuf</span></tt></p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--push-remove <var>opt</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Selectively remove all <tt class="docutils literal"><span class="pre">--push</span></tt> options matching "opt" from the option
|
|
list for a client. <tt class="docutils literal">opt</tt> is matched as a substring against the whole
|
|
option string to-be-pushed to the client, so <tt class="docutils literal"><span class="pre">--push-remove</span> route</tt>
|
|
would remove all <tt class="docutils literal"><span class="pre">--push</span> route ...</tt> and <tt class="docutils literal"><span class="pre">--push</span> <span class="pre">route-ipv6</span> ...</tt>
|
|
statements, while <tt class="docutils literal"><span class="pre">--push-remove</span> <span class="pre">"route-ipv6</span> 2001:"</tt> would only remove
|
|
IPv6 routes for <code>2001:...</code> networks.</p>
|
|
<p><tt class="docutils literal"><span class="pre">--push-remove</span></tt> can only be used in a client-specific context, like in
|
|
a <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> file, or <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script or plugin
|
|
-- similar to <tt class="docutils literal"><span class="pre">--push-reset</span></tt>, just more selective.</p>
|
|
<p><em>NOTE</em>: to <em>change</em> an option, <tt class="docutils literal"><span class="pre">--push-remove</span></tt> can be used to first
|
|
remove the old value, and then add a new <tt class="docutils literal"><span class="pre">--push</span></tt> option with the new
|
|
value.</p>
|
|
<p class="last"><em>NOTE 2</em>: due to implementation details, 'ifconfig' and 'ifconfig-ipv6'
|
|
can only be removed with an exact match on the option (
|
|
<code>push-remove ifconfig</code>), no substring matching and no matching on
|
|
the IPv4/IPv6 address argument is possible.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--push-reset</span></kbd></td>
|
|
<td><p class="first">Don't inherit the global push list for a specific client instance.
|
|
Specify this option in a client-specific context such as with a
|
|
<tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> configuration file. This option will ignore
|
|
<tt class="docutils literal"><span class="pre">--push</span></tt> options at the global config file level.</p>
|
|
<p class="last"><em>NOTE</em>: <tt class="docutils literal"><span class="pre">--push-reset</span></tt> is very thorough: it will remove almost
|
|
all options from the list of to-be-pushed options. In many cases,
|
|
some of these options will need to be re-configured afterwards -
|
|
specifically, <tt class="docutils literal"><span class="pre">--topology</span> subnet</tt> and <tt class="docutils literal"><span class="pre">--route-gateway</span></tt> will get
|
|
lost and this will break client configs in many cases. Thus, for most
|
|
purposes, <tt class="docutils literal"><span class="pre">--push-remove</span></tt> is better suited to selectively remove
|
|
push options for individual clients.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--server <var>args</var></span></kbd></td>
|
|
<td><p class="first">A helper directive designed to simplify the configuration of OpenVPN's
|
|
server mode. This directive will set up an OpenVPN server which will
|
|
allocate addresses to clients out of the given network/netmask. The
|
|
server itself will take the <code>.1</code> address of the given network for
|
|
use as the server-side endpoint of the local TUN/TAP interface. If the
|
|
optional <code>nopool</code> flag is given, no dynamic IP address pool will
|
|
prepared for VPN clients.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
server network netmask [nopool]
|
|
</pre>
|
|
<p>For example, <tt class="docutils literal"><span class="pre">--server</span> 10.8.0.0 255.255.255.0</tt> expands as follows:</p>
|
|
<pre class="literal-block">
|
|
mode server
|
|
tls-server
|
|
push "topology [topology]"
|
|
|
|
if dev tun AND (topology == net30 OR topology == p2p):
|
|
ifconfig 10.8.0.1 10.8.0.2
|
|
if !nopool:
|
|
ifconfig-pool 10.8.0.4 10.8.0.251
|
|
route 10.8.0.0 255.255.255.0
|
|
if client-to-client:
|
|
push "route 10.8.0.0 255.255.255.0"
|
|
else if topology == net30:
|
|
push "route 10.8.0.1"
|
|
|
|
if dev tap OR (dev tun AND topology == subnet):
|
|
ifconfig 10.8.0.1 255.255.255.0
|
|
if !nopool:
|
|
ifconfig-pool 10.8.0.2 10.8.0.253 255.255.255.0
|
|
push "route-gateway 10.8.0.1"
|
|
if route-gateway unset:
|
|
route-gateway 10.8.0.2
|
|
</pre>
|
|
<p class="last">Don't use <tt class="docutils literal"><span class="pre">--server</span></tt> if you are ethernet bridging. Use
|
|
<tt class="docutils literal"><span class="pre">--server-bridge</span></tt> instead.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--server-bridge <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">A helper directive similar to <tt class="docutils literal"><span class="pre">--server</span></tt> which is designed to simplify
|
|
the configuration of OpenVPN's server mode in ethernet bridging
|
|
configurations.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
server-bridge gateway netmask pool-start-IP pool-end-IP
|
|
server-bridge [nogw]
|
|
</pre>
|
|
<p>If <tt class="docutils literal"><span class="pre">--server-bridge</span></tt> is used without any parameters, it will enable a
|
|
DHCP-proxy mode, where connecting OpenVPN clients will receive an IP
|
|
address for their TAP adapter from the DHCP server running on the
|
|
OpenVPN server-side LAN. Note that only clients that support the binding
|
|
of a DHCP client with the TAP adapter (such as Windows) can support this
|
|
mode. The optional <code>nogw</code> flag (advanced) indicates that gateway
|
|
information should not be pushed to the client.</p>
|
|
<p>To configure ethernet bridging, you must first use your OS's bridging
|
|
capability to bridge the TAP interface with the ethernet NIC interface.
|
|
For example, on Linux this is done with the <code>brctl</code> tool, and with
|
|
Windows XP it is done in the Network Connections Panel by selecting the
|
|
ethernet and TAP adapters and right-clicking on "Bridge Connections".</p>
|
|
<p>Next you you must manually set the IP/netmask on the bridge interface.
|
|
The <tt class="docutils literal">gateway</tt> and <tt class="docutils literal">netmask</tt> parameters to <tt class="docutils literal"><span class="pre">--server-bridge</span></tt> can be
|
|
set to either the IP/netmask of the bridge interface, or the IP/netmask
|
|
of the default gateway/router on the bridged subnet.</p>
|
|
<p>Finally, set aside a IP range in the bridged subnet, denoted by
|
|
<tt class="docutils literal"><span class="pre">pool-start-IP</span></tt> and <tt class="docutils literal"><span class="pre">pool-end-IP</span></tt>, for OpenVPN to allocate to
|
|
connecting clients.</p>
|
|
<p>For example, <tt class="docutils literal"><span class="pre">server-bridge</span> 10.8.0.4 255.255.255.0 10.8.0.128
|
|
10.8.0.254</tt> expands as follows:</p>
|
|
<pre class="literal-block">
|
|
mode server
|
|
tls-server
|
|
|
|
ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0
|
|
push "route-gateway 10.8.0.4"
|
|
</pre>
|
|
<p>In another example, <tt class="docutils literal"><span class="pre">--server-bridge</span></tt> (without parameters) expands as
|
|
follows:</p>
|
|
<pre class="literal-block">
|
|
mode server
|
|
tls-server
|
|
|
|
push "route-gateway dhcp"
|
|
</pre>
|
|
<p>Or <tt class="docutils literal"><span class="pre">--server-bridge</span> nogw</tt> expands as follows:</p>
|
|
<pre class="last literal-block">
|
|
mode server
|
|
tls-server
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--server-ipv6 <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Convenience-function to enable a number of IPv6 related options at once,
|
|
namely <tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt>, <tt class="docutils literal"><span class="pre">--ifconfig-ipv6-pool</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">--push</span> <span class="pre">tun-ipv6</span></tt>.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
server-ipv6 ipv6addr/bits
|
|
</pre>
|
|
<p class="last">Pushing of the <tt class="docutils literal"><span class="pre">--tun-ipv6</span></tt> directive is done for older clients which
|
|
require an explicit <tt class="docutils literal"><span class="pre">--tun-ipv6</span></tt> in their configuration.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--stale-routes-check <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Remove routes which haven't had activity for <tt class="docutils literal">n</tt> seconds (i.e. the ageing
|
|
time). This check is run every <tt class="docutils literal">t</tt> seconds (i.e. check interval).</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
stale-routes-check n [t]
|
|
</pre>
|
|
<p>If <tt class="docutils literal">t</tt> is not present it defaults to <tt class="docutils literal">n</tt>.</p>
|
|
<p class="last">This option helps to keep the dynamic routing table small. See also
|
|
<tt class="docutils literal"><span class="pre">--max-routes-per-client</span></tt></p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--username-as-common-name</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Use the authenticated username as the common-name, rather than the
|
|
common-name from the client certificate. Requires that some form of
|
|
<tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> verification is in effect. As the replacement happens
|
|
after <tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> verification, the verification script or
|
|
plugin will still receive the common-name from the certificate.</p>
|
|
<p class="last">The common_name environment variable passed to scripts and plugins invoked
|
|
after authentication (e.g, client-connect script) and file names parsed in
|
|
client-config directory will match the username.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--verify-client-cert <var>mode</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Specify whether the client is required to supply a valid certificate.</p>
|
|
<p>Possible <tt class="docutils literal">mode</tt> options are:</p>
|
|
<dl class="docutils">
|
|
<dt><code>none</code></dt>
|
|
<dd><p class="first">A client certificate is not required. the client needs to
|
|
authenticate using username/password only. Be aware that using this
|
|
directive is less secure than requiring certificates from all
|
|
clients.</p>
|
|
<p>If you use this directive, the entire responsibility of authentication
|
|
will rest on your <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script, so keep in mind
|
|
that bugs in your script could potentially compromise the security of
|
|
your VPN.</p>
|
|
<p class="last"><tt class="docutils literal"><span class="pre">--verify-client-cert</span> none</tt> is functionally equivalent to
|
|
<tt class="docutils literal"><span class="pre">--client-cert-not-required</span></tt>.</p>
|
|
</dd>
|
|
<dt><code>optional</code></dt>
|
|
<dd><p class="first">A client may present a certificate but it is not required to do so.
|
|
When using this directive, you should also use a
|
|
<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script to ensure that clients are
|
|
authenticated using a certificate, a username and password, or
|
|
possibly even both.</p>
|
|
<p class="last">Again, the entire responsibility of authentication will rest on your
|
|
<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script, so keep in mind that bugs in your
|
|
script could potentially compromise the security of your VPN.</p>
|
|
</dd>
|
|
<dt><code>require</code></dt>
|
|
<dd>This is the default option. A client is required to present a
|
|
certificate, otherwise VPN access is refused.</dd>
|
|
</dl>
|
|
<p class="last">If you don't use this directive (or use <tt class="docutils literal"><span class="pre">--verify-client-cert</span> require</tt>)
|
|
but you also specify an <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script, then OpenVPN
|
|
will perform double authentication. The client certificate verification
|
|
AND the <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script will need to succeed in order
|
|
for a client to be authenticated and accepted onto the VPN.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--vlan-tagging</span></kbd></td>
|
|
<td><p class="first">Server-only option. Turns the OpenVPN server instance into a switch that
|
|
understands VLAN-tagging, based on IEEE 802.1Q.</p>
|
|
<p>The server TAP device and each of the connecting clients is seen as a
|
|
port of the switch. All client ports are in untagged mode and the server
|
|
TAP device is VLAN-tagged, untagged or accepts both, depending on the
|
|
<tt class="docutils literal"><span class="pre">--vlan-accept</span></tt> setting.</p>
|
|
<p>Ethernet frames with a prepended 802.1Q tag are called "tagged". If the
|
|
VLAN Identifier (VID) field in such a tag is non-zero, the frame is
|
|
called "VLAN-tagged". If the VID is zero, but the Priority Control Point
|
|
(PCP) field is non-zero, the frame is called "prio-tagged". If there is
|
|
no 802.1Q tag, the frame is "untagged".</p>
|
|
<p>Using the <tt class="docutils literal"><span class="pre">--vlan-pvid</span> v</tt> option once per client (see
|
|
--client-config-dir), each port can be associated with a certain VID.
|
|
Packets can only be forwarded between ports having the same VID.
|
|
Therefore, clients with differing VIDs are completely separated from
|
|
one-another, even if <tt class="docutils literal"><span class="pre">--client-to-client</span></tt> is activated.</p>
|
|
<p>The packet filtering takes place in the OpenVPN server. Clients should
|
|
not have any VLAN tagging configuration applied.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">--vlan-tagging</span></tt> option is off by default. While turned off,
|
|
OpenVPN accepts any Ethernet frame and does not perform any special
|
|
processing for VLAN-tagged packets.</p>
|
|
<p class="last">This option can only be activated in <tt class="docutils literal"><span class="pre">--dev</span> tap mode</tt>.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--vlan-accept <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Configure the VLAN tagging policy for the server TAP device.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
vlan-accept all|tagged|untagged
|
|
</pre>
|
|
<p>The following modes are available:</p>
|
|
<dl class="docutils">
|
|
<dt><code>tagged</code></dt>
|
|
<dd>Admit only VLAN-tagged frames. Only VLAN-tagged packets are accepted,
|
|
while untagged or priority-tagged packets are dropped when entering
|
|
the server TAP device.</dd>
|
|
<dt><code>untagged</code></dt>
|
|
<dd>Admit only untagged and prio-tagged frames. VLAN-tagged packets are
|
|
not accepted, while untagged or priority-tagged packets entering the
|
|
server TAP device are tagged with the value configured for the global
|
|
<tt class="docutils literal"><span class="pre">--vlan-pvid</span></tt> setting.</dd>
|
|
<dt><code>all</code> (default)</dt>
|
|
<dd>Admit all frames. All packets are admitted and then treated like
|
|
untagged or tagged mode respectively.</dd>
|
|
<dt><em>Note</em>:</dt>
|
|
<dd>Some vendors refer to switch ports running in <code>tagged</code> mode
|
|
as "trunk ports" and switch ports running in <code>untagged</code> mode
|
|
as "access ports".</dd>
|
|
</dl>
|
|
<p>Packets forwarded from clients to the server are VLAN-tagged with the
|
|
originating client's PVID, unless the VID matches the global
|
|
<tt class="docutils literal"><span class="pre">--vlan-pvid</span></tt>, in which case the tag is removed.</p>
|
|
<p class="last">If no <em>PVID</em> is configured for a given client (see --vlan-pvid) packets
|
|
are tagged with 1 by default.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--vlan-pvid <var>v</var></span></kbd></td>
|
|
<td><p class="first">Specifies which VLAN identifier a "port" is associated with. Only valid
|
|
when <tt class="docutils literal"><span class="pre">--vlan-tagging</span></tt> is speficied.</p>
|
|
<p>In the client context, the setting specifies which VLAN ID a client is
|
|
associated with. In the global context, the VLAN ID of the server TAP
|
|
device is set. The latter only makes sense for <tt class="docutils literal"><span class="pre">--vlan-accept</span>
|
|
untagged</tt> and <tt class="docutils literal"><span class="pre">--vlan-accept</span> all</tt> modes.</p>
|
|
<p>Valid values for <tt class="docutils literal">v</tt> go from <code>1</code> through to <code>4094</code>. The
|
|
global value defaults to <code>1</code>. If no <tt class="docutils literal"><span class="pre">--vlan-pvid</span></tt> is specified in
|
|
the client context, the global value is inherited.</p>
|
|
<p class="last">In some switch implementations, the <em>PVID</em> is also referred to as "Native
|
|
VLAN".</p>
|
|
</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="encryption-options">
|
|
<h1>Encryption Options</h1>
|
|
<div class="section" id="ssl-library-information">
|
|
<h2>SSL Library information</h2>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--show-ciphers</span></kbd></td>
|
|
<td>(Standalone) Show all cipher algorithms to use with the <tt class="docutils literal"><span class="pre">--cipher</span></tt>
|
|
option.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--show-digests</span></kbd></td>
|
|
<td>(Standalone) Show all message digest algorithms to use with the
|
|
<tt class="docutils literal"><span class="pre">--auth</span></tt> option.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--show-tls</span></kbd></td>
|
|
<td><p class="first">(Standalone) Show all TLS ciphers supported by the crypto library.
|
|
OpenVPN uses TLS to secure the control channel, over which the keys that
|
|
are used to protect the actual VPN traffic are exchanged. The TLS
|
|
ciphers will be sorted from highest preference (most secure) to lowest.</p>
|
|
<p class="last">Be aware that whether a cipher suite in this list can actually work
|
|
depends on the specific setup of both peers (e.g. both peers must
|
|
support the cipher, and an ECDSA cipher suite will not work if you are
|
|
using an RSA certificate, etc.).</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--show-engines</span></kbd></td>
|
|
<td>(Standalone) Show currently available hardware-based crypto acceleration
|
|
engines supported by the OpenSSL library.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--show-groups</span></kbd></td>
|
|
<td>(Standalone) Show all available elliptic curves/groups to use with the
|
|
<tt class="docutils literal"><span class="pre">--ecdh-curve</span></tt> and <tt class="docutils literal"><span class="pre">tls-groups</span></tt> options.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="generating-key-material">
|
|
<h2>Generating key material</h2>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--genkey <var>args</var></span></kbd></td>
|
|
<td><p class="first">(Standalone) Generate a key to be used of the type keytype. if keyfile
|
|
is left out or empty the key will be output on stdout. See the following
|
|
sections for the different keytypes.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
--genkey keytype keyfile
|
|
</pre>
|
|
<p>Valid keytype arguments are:</p>
|
|
<p><code>secret</code> Standard OpenVPN shared secret keys</p>
|
|
<p><code>tls-crypt</code> Alias for <code>secret</code></p>
|
|
<p><code>tls-auth</code> Alias for <code>secret</code></p>
|
|
<p><code>auth-token</code> Key used for <tt class="docutils literal"><span class="pre">--auth-gen-token-key</span></tt></p>
|
|
<p><code>tls-crypt-v2-server</code> TLS Crypt v2 server key</p>
|
|
<p><code>tls-crypt-v2-client</code> TLS Crypt v2 client key</p>
|
|
<p>Examples:</p>
|
|
<pre class="literal-block">
|
|
$ openvpn --genkey secret shared.key
|
|
$ openvpn --genkey tls-crypt shared.key
|
|
$ openvpn --genkey tls-auth shared.key
|
|
$ openvpn --genkey tls-crypt-v2-server v2crypt-server.key
|
|
$ openvpn --tls-crypt-v2 v2crypt-server.key --genkey tls-crypt-v2-client v2crypt-client-1.key
|
|
</pre>
|
|
<ul class="last">
|
|
<li><p class="first">Generating <em>Shared Secret Keys</em>
|
|
Generate a shared secret, for use with the <tt class="docutils literal"><span class="pre">--secret</span></tt>, <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>
|
|
or <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> options.</p>
|
|
<p>Syntax:</p>
|
|
<pre class="literal-block">
|
|
$ openvpn --genkey secret|tls-crypt|tls-auth keyfile
|
|
</pre>
|
|
<p>The key is saved in <tt class="docutils literal">keyfile</tt>. All three variants (<tt class="docutils literal"><span class="pre">--secret</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">tls-crypt</span></tt> and <tt class="docutils literal"><span class="pre">tls-auth</span></tt>) generate the same type of key. The
|
|
aliases are added for convenience.</p>
|
|
<p>If using this for <tt class="docutils literal"><span class="pre">--secret</span></tt>, this file must be shared with the peer
|
|
over a pre-existing secure channel such as <tt class="docutils literal">scp</tt>(1).</p>
|
|
</li>
|
|
<li><p class="first">Generating <em>TLS Crypt v2 Server key</em>
|
|
Generate a <tt class="docutils literal"><span class="pre">--tls-crypt-v2</span></tt> key to be used by an OpenVPN server.
|
|
The key is stored in <tt class="docutils literal">keyfile</tt>.</p>
|
|
<p>Syntax:</p>
|
|
<pre class="literal-block">
|
|
--genkey tls-crypt-v2-server keyfile
|
|
</pre>
|
|
</li>
|
|
<li><p class="first">Generating <em>TLS Crypt v2 Client key</em>
|
|
Generate a --tls-crypt-v2 key to be used by OpenVPN clients. The
|
|
key is stored in <tt class="docutils literal">keyfile</tt>.</p>
|
|
<p>Syntax</p>
|
|
<pre class="literal-block">
|
|
--genkey tls-crypt-v2-client keyfile [metadata]
|
|
</pre>
|
|
<p>If supplied, include the supplied <tt class="docutils literal">metadata</tt> in the wrapped client
|
|
key. This metadata must be supplied in base64-encoded form. The
|
|
metadata must be at most 735 bytes long (980 bytes in base64).</p>
|
|
<p>If no metadata is supplied, OpenVPN will use a 64-bit unix timestamp
|
|
representing the current time in UTC, encoded in network order, as
|
|
metadata for the generated key.</p>
|
|
<p>A tls-crypt-v2 client key is wrapped using a server key. To generate a
|
|
client key, the user must therefore supply the server key using the
|
|
<tt class="docutils literal"><span class="pre">--tls-crypt-v2</span></tt> option.</p>
|
|
<p>Servers can use <tt class="docutils literal"><span class="pre">--tls-crypt-v2-verify</span></tt> to specify a metadata
|
|
verification command.</p>
|
|
</li>
|
|
<li><p class="first">Generate <em>Authentication Token key</em>
|
|
Generate a new secret that can be used with <strong>--auth-gen-token-secret</strong></p>
|
|
<p>Syntax:</p>
|
|
<pre class="literal-block">
|
|
--genkey auth-token [keyfile]
|
|
</pre>
|
|
<dl class="docutils">
|
|
<dt><em>Note:</em></dt>
|
|
<dd><p class="first last">This file should be kept secret to the server as anyone that has
|
|
access to this file will be able to generate auth tokens that the
|
|
OpenVPN server will accept as valid.</p>
|
|
</dd>
|
|
</dl>
|
|
</li>
|
|
</ul>
|
|
</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="data-channel-renegotiation">
|
|
<h2>Data Channel Renegotiation</h2>
|
|
<p>When running OpenVPN in client/server mode, the data channel will use a
|
|
separate ephemeral encryption key which is rotated at regular intervals.</p>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--reneg-bytes <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Renegotiate data channel key after <tt class="docutils literal">n</tt> bytes sent or received
|
|
(disabled by default with an exception, see below). OpenVPN allows the
|
|
lifetime of a key to be expressed as a number of bytes
|
|
encrypted/decrypted, a number of packets, or a number of seconds. A key
|
|
renegotiation will be forced if any of these three criteria are met by
|
|
either peer.</p>
|
|
<p class="last">If using ciphers with cipher block sizes less than 128-bits,
|
|
<tt class="docutils literal"><span class="pre">--reneg-bytes</span></tt> is set to 64MB by default, unless it is explicitly
|
|
disabled by setting the value to <code>0</code>, but this is
|
|
<strong>HIGHLY DISCOURAGED</strong> as this is designed to add some protection against
|
|
the SWEET32 attack vector. For more information see the <tt class="docutils literal"><span class="pre">--cipher</span></tt>
|
|
option.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--reneg-pkts <var>n</var></span></kbd></td>
|
|
<td>Renegotiate data channel key after <strong>n</strong> packets sent and received
|
|
(disabled by default).</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--reneg-sec <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Renegotiate data channel key after at most <tt class="docutils literal">max</tt> seconds
|
|
(default <code>3600</code>) and at least <tt class="docutils literal">min</tt> seconds (default is 90% of
|
|
<tt class="docutils literal">max</tt> for servers, and equal to <tt class="docutils literal">max</tt> for clients).</p>
|
|
<pre class="literal-block">
|
|
reneg-sec max [min]
|
|
</pre>
|
|
<p>The effective <tt class="docutils literal"><span class="pre">--reneg-sec</span></tt> value used is per session
|
|
pseudo-uniform-randomized between <tt class="docutils literal">min</tt> and <tt class="docutils literal">max</tt>.</p>
|
|
<p>With the default value of <code>3600</code> this results in an effective per
|
|
session value in the range of <code>3240</code> .. <code>3600</code> seconds for
|
|
servers, or just 3600 for clients.</p>
|
|
<p>When using dual-factor authentication, note that this default value may
|
|
cause the end user to be challenged to reauthorize once per hour.</p>
|
|
<p class="last">Also, keep in mind that this option can be used on both the client and
|
|
server, and whichever uses the lower value will be the one to trigger
|
|
the renegotiation. A common mistake is to set <tt class="docutils literal"><span class="pre">--reneg-sec</span></tt> to a
|
|
higher value on either the client or server, while the other side of the
|
|
connection is still using the default value of <code>3600</code> seconds,
|
|
meaning that the renegotiation will still occur once per <code>3600</code>
|
|
seconds. The solution is to increase --reneg-sec on both the client and
|
|
server, or set it to <code>0</code> on one side of the connection (to
|
|
disable), and to your chosen value on the other side.</p>
|
|
</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="tls-mode-options">
|
|
<h2>TLS Mode Options</h2>
|
|
<p>TLS mode is the most powerful crypto mode of OpenVPN in both security
|
|
and flexibility. TLS mode works by establishing control and data
|
|
channels which are multiplexed over a single TCP/UDP port. OpenVPN
|
|
initiates a TLS session over the control channel and uses it to exchange
|
|
cipher and HMAC keys to protect the data channel. TLS mode uses a robust
|
|
reliability layer over the UDP connection for all control channel
|
|
communication, while the data channel, over which encrypted tunnel data
|
|
passes, is forwarded without any mediation. The result is the best of
|
|
both worlds: a fast data channel that forwards over UDP with only the
|
|
overhead of encrypt, decrypt, and HMAC functions, and a control channel
|
|
that provides all of the security features of TLS, including
|
|
certificate-based authentication and Diffie Hellman forward secrecy.</p>
|
|
<p>To use TLS mode, each peer that runs OpenVPN should have its own local
|
|
certificate/key pair (<tt class="docutils literal"><span class="pre">--cert</span></tt> and <tt class="docutils literal"><span class="pre">--key</span></tt>), signed by the root
|
|
certificate which is specified in <tt class="docutils literal"><span class="pre">--ca</span></tt>.</p>
|
|
<p>When two OpenVPN peers connect, each presents its local certificate to
|
|
the other. Each peer will then check that its partner peer presented a
|
|
certificate which was signed by the master root certificate as specified
|
|
in <tt class="docutils literal"><span class="pre">--ca</span></tt>.</p>
|
|
<p>If that check on both peers succeeds, then the TLS negotiation will
|
|
succeed, both OpenVPN peers will exchange temporary session keys, and
|
|
the tunnel will begin passing data.</p>
|
|
<p>The OpenVPN project provides a set of scripts for managing RSA
|
|
certificates and keys: <a class="reference external" href="https://github.com/OpenVPN/easy-rsa">https://github.com/OpenVPN/easy-rsa</a></p>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--askpass <var>file</var></span></kbd></td>
|
|
<td><p class="first">Get certificate password from console or <tt class="docutils literal">file</tt> before we daemonize.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
askpass
|
|
askpass file
|
|
</pre>
|
|
<p>For the extremely security conscious, it is possible to protect your
|
|
private key with a password. Of course this means that every time the
|
|
OpenVPN daemon is started you must be there to type the password. The
|
|
<tt class="docutils literal"><span class="pre">--askpass</span></tt> option allows you to start OpenVPN from the command line.
|
|
It will query you for a password before it daemonizes. To protect a
|
|
private key with a password you should omit the <tt class="docutils literal"><span class="pre">-nodes</span></tt> option when
|
|
you use the <tt class="docutils literal">openssl</tt> command line tool to manage certificates and
|
|
private keys.</p>
|
|
<p class="last">If <tt class="docutils literal">file</tt> is specified, read the password from the first line of
|
|
<tt class="docutils literal">file</tt>. Keep in mind that storing your password in a file to a certain
|
|
extent invalidates the extra security provided by using an encrypted
|
|
key.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--ca <var>file</var></span></kbd></td>
|
|
<td><p class="first">Certificate authority (CA) file in .pem format, also referred to as the
|
|
<em>root</em> certificate. This file can have multiple certificates in .pem
|
|
format, concatenated together. You can construct your own certificate
|
|
authority certificate and private key by using a command such as:</p>
|
|
<pre class="literal-block">
|
|
openssl req -nodes -new -x509 -keyout ca.key -out ca.crt
|
|
</pre>
|
|
<p>Then edit your openssl.cnf file and edit the <tt class="docutils literal">certificate</tt> variable to
|
|
point to your new root certificate <tt class="docutils literal">ca.crt</tt>.</p>
|
|
<p class="last">For testing purposes only, the OpenVPN distribution includes a sample CA
|
|
certificate (ca.crt). Of course you should never use the test
|
|
certificates and test keys distributed with OpenVPN in a production
|
|
environment, since by virtue of the fact that they are distributed with
|
|
OpenVPN, they are totally insecure.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--capath <var>dir</var></span></kbd></td>
|
|
<td><p class="first">Directory containing trusted certificates (CAs and CRLs). Not available
|
|
with mbed TLS.</p>
|
|
<p>CAs in the capath directory are expected to be named <hash>.<n>. CRLs
|
|
are expected to be named <hash>.r<n>. See the <tt class="docutils literal"><span class="pre">-CApath</span></tt> option of
|
|
<tt class="docutils literal">openssl verify</tt>, and the <tt class="docutils literal"><span class="pre">-hash</span></tt> option of <tt class="docutils literal">openssl x509</tt>,
|
|
<tt class="docutils literal">openssl crl</tt> and <tt class="docutils literal">X509_LOOKUP_hash_dir()</tt>(3)
|
|
for more information.</p>
|
|
<p class="last">Similar to the <tt class="docutils literal"><span class="pre">--crl-verify</span></tt> option, CRLs are not mandatory -
|
|
OpenVPN will log the usual warning in the logs if the relevant CRL is
|
|
missing, but the connection will be allowed.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--cert <var>file</var></span></kbd></td>
|
|
<td><p class="first">Local peer's signed certificate in .pem format -- must be signed by a
|
|
certificate authority whose certificate is in <tt class="docutils literal"><span class="pre">--ca</span> file</tt>. Each peer
|
|
in an OpenVPN link running in TLS mode should have its own certificate
|
|
and private key file. In addition, each certificate should have been
|
|
signed by the key of a certificate authority whose public key resides in
|
|
the <tt class="docutils literal"><span class="pre">--ca</span></tt> certificate authority file. You can easily make your own
|
|
certificate authority (see above) or pay money to use a commercial
|
|
service such as thawte.com (in which case you will be helping to finance
|
|
the world's second space tourist :). To generate a certificate, you can
|
|
use a command such as:</p>
|
|
<pre class="literal-block">
|
|
openssl req -nodes -new -keyout mycert.key -out mycert.csr
|
|
</pre>
|
|
<p>If your certificate authority private key lives on another machine, copy
|
|
the certificate signing request (mycert.csr) to this other machine (this
|
|
can be done over an insecure channel such as email). Now sign the
|
|
certificate with a command such as:</p>
|
|
<pre class="literal-block">
|
|
openssl ca -out mycert.crt -in mycert.csr
|
|
</pre>
|
|
<p class="last">Now copy the certificate (mycert.crt) back to the peer which initially
|
|
generated the .csr file (this can be over a public medium). Note that
|
|
the <tt class="docutils literal">openssl ca</tt> command reads the location of the certificate
|
|
authority key from its configuration file such as
|
|
<code>/usr/share/ssl/openssl.cnf</code> -- note also that for certificate
|
|
authority functions, you must set up the files <code>index.txt</code> (may be
|
|
empty) and <code>serial</code> (initialize to <code>01</code>).</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--crl-verify <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Check peer certificate against a Certificate Revocation List.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
crl-verify file/directory flag
|
|
</pre>
|
|
<p>Examples:</p>
|
|
<pre class="literal-block">
|
|
crl-verify crl-file.pem
|
|
crl-verify /etc/openvpn/crls dir
|
|
</pre>
|
|
<p>A CRL (certificate revocation list) is used when a particular key is
|
|
compromised but when the overall PKI is still intact.</p>
|
|
<p>Suppose you had a PKI consisting of a CA, root certificate, and a number
|
|
of client certificates. Suppose a laptop computer containing a client
|
|
key and certificate was stolen. By adding the stolen certificate to the
|
|
CRL file, you could reject any connection which attempts to use it,
|
|
while preserving the overall integrity of the PKI.</p>
|
|
<p>The only time when it would be necessary to rebuild the entire PKI from
|
|
scratch would be if the root certificate key itself was compromised.</p>
|
|
<p>The option is not mandatory - if the relevant CRL is missing, OpenVPN
|
|
will log a warning in the logs - e.g.</p>
|
|
<pre class="literal-block">
|
|
VERIFY WARNING: depth=0, unable to get certificate CRL
|
|
</pre>
|
|
<p>but the connection will be allowed. If the optional <code>dir</code> flag
|
|
is specified, enable a different mode where the <tt class="docutils literal"><span class="pre">crl-verify</span></tt> is
|
|
pointed at a directory containing files named as revoked serial numbers
|
|
(the files may be empty, the contents are never read). If a client
|
|
requests a connection, where the client certificate serial number
|
|
(decimal string) is the name of a file present in the directory, it will
|
|
be rejected.</p>
|
|
<dl class="last docutils">
|
|
<dt><em>Note:</em></dt>
|
|
<dd>As the crl file (or directory) is read every time a peer
|
|
connects, if you are dropping root privileges with
|
|
<tt class="docutils literal"><span class="pre">--user</span></tt>, make sure that this user has sufficient
|
|
privileges to read the file.</dd>
|
|
</dl>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--dh <var>file</var></span></kbd></td>
|
|
<td><p class="first">File containing Diffie Hellman parameters in .pem format (required for
|
|
<tt class="docutils literal"><span class="pre">--tls-server</span></tt> only).</p>
|
|
<p>Set <tt class="docutils literal">file</tt> to <code>none</code> to disable Diffie Hellman key exchange (and
|
|
use ECDH only). Note that this requires peers to be using an SSL library
|
|
that supports ECDH TLS cipher suites (e.g. OpenSSL 1.0.1+, or
|
|
mbed TLS 2.0+).</p>
|
|
<p class="last">Use <tt class="docutils literal">openssl dhparam <span class="pre">-out</span> dh2048.pem 2048</tt> to generate 2048-bit DH
|
|
parameters. Diffie Hellman parameters may be considered public.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ecdh-curve <var>name</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Specify the curve to use for elliptic curve Diffie Hellman. Available
|
|
curves can be listed with <tt class="docutils literal"><span class="pre">--show-curves</span></tt>. The specified curve will
|
|
only be used for ECDH TLS-ciphers.</p>
|
|
<p class="last">This option is not supported in mbed TLS builds of OpenVPN.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--extra-certs <var>file</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Specify a <tt class="docutils literal">file</tt> containing one or more PEM certs (concatenated
|
|
together) that complete the local certificate chain.</p>
|
|
<p class="last">This option is useful for "split" CAs, where the CA for server certs is
|
|
different than the CA for client certs. Putting certs in this file
|
|
allows them to be used to complete the local certificate chain without
|
|
trusting them to verify the peer-submitted certificate, as would be the
|
|
case if the certs were placed in the <tt class="docutils literal">ca</tt> file.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--hand-window <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Handshake Window -- the TLS-based key exchange must finalize within
|
|
<tt class="docutils literal">n</tt> seconds of handshake initiation by any peer (default <code>60</code>
|
|
seconds). If the handshake fails we will attempt to reset our connection
|
|
with our peer and try again. Even in the event of handshake failure we
|
|
will still use our expiring key for up to <tt class="docutils literal"><span class="pre">--tran-window</span></tt> seconds to
|
|
maintain continuity of transmission of tunnel data.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--key <var>file</var></span></kbd></td>
|
|
<td>Local peer's private key in .pem format. Use the private key which was
|
|
generated when you built your peer's certificate (see <tt class="docutils literal"><span class="pre">--cert</span> file</tt>
|
|
above).</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--pkcs12 <var>file</var></span></kbd></td>
|
|
<td>Specify a PKCS #12 file containing local private key, local certificate,
|
|
and root CA certificate. This option can be used instead of <tt class="docutils literal"><span class="pre">--ca</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--cert</span></tt>, and <tt class="docutils literal"><span class="pre">--key</span></tt>. Not available with mbed TLS.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--remote-cert-eku <var>oid</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Require that peer certificate was signed with an explicit <em>extended key
|
|
usage</em>.</p>
|
|
<p>This is a useful security option for clients, to ensure that the host
|
|
they connect to is a designated server.</p>
|
|
<p class="last">The extended key usage should be encoded in <em>oid notation</em>, or <em>OpenSSL
|
|
symbolic representation</em>.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--remote-cert-ku <var>key-usage</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Require that peer certificate was signed with an explicit
|
|
<tt class="docutils literal"><span class="pre">key-usage</span></tt>.</p>
|
|
<p>If present in the certificate, the <code>keyUsage</code> value is validated by
|
|
the TLS library during the TLS handshake. Specifying this option without
|
|
arguments requires this extension to be present (so the TLS library will
|
|
verify it).</p>
|
|
<p>If <tt class="docutils literal"><span class="pre">key-usage</span></tt> is a list of usage bits, the <code>keyUsage</code> field
|
|
must have <em>at least</em> the same bits set as the bits in <em>one of</em> the values
|
|
supplied in the <tt class="docutils literal"><span class="pre">key-usage</span></tt> list.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">key-usage</span></tt> values in the list must be encoded in hex, e.g.</p>
|
|
<pre class="last literal-block">
|
|
remote-cert-ku a0
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--remote-cert-tls <var>type</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Require that peer certificate was signed with an explicit <em>key usage</em>
|
|
and <em>extended key usage</em> based on RFC3280 TLS rules.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
remote-cert-tls server
|
|
remote-cert-tls client
|
|
</pre>
|
|
<p>This is a useful security option for clients, to ensure that the host
|
|
they connect to is a designated server. Or the other way around; for a
|
|
server to verify that only hosts with a client certificate can connect.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">--remote-cert-tls</span> client</tt> option is equivalent to</p>
|
|
<pre class="literal-block">
|
|
remote-cert-ku
|
|
remote-cert-eku "TLS Web Client Authentication"
|
|
</pre>
|
|
<p>The <tt class="docutils literal"><span class="pre">--remote-cert-tls</span> server</tt> option is equivalent to</p>
|
|
<pre class="literal-block">
|
|
remote-cert-ku
|
|
remote-cert-eku "TLS Web Server Authentication"
|
|
</pre>
|
|
<p class="last">This is an important security precaution to protect against a
|
|
man-in-the-middle attack where an authorized client attempts to connect
|
|
to another client by impersonating the server. The attack is easily
|
|
prevented by having clients verify the server certificate using any one
|
|
of <tt class="docutils literal"><span class="pre">--remote-cert-tls</span></tt>, <tt class="docutils literal"><span class="pre">--verify-x509-name</span></tt>, or <tt class="docutils literal"><span class="pre">--tls-verify</span></tt>.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tls-auth <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Add an additional layer of HMAC authentication on top of the TLS control
|
|
channel to mitigate DoS attacks and attacks on the TLS stack.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
tls-auth file
|
|
tls-auth file 0
|
|
tls-auth file 1
|
|
</pre>
|
|
<p>In a nutshell, <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> enables a kind of "HMAC firewall" on
|
|
OpenVPN's TCP/UDP port, where TLS control channel packets bearing an
|
|
incorrect HMAC signature can be dropped immediately without response.</p>
|
|
<p><tt class="docutils literal">file</tt> (required) is a file in OpenVPN static key format which can be
|
|
generated by <tt class="docutils literal"><span class="pre">--genkey</span></tt>.</p>
|
|
<p>Older versions (up to OpenVPN 2.3) supported a freeform passphrase file.
|
|
This is no longer supported in newer versions (v2.4+).</p>
|
|
<p>See the <tt class="docutils literal"><span class="pre">--secret</span></tt> option for more information on the optional
|
|
<tt class="docutils literal">direction</tt> parameter.</p>
|
|
<p><tt class="docutils literal"><span class="pre">--tls-auth</span></tt> is recommended when you are running OpenVPN in a mode
|
|
where it is listening for packets from any IP address, such as when
|
|
<tt class="docutils literal"><span class="pre">--remote</span></tt> is not specified, or <tt class="docutils literal"><span class="pre">--remote</span></tt> is specified with
|
|
<tt class="docutils literal"><span class="pre">--float</span></tt>.</p>
|
|
<p>The rationale for this feature is as follows. TLS requires a
|
|
multi-packet exchange before it is able to authenticate a peer. During
|
|
this time before authentication, OpenVPN is allocating resources (memory
|
|
and CPU) to this potential peer. The potential peer is also exposing
|
|
many parts of OpenVPN and the OpenSSL library to the packets it is
|
|
sending. Most successful network attacks today seek to either exploit
|
|
bugs in programs (such as buffer overflow attacks) or force a program to
|
|
consume so many resources that it becomes unusable. Of course the first
|
|
line of defense is always to produce clean, well-audited code. OpenVPN
|
|
has been written with buffer overflow attack prevention as a top
|
|
priority. But as history has shown, many of the most widely used network
|
|
applications have, from time to time, fallen to buffer overflow attacks.</p>
|
|
<p>So as a second line of defense, OpenVPN offers this special layer of
|
|
authentication on top of the TLS control channel so that every packet on
|
|
the control channel is authenticated by an HMAC signature and a unique
|
|
ID for replay protection. This signature will also help protect against
|
|
DoS (Denial of Service) attacks. An important rule of thumb in reducing
|
|
vulnerability to DoS attacks is to minimize the amount of resources a
|
|
potential, but as yet unauthenticated, client is able to consume.</p>
|
|
<p><tt class="docutils literal"><span class="pre">--tls-auth</span></tt> does this by signing every TLS control channel packet
|
|
with an HMAC signature, including packets which are sent before the TLS
|
|
level has had a chance to authenticate the peer. The result is that
|
|
packets without the correct signature can be dropped immediately upon
|
|
reception, before they have a chance to consume additional system
|
|
resources such as by initiating a TLS handshake. <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> can be
|
|
strengthened by adding the <tt class="docutils literal"><span class="pre">--replay-persist</span></tt> option which will keep
|
|
OpenVPN's replay protection state in a file so that it is not lost
|
|
across restarts.</p>
|
|
<p>It should be emphasized that this feature is optional and that the key
|
|
file used with <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> gives a peer nothing more than the power
|
|
to initiate a TLS handshake. It is not used to encrypt or authenticate
|
|
any tunnel data.</p>
|
|
<p class="last">Use <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> instead if you want to use the key file to not only
|
|
authenticate, but also encrypt the TLS control channel.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tls-groups <var>list</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">A list of allowable groups/curves in order of preference.</p>
|
|
<p>Set the allowed elliptic curves/groups for the TLS session.
|
|
These groups are allowed to be used in signatures and key exchange.</p>
|
|
<p>mbedTLS currently allows all known curves per default.</p>
|
|
<p>OpenSSL 1.1+ restricts the list per default to</p>
|
|
<pre class="literal-block">
|
|
"X25519:secp256r1:X448:secp521r1:secp384r1".
|
|
</pre>
|
|
<p>If you use certificates that use non-standard curves, you
|
|
might need to add them here. If you do not force the ecdh curve
|
|
by using <tt class="docutils literal"><span class="pre">--ecdh-curve</span></tt>, the groups for ecdh will also be picked
|
|
from this list.</p>
|
|
<p>OpenVPN maps the curve name <cite>secp256r1</cite> to <cite>prime256v1</cite> to allow
|
|
specifying the same tls-groups option for mbedTLS and OpenSSL.</p>
|
|
<p class="last">Warning: this option not only affects elliptic curve certificates
|
|
but also the key exchange in TLS 1.3 and using this option improperly
|
|
will disable TLS 1.3.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tls-cert-profile <var>profile</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Set the allowed cryptographic algorithms for certificates according to
|
|
<tt class="docutils literal">profile</tt>.</p>
|
|
<p>The following profiles are supported:</p>
|
|
<dl class="docutils">
|
|
<dt><code>legacy</code> (default)</dt>
|
|
<dd>SHA1 and newer, RSA 2048-bit+, any elliptic curve.</dd>
|
|
<dt><code>preferred</code></dt>
|
|
<dd>SHA2 and newer, RSA 2048-bit+, any elliptic curve.</dd>
|
|
<dt><code>suiteb</code></dt>
|
|
<dd>SHA256/SHA384, ECDSA with P-256 or P-384.</dd>
|
|
</dl>
|
|
<p>This option is only fully supported for mbed TLS builds. OpenSSL builds
|
|
use the following approximation:</p>
|
|
<dl class="docutils">
|
|
<dt><code>legacy</code> (default)</dt>
|
|
<dd>sets "security level 1"</dd>
|
|
<dt><code>preferred</code></dt>
|
|
<dd>sets "security level 2"</dd>
|
|
<dt><code>suiteb</code></dt>
|
|
<dd>sets "security level 3" and <tt class="docutils literal"><span class="pre">--tls-cipher</span> "SUITEB128"</tt>.</dd>
|
|
</dl>
|
|
<p class="last">OpenVPN will migrate to 'preferred' as default in the future. Please
|
|
ensure that your keys already comply.</p>
|
|
</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<dl class="docutils">
|
|
<dt><em>WARNING:</em> <tt class="docutils literal"><span class="pre">--tls-ciphers</span></tt>, <tt class="docutils literal"><span class="pre">--tls-ciphersuites</span></tt> and <tt class="docutils literal"><span class="pre">tls-groups</span></tt></dt>
|
|
<dd>These options are expert features, which - if used correctly - can
|
|
improve the security of your VPN connection. But it is also easy to
|
|
unwittingly use them to carefully align a gun with your foot, or just
|
|
break your connection. Use with care!</dd>
|
|
</dl>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--tls-cipher <var>l</var></span></kbd></td>
|
|
<td><p class="first">A list <tt class="docutils literal">l</tt> of allowable TLS ciphers delimited by a colon ("<code>:</code>").</p>
|
|
<p>These setting can be used to ensure that certain cipher suites are used
|
|
(or not used) for the TLS connection. OpenVPN uses TLS to secure the
|
|
control channel, over which the keys that are used to protect the actual
|
|
VPN traffic are exchanged.</p>
|
|
<p>The supplied list of ciphers is (after potential OpenSSL/IANA name
|
|
translation) simply supplied to the crypto library. Please see the
|
|
OpenSSL and/or mbed TLS documentation for details on the cipher list
|
|
interpretation.</p>
|
|
<p>For OpenSSL, the <tt class="docutils literal"><span class="pre">--tls-cipher</span></tt> is used for TLS 1.2 and below.</p>
|
|
<p>Use <tt class="docutils literal"><span class="pre">--show-tls</span></tt> to see a list of TLS ciphers supported by your crypto
|
|
library.</p>
|
|
<p class="last">The default for <tt class="docutils literal"><span class="pre">--tls-cipher</span></tt> is to use mbed TLS's default cipher list
|
|
when using mbed TLS or
|
|
<code>DEFAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA</code> when
|
|
using OpenSSL.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tls-ciphersuites <var>l</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Same as <tt class="docutils literal"><span class="pre">--tls-cipher</span></tt> but for TLS 1.3 and up. mbed TLS has no
|
|
TLS 1.3 support yet and only the <tt class="docutils literal"><span class="pre">--tls-cipher</span></tt> setting is used.</p>
|
|
<p class="last">The default for <cite>--tls-ciphersuites</cite> is to use the crypto library's
|
|
default.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--tls-client</span></kbd></td>
|
|
<td>Enable TLS and assume client role during TLS handshake.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tls-crypt <var>keyfile</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Encrypt and authenticate all control channel packets with the key from
|
|
<tt class="docutils literal">keyfile</tt>. (See <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> for more background.)</p>
|
|
<p>Encrypting (and authenticating) control channel packets:</p>
|
|
<ul class="simple">
|
|
<li>provides more privacy by hiding the certificate used for the TLS
|
|
connection,</li>
|
|
<li>makes it harder to identify OpenVPN traffic as such,</li>
|
|
<li>provides "poor-man's" post-quantum security, against attackers who will
|
|
never know the pre-shared key (i.e. no forward secrecy).</li>
|
|
</ul>
|
|
<p>In contrast to <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>, <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> does <em>not</em> require the
|
|
user to set <tt class="docutils literal"><span class="pre">--key-direction</span></tt>.</p>
|
|
<p><strong>Security Considerations</strong></p>
|
|
<p>All peers use the same <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> pre-shared group key to
|
|
authenticate and encrypt control channel messages. To ensure that IV
|
|
collisions remain unlikely, this key should not be used to encrypt more
|
|
than 2^48 client-to-server or 2^48 server-to-client control channel
|
|
messages. A typical initial negotiation is about 10 packets in each
|
|
direction. Assuming both initial negotiation and renegotiations are at
|
|
most 2^16 (65536) packets (to be conservative), and (re)negotiations
|
|
happen each minute for each user (24/7), this limits the tls-crypt key
|
|
lifetime to 8171 years divided by the number of users. So a setup with
|
|
1000 users should rotate the key at least once each eight years. (And a
|
|
setup with 8000 users each year.)</p>
|
|
<p>If IV collisions were to occur, this could result in the security of
|
|
<tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> degrading to the same security as using <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>.
|
|
That is, the control channel still benefits from the extra protection
|
|
against active man-in-the-middle-attacks and DoS attacks, but may no
|
|
longer offer extra privacy and post-quantum security on top of what TLS
|
|
itself offers.</p>
|
|
<p class="last">For large setups or setups where clients are not trusted, consider using
|
|
<tt class="docutils literal"><span class="pre">--tls-crypt-v2</span></tt> instead. That uses per-client unique keys, and
|
|
thereby improves the bounds to 'rotate a client key at least once per
|
|
8000 years'.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tls-crypt-v2 <var>keyfile</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Use client-specific tls-crypt keys.</p>
|
|
<p>For clients, <tt class="docutils literal">keyfile</tt> is a client-specific tls-crypt key. Such a key
|
|
can be generated using the <code>--genkey tls-crypt-v2-client</code> option.</p>
|
|
<p>For servers, <tt class="docutils literal">keyfile</tt> is used to unwrap client-specific keys supplied
|
|
by the client during connection setup. This key must be the same as the
|
|
key used to generate the client-specific key (see <code>--genkey
|
|
tls-crypt-v2-client</code>).</p>
|
|
<p class="last">On servers, this option can be used together with the <tt class="docutils literal"><span class="pre">--tls-auth</span></tt> or
|
|
<tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> option. In that case, the server will detect whether the
|
|
client is using client-specific keys, and automatically select the right
|
|
mode.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tls-crypt-v2-verify <var>cmd</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> to verify the metadata of the client-specific
|
|
tls-crypt-v2 key of a connecting client. This allows server
|
|
administrators to reject client connections, before exposing the TLS
|
|
stack (including the notoriously dangerous X.509 and ASN.1 stacks) to
|
|
the connecting client.</p>
|
|
<p>OpenVPN supplies the following environment variables to the command:</p>
|
|
<ul class="simple">
|
|
<li><code>script_type</code> is set to <code>tls-crypt-v2-verify</code></li>
|
|
<li><code>metadata_type</code> is set to <code>0</code> if the metadata was user
|
|
supplied, or <code>1</code> if it's a 64-bit unix timestamp representing
|
|
the key creation time.</li>
|
|
<li><code>metadata_file</code> contains the filename of a temporary file that
|
|
contains the client metadata.</li>
|
|
</ul>
|
|
<p class="last">The command can reject the connection by exiting with a non-zero exit
|
|
code.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--tls-exit</span></kbd></td>
|
|
<td>Exit on TLS negotiation failure.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tls-export-cert <var>directory</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Store the certificates the clients use upon connection to this
|
|
directory. This will be done before <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> is called. The
|
|
certificates will use a temporary name and will be deleted when the
|
|
tls-verify script returns. The file name used for the certificate is
|
|
available via the <tt class="docutils literal">peer_cert</tt> environment variable.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--tls-server</span></kbd></td>
|
|
<td>Enable TLS and assume server role during TLS handshake. Note that
|
|
OpenVPN is designed as a peer-to-peer application. The designation of
|
|
client or server is only for the purpose of negotiating the TLS control
|
|
channel.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tls-timeout <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Packet retransmit timeout on TLS control channel if no acknowledgment
|
|
from remote within <tt class="docutils literal">n</tt> seconds (default <code>2</code>). When OpenVPN sends
|
|
a control packet to its peer, it will expect to receive an
|
|
acknowledgement within <tt class="docutils literal">n</tt> seconds or it will retransmit the packet,
|
|
subject to a TCP-like exponential backoff algorithm. This parameter only
|
|
applies to control channel packets. Data channel packets (which carry
|
|
encrypted tunnel data) are never acknowledged, sequenced, or
|
|
retransmitted by OpenVPN because the higher level network protocols
|
|
running on top of the tunnel such as TCP expect this role to be left to
|
|
them.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tls-version-min <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Sets the minimum TLS version we will accept from the peer (default is
|
|
"1.0").</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
tls-version-min version ['or-highest']
|
|
</pre>
|
|
<p class="last">Examples for version include <code>1.0</code>, <code>1.1</code>, or <code>1.2</code>. If
|
|
<code>or-highest</code> is specified and version is not recognized, we will
|
|
only accept the highest TLS version supported by the local SSL
|
|
implementation.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tls-version-max <var>version</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Set the maximum TLS version we will use (default is the highest version
|
|
supported). Examples for version include <code>1.0</code>, <code>1.1</code>, or
|
|
<code>1.2</code>.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--verify-hash <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Specify SHA1 or SHA256 fingerprint for level-1 cert.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
verify-hash hash [algo]
|
|
</pre>
|
|
<p>The level-1 cert is the CA (or intermediate cert) that signs the leaf
|
|
certificate, and is one removed from the leaf certificate in the
|
|
direction of the root. When accepting a connection from a peer, the
|
|
level-1 cert fingerprint must match <tt class="docutils literal">hash</tt> or certificate verification
|
|
will fail. Hash is specified as XX:XX:... For example:</p>
|
|
<pre class="literal-block">
|
|
AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16
|
|
</pre>
|
|
<p class="last">The <tt class="docutils literal">algo</tt> flag can be either <code>SHA1</code> or <code>SHA256</code>. If not
|
|
provided, it defaults to <code>SHA1</code>.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--verify-x509-name <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Accept connections only if a host's X.509 name is equal to <strong>name.</strong> The
|
|
remote host must also pass all other tests of verification.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
verify-x509 name type
|
|
</pre>
|
|
<p>Which X.509 name is compared to <tt class="docutils literal">name</tt> depends on the setting of type.
|
|
<tt class="docutils literal">type</tt> can be <code>subject</code> to match the complete subject DN
|
|
(default), <code>name</code> to match a subject RDN or <code>name-prefix</code> to
|
|
match a subject RDN prefix. Which RDN is verified as name depends on the
|
|
<tt class="docutils literal"><span class="pre">--x509-username-field</span></tt> option. But it defaults to the common name
|
|
(CN), e.g. a certificate with a subject DN</p>
|
|
<pre class="literal-block">
|
|
C=KG, ST=NA, L=Bishkek, CN=Server-1
|
|
</pre>
|
|
<p>would be matched by:</p>
|
|
<pre class="literal-block">
|
|
verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1'
|
|
verify-x509-name Server-1 name
|
|
verify-x509-name Server- name-prefix
|
|
</pre>
|
|
<p>The last example is useful if you want a client to only accept
|
|
connections to <code>Server-1</code>, <code>Server-2</code>, etc.</p>
|
|
<p><tt class="docutils literal"><span class="pre">--verify-x509-name</span></tt> is a useful replacement for the <tt class="docutils literal"><span class="pre">--tls-verify</span></tt>
|
|
option to verify the remote host, because <tt class="docutils literal"><span class="pre">--verify-x509-name</span></tt> works
|
|
in a <tt class="docutils literal"><span class="pre">--chroot</span></tt> environment without any dependencies.</p>
|
|
<p>Using a name prefix is a useful alternative to managing a CRL
|
|
(Certificate Revocation List) on the client, since it allows the client
|
|
to refuse all certificates except for those associated with designated
|
|
servers.</p>
|
|
<dl class="last docutils">
|
|
<dt><em>NOTE:</em></dt>
|
|
<dd>Test against a name prefix only when you are using OpenVPN
|
|
with a custom CA certificate that is under your control. Never use
|
|
this option with type <code>name-prefix</code> when your client
|
|
certificates are signed by a third party, such as a commercial
|
|
web CA.</dd>
|
|
</dl>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--x509-track <var>attribute</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Save peer X509 <strong>attribute</strong> value in environment for use by plugins and
|
|
management interface. Prepend a <code>+</code> to <tt class="docutils literal">attribute</tt> to save values
|
|
from full cert chain. Values will be encoded as
|
|
<code>X509_<depth>_<attribute>=<value></code>. Multiple <tt class="docutils literal"><span class="pre">--x509-track</span></tt>
|
|
options can be defined to track multiple attributes.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--x509-username-field <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Field in the X.509 certificate subject to be used as the username
|
|
(default <code>CN</code>).</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
x509-username-field [ext:]fieldname
|
|
</pre>
|
|
<p>Typically, this option is specified with <strong>fieldname</strong> as
|
|
either of the following:</p>
|
|
<pre class="literal-block">
|
|
x509-username-field emailAddress
|
|
x509-username-field ext:subjectAltName
|
|
</pre>
|
|
<p>The first example uses the value of the <code>emailAddress</code> attribute
|
|
in the certificate's Subject field as the username. The second example
|
|
uses the <code>ext:</code> prefix to signify that the X.509 extension
|
|
<tt class="docutils literal">fieldname</tt> <code>subjectAltName</code> be searched for an rfc822Name
|
|
(email) field to be used as the username. In cases where there are
|
|
multiple email addresses in <code>ext:fieldname</code>, the last occurrence
|
|
is chosen.</p>
|
|
<p>When this option is used, the <tt class="docutils literal"><span class="pre">--verify-x509-name</span></tt> option will match
|
|
against the chosen <tt class="docutils literal">fieldname</tt> instead of the Common Name.</p>
|
|
<p>Only the <code>subjectAltName</code> and <code>issuerAltName</code> X.509
|
|
extensions are supported.</p>
|
|
<p class="last"><strong>Please note:</strong> This option has a feature which will convert an
|
|
all-lowercase <tt class="docutils literal">fieldname</tt> to uppercase characters, e.g.,
|
|
<code>ou</code> -> <code>OU</code>. A mixed-case <tt class="docutils literal">fieldname</tt> or one having the
|
|
<code>ext:</code> prefix will be left as-is. This automatic upcasing feature is
|
|
deprecated and will be removed in a future release.</p>
|
|
</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="pkcs-11-smartcard-options">
|
|
<h2>PKCS#11 / SmartCard options</h2>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--pkcs11-cert-private <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Set if access to certificate object should be performed after login.
|
|
Every provider has its own setting.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="last literal-block">
|
|
pkcs11-cert-private 0
|
|
pkcs11-cert-private 1
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--pkcs11-id <var>name</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Specify the serialized certificate id to be used. The id can be gotten
|
|
by the standalone <tt class="docutils literal"><span class="pre">--show-pkcs11-ids</span></tt> option.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--pkcs11-id-management</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Acquire PKCS#11 id from management interface. In this case a
|
|
<code>NEED-STR 'pkcs11-id-request'</code> real-time message will be triggered,
|
|
application may use pkcs11-id-count command to retrieve available number of
|
|
certificates, and pkcs11-id-get command to retrieve certificate id and
|
|
certificate body.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--pkcs11-pin-cache <var>seconds</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Specify how many seconds the PIN can be cached, the default is until the
|
|
token is removed.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--pkcs11-private-mode <var>mode</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Specify which method to use in order to perform private key operations.
|
|
A different mode can be specified for each provider. Mode is encoded as
|
|
hex number, and can be a mask one of the following:</p>
|
|
<p><code>0</code> (default) Try to determine automatically.</p>
|
|
<p><code>1</code> Use sign.</p>
|
|
<p><code>2</code> Use sign recover.</p>
|
|
<p><code>4</code> Use decrypt.</p>
|
|
<p class="last"><code>8</code> Use unwrap.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--pkcs11-protected-authentication <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Use PKCS#11 protected authentication path, useful for biometric and
|
|
external keypad devices. Every provider has its own setting.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="last literal-block">
|
|
pkcs11-protected-authentication 0
|
|
pkcs11-protected-authentication 1
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--pkcs11-providers <var>provider</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Specify an RSA Security Inc. PKCS #11 Cryptographic Token Interface
|
|
(Cryptoki) providers to load. This option can be used instead of
|
|
<tt class="docutils literal"><span class="pre">--cert</span></tt>, <tt class="docutils literal"><span class="pre">--key</span></tt> and <tt class="docutils literal"><span class="pre">--pkcs12</span></tt>.</p>
|
|
<p class="last">If p11-kit is present on the system, its <code>p11-kit-proxy.so</code> module
|
|
will be loaded by default if either the <tt class="docutils literal"><span class="pre">--pkcs11-id</span></tt> or
|
|
<tt class="docutils literal"><span class="pre">--pkcs11-id-management</span></tt> options are specified without
|
|
<tt class="docutils literal"><span class="pre">--pkcs11-provider</span></tt> being given.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--show-pkcs11-ids <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">(Standalone) Show PKCS#11 token object list.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
show-pkcs11 [provider] [cert_private]
|
|
</pre>
|
|
<p>Specify <tt class="docutils literal">cert_private</tt> as <code>1</code> if certificates are stored as
|
|
private objects.</p>
|
|
<p>If <em>p11-kit</em> is present on the system, the <tt class="docutils literal">provider</tt> argument is
|
|
optional; if omitted the default <code>p11-kit-proxy.so</code> module will be
|
|
queried.</p>
|
|
<p class="last"><tt class="docutils literal"><span class="pre">--verb</span></tt> option can be used BEFORE this option to produce debugging
|
|
information.</p>
|
|
</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="data-channel-cipher-negotiation">
|
|
<h1>Data channel cipher negotiation</h1>
|
|
<p>OpenVPN 2.4 and higher have the capability to negotiate the data cipher that
|
|
is used to encrypt data packets. This section describes the mechanism in more detail and the
|
|
different backwards compatibility mechanism with older server and clients.</p>
|
|
<div class="section" id="openvpn-2-5-and-higher-behaviour">
|
|
<h2>OpenVPN 2.5 and higher behaviour</h2>
|
|
<p>When both client and server are at least running OpenVPN 2.5, that the order of
|
|
the ciphers of the server's <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> is used to pick the the data cipher.
|
|
That means that the first cipher in that list that is also in the client's
|
|
<tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> list is chosen. If no common cipher is found the client is rejected
|
|
with a AUTH_FAILED message (as seen in client log):</p>
|
|
<blockquote>
|
|
AUTH: Received control message: AUTH_FAILED,Data channel cipher negotiation failed (no shared cipher)</blockquote>
|
|
<p>OpenVPN 2.5 will only allow the ciphers specified in <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt>. To ensure
|
|
backwards compatibility also if a cipher is specified using the <tt class="docutils literal"><span class="pre">--cipher</span></tt> option
|
|
it is automatically added to this list. If both options are unset the default is
|
|
<code>AES-256-GCM:AES-128-GCM</code>.</p>
|
|
</div>
|
|
<div class="section" id="openvpn-2-4-clients">
|
|
<h2>OpenVPN 2.4 clients</h2>
|
|
<p>The negotiation support in OpenVPN 2.4 was the first iteration of the implementation
|
|
and still had some quirks. Its main goal was "upgrade to AES-256-GCM when possible".
|
|
An OpenVPN 2.4 client that is built against a crypto library that supports AES in GCM
|
|
mode and does not have <tt class="docutils literal"><span class="pre">--ncp-disable</span></tt> will always announce support for
|
|
<cite>AES-256-GCM</cite> and <cite>AES-128-GCM</cite> to a server by sending <code>IV_NCP=2</code>.</p>
|
|
<p>This only causes a problem if <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt> option has been changed from the
|
|
default of <code>AES-256-GCM:AES-128-GCM</code> to a value that does not include
|
|
these two ciphers. When a OpenVPN servers try to use <cite>AES-256-GCM</cite> or
|
|
<cite>AES-128-GCM</cite> the connection will then fail. It is therefore recommended to
|
|
always have the <cite>AES-256-GCM</cite> and <cite>AES-128-GCM</cite> ciphers to the <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt>
|
|
options to avoid this behaviour.</p>
|
|
</div>
|
|
<div class="section" id="openvpn-3-clients">
|
|
<h2>OpenVPN 3 clients</h2>
|
|
<p>Clients based on the OpenVPN 3.x library (<a class="reference external" href="https://github.com/openvpn/openvpn3/">https://github.com/openvpn/openvpn3/</a>)
|
|
do not have a configurable <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt> or <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> option. Instead
|
|
these clients will announce support for all their supported AEAD ciphers
|
|
(<cite>AES-256-GCM</cite>, <cite>AES-128-GCM</cite> and in newer versions also <cite>Chacha20-Poly1305</cite>).</p>
|
|
<p>To support OpenVPN 3.x based clients at least one of these ciphers needs to be
|
|
included in the server's <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> option.</p>
|
|
</div>
|
|
<div class="section" id="openvpn-2-3-and-older-clients-and-clients-with-ncp-disable">
|
|
<h2>OpenVPN 2.3 and older clients (and clients with <tt class="docutils literal"><span class="pre">--ncp-disable</span></tt>)</h2>
|
|
<p>When a client without cipher negotiation support connects to a server the
|
|
cipher specified with the <tt class="docutils literal"><span class="pre">--cipher</span></tt> option in the client configuration
|
|
must be included in the <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> option of the server to allow
|
|
the client to connect. Otherwise the client will be sent the <tt class="docutils literal">AUTH_FAILED</tt>
|
|
message that indicates no shared cipher.</p>
|
|
<p>If the client is 2.3 or older and has been configured with the
|
|
<tt class="docutils literal"><span class="pre">--enable-small</span></tt> <code>./configure</code> argument, using
|
|
<tt class="docutils literal"><span class="pre">data-ciphers-fallback</span> cipher</tt> in the server config file with the explicit
|
|
cipher used by the client is necessary.</p>
|
|
</div>
|
|
<div class="section" id="openvpn-2-4-server">
|
|
<h2>OpenVPN 2.4 server</h2>
|
|
<p>When a client indicates support for <cite>AES-128-GCM</cite> and <cite>AES-256-GCM</cite>
|
|
(with <tt class="docutils literal">IV_NCP=2</tt>) an OpenVPN 2.4 server will send the first
|
|
cipher of the <tt class="docutils literal"><span class="pre">--ncp-ciphers</span></tt> to the OpenVPN client regardless of what
|
|
the cipher is. To emulate the behaviour of an OpenVPN 2.4 client as close
|
|
as possible and have compatibility to a setup that depends on this quirk,
|
|
adding <cite>AES-128-GCM</cite> and <cite>AES-256-GCM</cite> to the client's <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt>
|
|
option is required. OpenVPN 2.5+ will only announce the <tt class="docutils literal">IV_NCP=2</tt> flag if
|
|
those ciphers are present.</p>
|
|
</div>
|
|
<div class="section" id="openvpn-2-3-and-older-servers-and-servers-with-ncp-disable">
|
|
<h2>OpenVPN 2.3 and older servers (and servers with <tt class="docutils literal"><span class="pre">--ncp-disable</span></tt>)</h2>
|
|
<p>The cipher used by the server must be included in <tt class="docutils literal"><span class="pre">--data-ciphers</span></tt> to
|
|
allow the client connecting to a server without cipher negotiation
|
|
support.
|
|
(For compatibility OpenVPN 2.5 will also accept the cipher set with
|
|
<tt class="docutils literal"><span class="pre">--cipher</span></tt>)</p>
|
|
<p>If the server is 2.3 or older and has been configured with the
|
|
<tt class="docutils literal"><span class="pre">--enable-small</span></tt> <code>./configure</code> argument, adding
|
|
<tt class="docutils literal"><span class="pre">data-ciphers-fallback</span> cipher</tt> to the client config with the explicit
|
|
cipher used by the server is necessary.</p>
|
|
</div>
|
|
<div class="section" id="blowfish-in-cbc-mode-bf-cbc-deprecation">
|
|
<h2>Blowfish in CBC mode (BF-CBC) deprecation</h2>
|
|
<p>The <tt class="docutils literal"><span class="pre">--cipher</span></tt> option defaulted to <tt class="docutils literal"><span class="pre">BF-CBC</span></tt> in OpenVPN 2.4 and older
|
|
version. The default was never changed to ensure backwards compatibility.
|
|
In OpenVPN 2.5 this behaviour has now been changed so that if the <tt class="docutils literal"><span class="pre">--cipher</span></tt>
|
|
is not explicitly set it does not allow the weak <tt class="docutils literal"><span class="pre">BF-CBC</span></tt> cipher any more
|
|
and needs to explicitly added as <tt class="docutils literal"><span class="pre">--cipher</span> <span class="pre">BFC-CBC</span></tt> or added to
|
|
<tt class="docutils literal"><span class="pre">--data-ciphers</span></tt>.</p>
|
|
<p>We strongly recommend to switching away from BF-CBC to a
|
|
more secure cipher as soon as possible instead.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="network-configuration">
|
|
<h1>NETWORK CONFIGURATION</h1>
|
|
<p>OpenVPN consists of two sides of network configuration. One side is the
|
|
<em>link</em> between the local and remote side, the other side is the <em>virtual
|
|
network adapter</em> (tun/tap device).</p>
|
|
<div class="section" id="link-options">
|
|
<h2>Link Options</h2>
|
|
<p>This link options section covers options related to the connection between
|
|
the local and the remote host.</p>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--bind <var>keywords</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Bind to local address and port. This is the default unless any of
|
|
<tt class="docutils literal"><span class="pre">--proto</span> <span class="pre">tcp-client</span></tt> , <tt class="docutils literal"><span class="pre">--http-proxy</span></tt> or <tt class="docutils literal"><span class="pre">--socks-proxy</span></tt> are used.</p>
|
|
<p class="last">If the optional <code>ipv6only</code> keyword is present OpenVPN will bind only
|
|
to IPv6 (as opposed to IPv6 and IPv4) when a IPv6 socket is opened.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--float</span></kbd></td>
|
|
<td><p class="first">Allow remote peer to change its IP address and/or port number, such as
|
|
due to DHCP (this is the default if <tt class="docutils literal"><span class="pre">--remote</span></tt> is not used).
|
|
<tt class="docutils literal"><span class="pre">--float</span></tt> when specified with <tt class="docutils literal"><span class="pre">--remote</span></tt> allows an OpenVPN session
|
|
to initially connect to a peer at a known address, however if packets
|
|
arrive from a new address and pass all authentication tests, the new
|
|
address will take control of the session. This is useful when you are
|
|
connecting to a peer which holds a dynamic address such as a dial-in
|
|
user or DHCP client.</p>
|
|
<p class="last">Essentially, <tt class="docutils literal"><span class="pre">--float</span></tt> tells OpenVPN to accept authenticated packets
|
|
from any address, not only the address which was specified in the
|
|
<tt class="docutils literal"><span class="pre">--remote</span></tt> option.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--fragment <var>max</var></span></kbd></td>
|
|
<td><p class="first">Enable internal datagram fragmentation so that no UDP datagrams are sent
|
|
which are larger than <tt class="docutils literal">max</tt> bytes.</p>
|
|
<p>The <tt class="docutils literal">max</tt> parameter is interpreted in the same way as the
|
|
<tt class="docutils literal"><span class="pre">--link-mtu</span></tt> parameter, i.e. the UDP packet size after encapsulation
|
|
overhead has been added in, but not including the UDP header itself.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">--fragment</span></tt> option only makes sense when you are using the UDP
|
|
protocol (<tt class="docutils literal"><span class="pre">--proto</span> udp</tt>).</p>
|
|
<p><tt class="docutils literal"><span class="pre">--fragment</span></tt> adds 4 bytes of overhead per datagram.</p>
|
|
<p>See the <tt class="docutils literal"><span class="pre">--mssfix</span></tt> option below for an important related option to
|
|
<tt class="docutils literal"><span class="pre">--fragment</span></tt>.</p>
|
|
<p>It should also be noted that this option is not meant to replace UDP
|
|
fragmentation at the IP stack level. It is only meant as a last resort
|
|
when path MTU discovery is broken. Using this option is less efficient
|
|
than fixing path MTU discovery for your IP link and using native IP
|
|
fragmentation instead.</p>
|
|
<p class="last">Having said that, there are circumstances where using OpenVPN's internal
|
|
fragmentation capability may be your only option, such as tunneling a
|
|
UDP multicast stream which requires fragmentation.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--keepalive <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">A helper directive designed to simplify the expression of <tt class="docutils literal"><span class="pre">--ping</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">--ping-restart</span></tt>.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
keepalive interval timeout
|
|
</pre>
|
|
<p>This option can be used on both client and server side, but it is enough
|
|
to add this on the server side as it will push appropriate <tt class="docutils literal"><span class="pre">--ping</span></tt>
|
|
and <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> options to the client. If used on both server and
|
|
client, the values pushed from server will override the client local
|
|
values.</p>
|
|
<p>The <tt class="docutils literal">timeout</tt> argument will be twice as long on the server side. This
|
|
ensures that a timeout is detected on client side before the server side
|
|
drops the connection.</p>
|
|
<p>For example, <tt class="docutils literal"><span class="pre">--keepalive</span> 10 60</tt> expands as follows:</p>
|
|
<pre class="last literal-block">
|
|
if mode server:
|
|
ping 10 # Argument: interval
|
|
ping-restart 120 # Argument: timeout*2
|
|
push "ping 10" # Argument: interval
|
|
push "ping-restart 60" # Argument: timeout
|
|
else
|
|
ping 10 # Argument: interval
|
|
ping-restart 60 # Argument: timeout
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--link-mtu <var>n</var></span></kbd></td>
|
|
<td>Sets an upper bound on the size of UDP packets which are sent between
|
|
OpenVPN peers. <em>It's best not to set this parameter unless you know what
|
|
you're doing.</em></td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--local <var>host</var></span></kbd></td>
|
|
<td>Local host name or IP address for bind. If specified, OpenVPN will bind
|
|
to this address only. If unspecified, OpenVPN will bind to all
|
|
interfaces.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--lport <var>port</var></span></kbd></td>
|
|
<td>Set local TCP/UDP port number or name. Cannot be used together with
|
|
<tt class="docutils literal"><span class="pre">--nobind</span></tt> option.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--mark <var>value</var></span></kbd></td>
|
|
<td>Mark encrypted packets being sent with value. The mark value can be
|
|
matched in policy routing and packetfilter rules. This option is only
|
|
supported in Linux and does nothing on other operating systems.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--mode <var>m</var></span></kbd></td>
|
|
<td>Set OpenVPN major mode. By default, OpenVPN runs in point-to-point mode
|
|
(<code>p2p</code>). OpenVPN 2.0 introduces a new mode (<code>server</code>) which
|
|
implements a multi-client server capability.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--mssfix <var>max</var></span></kbd></td>
|
|
<td><p class="first">Announce to TCP sessions running over the tunnel that they should limit
|
|
their send packet sizes such that after OpenVPN has encapsulated them,
|
|
the resulting UDP packet size that OpenVPN sends to its peer will not
|
|
exceed <tt class="docutils literal">max</tt> bytes. The default value is <code>1450</code>.</p>
|
|
<p>The <tt class="docutils literal">max</tt> parameter is interpreted in the same way as the
|
|
<tt class="docutils literal"><span class="pre">--link-mtu</span></tt> parameter, i.e. the UDP packet size after encapsulation
|
|
overhead has been added in, but not including the UDP header itself.
|
|
Resulting packet would be at most 28 bytes larger for IPv4 and 48 bytes
|
|
for IPv6 (20/40 bytes for IP header and 8 bytes for UDP header). Default
|
|
value of 1450 allows IPv4 packets to be transmitted over a link with MTU
|
|
1473 or higher without IP level fragmentation.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">--mssfix</span></tt> option only makes sense when you are using the UDP
|
|
protocol for OpenVPN peer-to-peer communication, i.e. <tt class="docutils literal"><span class="pre">--proto</span> udp</tt>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">--mssfix</span></tt> and <tt class="docutils literal"><span class="pre">--fragment</span></tt> can be ideally used together, where
|
|
<tt class="docutils literal"><span class="pre">--mssfix</span></tt> will try to keep TCP from needing packet fragmentation in
|
|
the first place, and if big packets come through anyhow (from protocols
|
|
other than TCP), <tt class="docutils literal"><span class="pre">--fragment</span></tt> will internally fragment them.</p>
|
|
<p>Both <tt class="docutils literal"><span class="pre">--fragment</span></tt> and <tt class="docutils literal"><span class="pre">--mssfix</span></tt> are designed to work around cases
|
|
where Path MTU discovery is broken on the network path between OpenVPN
|
|
peers.</p>
|
|
<p>The usual symptom of such a breakdown is an OpenVPN connection which
|
|
successfully starts, but then stalls during active usage.</p>
|
|
<p>If <tt class="docutils literal"><span class="pre">--fragment</span></tt> and <tt class="docutils literal"><span class="pre">--mssfix</span></tt> are used together, <tt class="docutils literal"><span class="pre">--mssfix</span></tt> will
|
|
take its default <tt class="docutils literal">max</tt> parameter from the <tt class="docutils literal"><span class="pre">--fragment</span> max</tt> option.</p>
|
|
<p>Therefore, one could lower the maximum UDP packet size to 1300 (a good
|
|
first try for solving MTU-related connection problems) with the
|
|
following options:</p>
|
|
<pre class="last literal-block">
|
|
--tun-mtu 1500 --fragment 1300 --mssfix
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--mtu-disc <var>type</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Should we do Path MTU discovery on TCP/UDP channel? Only supported on
|
|
OSes such as Linux that supports the necessary system call to set.</p>
|
|
<p>Valid types:</p>
|
|
<p><code>no</code> Never send DF (Don't Fragment) frames</p>
|
|
<p><code>maybe</code> Use per-route hints</p>
|
|
<p class="last"><code>yes</code> Always DF (Don't Fragment)</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--mtu-test</span></kbd></td>
|
|
<td>To empirically measure MTU on connection startup, add the <tt class="docutils literal"><span class="pre">--mtu-test</span></tt>
|
|
option to your configuration. OpenVPN will send ping packets of various
|
|
sizes to the remote peer and measure the largest packets which were
|
|
successfully received. The <tt class="docutils literal"><span class="pre">--mtu-test</span></tt> process normally takes about 3
|
|
minutes to complete.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--nobind</span></kbd></td>
|
|
<td>Do not bind to local address and port. The IP stack will allocate a
|
|
dynamic port for returning packets. Since the value of the dynamic port
|
|
could not be known in advance by a peer, this option is only suitable
|
|
for peers which will be initiating connections by using the --remote
|
|
option.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--passtos</span></kbd></td>
|
|
<td>Set the TOS field of the tunnel packet to what the payload's TOS is.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--ping <var>n</var></span></kbd></td>
|
|
<td><p class="first">Ping remote over the TCP/UDP control channel if no packets have been
|
|
sent for at least <tt class="docutils literal">n</tt> seconds (specify <tt class="docutils literal"><span class="pre">--ping</span></tt> on both peers to
|
|
cause ping packets to be sent in both directions since OpenVPN ping
|
|
packets are not echoed like IP ping packets). When used in one of
|
|
OpenVPN's secure modes (where <tt class="docutils literal"><span class="pre">--secret</span></tt>, <tt class="docutils literal"><span class="pre">--tls-server</span></tt> or
|
|
<tt class="docutils literal"><span class="pre">--tls-client</span></tt> is specified), the ping packet will be
|
|
cryptographically secure.</p>
|
|
<p>This option has two intended uses:</p>
|
|
<ol class="last arabic simple">
|
|
<li>Compatibility with stateful firewalls. The periodic ping will ensure
|
|
that a stateful firewall rule which allows OpenVPN UDP packets to
|
|
pass will not time out.</li>
|
|
<li>To provide a basis for the remote to test the existence of its peer
|
|
using the <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> option.</li>
|
|
</ol>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--ping-exit <var>n</var></span></kbd></td>
|
|
<td><p class="first">Causes OpenVPN to exit after <tt class="docutils literal">n</tt> seconds pass without reception of a
|
|
ping or other packet from remote. This option can be combined with
|
|
<tt class="docutils literal"><span class="pre">--inactive</span></tt>, <tt class="docutils literal"><span class="pre">--ping</span></tt> and <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> to create a two-tiered
|
|
inactivity disconnect.</p>
|
|
<p>For example,</p>
|
|
<pre class="literal-block">
|
|
openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60
|
|
</pre>
|
|
<p class="last">when used on both peers will cause OpenVPN to exit within 60 seconds if
|
|
its peer disconnects, but will exit after one hour if no actual tunnel
|
|
data is exchanged.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ping-restart <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Similar to <tt class="docutils literal"><span class="pre">--ping-exit</span></tt>, but trigger a <code>SIGUSR1</code> restart after
|
|
<tt class="docutils literal">n</tt> seconds pass without reception of a ping or other packet from
|
|
remote.</p>
|
|
<p>This option is useful in cases where the remote peer has a dynamic IP
|
|
address and a low-TTL DNS name is used to track the IP address using a
|
|
service such as <a class="reference external" href="https://www.nsupdate.info/">https://www.nsupdate.info/</a> + a dynamic DNS client such as
|
|
<tt class="docutils literal">ddclient</tt>.</p>
|
|
<p>If the peer cannot be reached, a restart will be triggered, causing the
|
|
hostname used with <tt class="docutils literal"><span class="pre">--remote</span></tt> to be re-resolved (if <tt class="docutils literal"><span class="pre">--resolv-retry</span></tt>
|
|
is also specified).</p>
|
|
<p>In server mode, <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>, <tt class="docutils literal"><span class="pre">--inactive</span></tt> or any other type of
|
|
internally generated signal will always be applied to individual client
|
|
instance objects, never to whole server itself. Note also in server mode
|
|
that any internally generated signal which would normally cause a
|
|
restart, will cause the deletion of the client instance object instead.</p>
|
|
<p>In client mode, the <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> parameter is set to 120 seconds
|
|
by default. This default will hold until the client pulls a replacement
|
|
value from the server, based on the <tt class="docutils literal"><span class="pre">--keepalive</span></tt> setting in the
|
|
server configuration. To disable the 120 second default, set
|
|
<tt class="docutils literal"><span class="pre">--ping-restart</span> 0</tt> on the client.</p>
|
|
<p>See the signals section below for more information on <code>SIGUSR1</code>.</p>
|
|
<p>Note that the behavior of <tt class="docutils literal">SIGUSR1</tt> can be modified by the
|
|
<tt class="docutils literal"><span class="pre">--persist-tun</span></tt>, <tt class="docutils literal"><span class="pre">--persist-key</span></tt>, <tt class="docutils literal"><span class="pre">--persist-local-ip</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">--persist-remote-ip</span></tt> options.</p>
|
|
<p class="last">Also note that <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> and <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> are mutually
|
|
exclusive and cannot be used together.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ping-timer-rem</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Run the <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> / <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> timer only if we have a
|
|
remote address. Use this option if you are starting the daemon in listen
|
|
mode (i.e. without an explicit <tt class="docutils literal"><span class="pre">--remote</span></tt> peer), and you don't want to
|
|
start clocking timeouts until a remote peer connects.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--proto <var>p</var></span></kbd></td>
|
|
<td><p class="first">Use protocol <tt class="docutils literal">p</tt> for communicating with remote host. <tt class="docutils literal">p</tt> can be
|
|
<code>udp</code>, <code>tcp-client</code>, or <code>tcp-server</code>.</p>
|
|
<p>The default protocol is <code>udp</code> when <tt class="docutils literal"><span class="pre">--proto</span></tt> is not specified.</p>
|
|
<p>For UDP operation, <tt class="docutils literal"><span class="pre">--proto</span> udp</tt> should be specified on both peers.</p>
|
|
<p>For TCP operation, one peer must use <tt class="docutils literal"><span class="pre">--proto</span> <span class="pre">tcp-server</span></tt> and the
|
|
other must use <tt class="docutils literal"><span class="pre">--proto</span> <span class="pre">tcp-client</span></tt>. A peer started with
|
|
<code>tcp-server</code> will wait indefinitely for an incoming connection. A peer
|
|
started with <code>tcp-client</code> will attempt to connect, and if that fails,
|
|
will sleep for 5 seconds (adjustable via the <tt class="docutils literal"><span class="pre">--connect-retry</span></tt> option)
|
|
and try again infinite or up to N retries (adjustable via the
|
|
<tt class="docutils literal"><span class="pre">--connect-retry-max</span></tt> option). Both TCP client and server will
|
|
simulate a SIGUSR1 restart signal if either side resets the connection.</p>
|
|
<p>OpenVPN is designed to operate optimally over UDP, but TCP capability is
|
|
provided for situations where UDP cannot be used. In comparison with
|
|
UDP, TCP will usually be somewhat less efficient and less robust when
|
|
used over unreliable or congested networks.</p>
|
|
<p>This article outlines some of problems with tunneling IP over TCP:
|
|
<a class="reference external" href="http://sites.inka.de/sites/bigred/devel/tcp-tcp.html">http://sites.inka.de/sites/bigred/devel/tcp-tcp.html</a></p>
|
|
<p class="last">There are certain cases, however, where using TCP may be advantageous
|
|
from a security and robustness perspective, such as tunneling non-IP or
|
|
application-level UDP protocols, or tunneling protocols which don't
|
|
possess a built-in reliability layer.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--port <var>port</var></span></kbd></td>
|
|
<td>TCP/UDP port number or port name for both local and remote (sets both
|
|
<tt class="docutils literal"><span class="pre">--lport</span></tt> and <tt class="docutils literal"><span class="pre">--rport</span></tt> options to given port). The current default
|
|
of 1194 represents the official IANA port number assignment for OpenVPN
|
|
and has been used since version 2.0-beta17. Previous versions used port
|
|
5000 as the default.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--rport <var>port</var></span></kbd></td>
|
|
<td>Set TCP/UDP port number or name used by the <tt class="docutils literal"><span class="pre">--remote</span></tt> option. The
|
|
port can also be set directly using the <tt class="docutils literal"><span class="pre">--remote</span></tt> option.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--replay-window <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Modify the replay protection sliding-window size and time window.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
replay-window n [t]
|
|
</pre>
|
|
<p>Use a replay protection sliding-window of size <strong>n</strong> and a time window
|
|
of <strong>t</strong> seconds.</p>
|
|
<p>By default <strong>n</strong> is 64 (the IPSec default) and <strong>t</strong> is 15 seconds.</p>
|
|
<p>This option is only relevant in UDP mode, i.e. when either <strong>--proto
|
|
udp</strong> is specified, or no <strong>--proto</strong> option is specified.</p>
|
|
<p>When OpenVPN tunnels IP packets over UDP, there is the possibility that
|
|
packets might be dropped or delivered out of order. Because OpenVPN,
|
|
like IPSec, is emulating the physical network layer, it will accept an
|
|
out-of-order packet sequence, and will deliver such packets in the same
|
|
order they were received to the TCP/IP protocol stack, provided they
|
|
satisfy several constraints.</p>
|
|
<ol class="loweralpha simple">
|
|
<li>The packet cannot be a replay (unless <tt class="docutils literal"><span class="pre">--no-replay</span></tt> is
|
|
specified, which disables replay protection altogether).</li>
|
|
<li>If a packet arrives out of order, it will only be accepted if
|
|
the difference between its sequence number and the highest sequence
|
|
number received so far is less than <tt class="docutils literal">n</tt>.</li>
|
|
<li>If a packet arrives out of order, it will only be accepted if it
|
|
arrives no later than <tt class="docutils literal">t</tt> seconds after any packet containing a higher
|
|
sequence number.</li>
|
|
</ol>
|
|
<p>If you are using a network link with a large pipeline (meaning that the
|
|
product of bandwidth and latency is high), you may want to use a larger
|
|
value for <tt class="docutils literal">n</tt>. Satellite links in particular often require this.</p>
|
|
<p>If you run OpenVPN at <tt class="docutils literal"><span class="pre">--verb</span> 4</tt>, you will see the message
|
|
"Replay-window backtrack occurred [x]" every time the maximum sequence
|
|
number backtrack seen thus far increases. This can be used to calibrate
|
|
<tt class="docutils literal">n</tt>.</p>
|
|
<p>There is some controversy on the appropriate method of handling packet
|
|
reordering at the security layer.</p>
|
|
<p>Namely, to what extent should the security layer protect the
|
|
encapsulated protocol from attacks which masquerade as the kinds of
|
|
normal packet loss and reordering that occur over IP networks?</p>
|
|
<p>The IPSec and OpenVPN approach is to allow packet reordering within a
|
|
certain fixed sequence number window.</p>
|
|
<p>OpenVPN adds to the IPSec model by limiting the window size in time as
|
|
well as sequence space.</p>
|
|
<p>OpenVPN also adds TCP transport as an option (not offered by IPSec) in
|
|
which case OpenVPN can adopt a very strict attitude towards message
|
|
deletion and reordering: Don't allow it. Since TCP guarantees
|
|
reliability, any packet loss or reordering event can be assumed to be an
|
|
attack.</p>
|
|
<p>In this sense, it could be argued that TCP tunnel transport is preferred
|
|
when tunneling non-IP or UDP application protocols which might be
|
|
vulnerable to a message deletion or reordering attack which falls within
|
|
the normal operational parameters of IP networks.</p>
|
|
<p class="last">So I would make the statement that one should never tunnel a non-IP
|
|
protocol or UDP application protocol over UDP, if the protocol might be
|
|
vulnerable to a message deletion or reordering attack that falls within
|
|
the normal operating parameters of what is to be expected from the
|
|
physical IP layer. The problem is easily fixed by simply using TCP as
|
|
the VPN transport layer.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--replay-persist <var>file</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Persist replay-protection state across sessions using <tt class="docutils literal">file</tt> to save
|
|
and reload the state.</p>
|
|
<p>This option will strengthen protection against replay attacks,
|
|
especially when you are using OpenVPN in a dynamic context (such as with
|
|
<tt class="docutils literal"><span class="pre">--inetd</span></tt>) when OpenVPN sessions are frequently started and stopped.</p>
|
|
<p>This option will keep a disk copy of the current replay protection state
|
|
(i.e. the most recent packet timestamp and sequence number received from
|
|
the remote peer), so that if an OpenVPN session is stopped and
|
|
restarted, it will reject any replays of packets which were already
|
|
received by the prior session.</p>
|
|
<p class="last">This option only makes sense when replay protection is enabled (the
|
|
default) and you are using either <tt class="docutils literal"><span class="pre">--secret</span></tt> (shared-secret key mode)
|
|
or TLS mode with <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--socket-flags <var>flags</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Apply the given flags to the OpenVPN transport socket. Currently, only
|
|
<code>TCP_NODELAY</code> is supported.</p>
|
|
<p>The <code>TCP_NODELAY</code> socket flag is useful in TCP mode, and causes the
|
|
kernel to send tunnel packets immediately over the TCP connection without
|
|
trying to group several smaller packets into a larger packet. This can
|
|
result in a considerably improvement in latency.</p>
|
|
<p class="last">This option is pushable from server to client, and should be used on
|
|
both client and server for maximum effect.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--tcp-nodelay</span></kbd></td>
|
|
<td><p class="first">This macro sets the <code>TCP_NODELAY</code> socket flag on the server as well
|
|
as pushes it to connecting clients. The <code>TCP_NODELAY</code> flag disables
|
|
the Nagle algorithm on TCP sockets causing packets to be transmitted
|
|
immediately with low latency, rather than waiting a short period of time
|
|
in order to aggregate several packets into a larger containing packet.
|
|
In VPN applications over TCP, <code>TCP_NODELAY</code> is generally a good
|
|
latency optimization.</p>
|
|
<p>The macro expands as follows:</p>
|
|
<pre class="last literal-block">
|
|
if mode server:
|
|
socket-flags TCP_NODELAY
|
|
push "socket-flags TCP_NODELAY"
|
|
</pre>
|
|
</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="virtual-network-adapter-vpn-interface">
|
|
<h2>Virtual Network Adapter (VPN interface)</h2>
|
|
<p>Options in this section relates to configuration of the virtual tun/tap
|
|
network interface, including setting the VPN IP address and network
|
|
routing.</p>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--bind-dev <var>device</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>(Linux only) Set <tt class="docutils literal">device</tt> to bind the server socket to a
|
|
<a class="reference internal" href="#virtual-routing-and-forwarding">Virtual Routing and Forwarding</a> device</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--block-ipv6</span></kbd></td>
|
|
<td><p class="first">On the client, instead of sending IPv6 packets over the VPN tunnel, all
|
|
IPv6 packets are answered with an ICMPv6 no route host message. On the
|
|
server, all IPv6 packets from clients are answered with an ICMPv6 no
|
|
route to host message. This options is intended for cases when IPv6
|
|
should be blocked and other options are not available. <tt class="docutils literal"><span class="pre">--block-ipv6</span></tt>
|
|
will use the remote IPv6 as source address of the ICMPv6 packets if set,
|
|
otherwise will use <code>fe80::7</code> as source address.</p>
|
|
<p>For this option to make sense you actually have to route traffic to the
|
|
tun interface. The following example config block would send all IPv6
|
|
traffic to OpenVPN and answer all requests with no route to host,
|
|
effectively blocking IPv6 (to avoid IPv6 connections from dual-stacked
|
|
clients leaking around IPv4-only VPN services).</p>
|
|
<dl class="docutils">
|
|
<dt><strong>Client config</strong></dt>
|
|
<dd><pre class="first last literal-block">
|
|
--ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1
|
|
--redirect-gateway ipv6
|
|
--block-ipv6
|
|
</pre>
|
|
</dd>
|
|
<dt><strong>Server config</strong></dt>
|
|
<dd><p class="first">Push a "valid" ipv6 config to the client and block on the server</p>
|
|
<pre class="last literal-block">
|
|
--push "ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1"
|
|
--push "redirect-gateway ipv6"
|
|
--block-ipv6
|
|
</pre>
|
|
</dd>
|
|
</dl>
|
|
<p class="last">Note: this option does not influence traffic sent from the server
|
|
towards the client (neither on the server nor on the client side).
|
|
This is not seen as necessary, as such traffic can be most easily
|
|
avoided by not configuring IPv6 on the server tun, or setting up a
|
|
server-side firewall rule.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--dev <var>device</var></span></kbd></td>
|
|
<td><p class="first">TUN/TAP virtual network device which can be <code>tunX</code>, <code>tapX</code>,
|
|
<code>null</code> or an arbitrary name string (<code>X</code> can be omitted for
|
|
a dynamic device.)</p>
|
|
<p>See examples section below for an example on setting up a TUN device.</p>
|
|
<p>You must use either tun devices on both ends of the connection or tap
|
|
devices on both ends. You cannot mix them, as they represent different
|
|
underlying network layers:</p>
|
|
<dl class="docutils">
|
|
<dt><code>tun</code></dt>
|
|
<dd>devices encapsulate IPv4 or IPv6 (OSI Layer 3)</dd>
|
|
<dt><code>tap</code></dt>
|
|
<dd>devices encapsulate Ethernet 802.3 (OSI Layer 2).</dd>
|
|
</dl>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
dev tun2
|
|
dev tap4
|
|
dev ovpn
|
|
</pre>
|
|
<p class="last">When the device name starts with <code>tun</code> or <code>tap</code>, the device
|
|
type is extracted automatically. Otherwise the <tt class="docutils literal"><span class="pre">--dev-type</span></tt> option
|
|
needs to be added as well.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--dev-node <var>node</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Explicitly set the device node rather than using <code>/dev/net/tun</code>,
|
|
<code>/dev/tun</code>, <code>/dev/tap</code>, etc. If OpenVPN cannot figure out
|
|
whether <tt class="docutils literal">node</tt> is a TUN or TAP device based on the name, you should
|
|
also specify <tt class="docutils literal"><span class="pre">--dev-type</span> tun</tt> or <tt class="docutils literal"><span class="pre">--dev-type</span> tap</tt>.</p>
|
|
<p>Under Mac OS X this option can be used to specify the default tun
|
|
implementation. Using <tt class="docutils literal"><span class="pre">--dev-node</span> utun</tt> forces usage of the native
|
|
Darwin tun kernel support. Use <tt class="docutils literal"><span class="pre">--dev-node</span> utunN</tt> to select a specific
|
|
utun instance. To force using the <code>tun.kext</code> (<code>/dev/tunX</code>)
|
|
use <tt class="docutils literal"><span class="pre">--dev-node</span> tun</tt>. When not specifying a <tt class="docutils literal"><span class="pre">--dev-node</span></tt> option
|
|
openvpn will first try to open utun, and fall back to tun.kext.</p>
|
|
<p class="last">On Windows systems, select the TAP-Win32 adapter which is named <tt class="docutils literal">node</tt>
|
|
in the Network Connections Control Panel or the raw GUID of the adapter
|
|
enclosed by braces. The <tt class="docutils literal"><span class="pre">--show-adapters</span></tt> option under Windows can
|
|
also be used to enumerate all available TAP-Win32 adapters and will show
|
|
both the network connections control panel name and the GUID for each
|
|
TAP-Win32 adapter.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--dev-type <var>device-type</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Which device type are we using? <tt class="docutils literal"><span class="pre">device-type</span></tt> should be <code>tun</code>
|
|
(OSI Layer 3) or <code>tap</code> (OSI Layer 2). Use this option only if
|
|
the TUN/TAP device used with <tt class="docutils literal"><span class="pre">--dev</span></tt> does not begin with <code>tun</code>
|
|
or <code>tap</code>.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--dhcp-option <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Set additional network parameters on supported platforms. May be specified
|
|
on the client or pushed from the server. On Windows these options are
|
|
handled by the <tt class="docutils literal"><span class="pre">tap-windows6</span></tt> driver by default or directly by OpenVPN
|
|
if dhcp is disabled or the <tt class="docutils literal">wintun</tt> driver is in use. The
|
|
<tt class="docutils literal">OpenVPN for Android</tt> client also handles them internally.</p>
|
|
<p>On all other platforms these options are only saved in the client's
|
|
environment under the name <code>foreign_option_{n}</code> before the
|
|
<tt class="docutils literal"><span class="pre">--up</span></tt> script is called. A plugin or an <tt class="docutils literal"><span class="pre">--up</span></tt> script must be used to
|
|
pick up and interpret these as required. Many Linux distributions include
|
|
such scripts and some third-party user interfaces such as tunnelblick also
|
|
come with scripts that process these options.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
dhcp-options type [parm]
|
|
</pre>
|
|
<dl class="last docutils">
|
|
<dt><code>DOMAIN</code> <tt class="docutils literal">name</tt></dt>
|
|
<dd>Set Connection-specific DNS Suffix to <code>name</code>.</dd>
|
|
<dt><code>ADAPTER_DOMAIN_SUFFIX</code> <tt class="docutils literal">name</tt></dt>
|
|
<dd>Alias to <code>DOMAIN</code>. This is a compatibility option, it
|
|
should not be used in new deployments.</dd>
|
|
<dt><code>DOMAIN-SEARCH</code> <tt class="docutils literal">name</tt></dt>
|
|
<dd>Add <code>name</code> to the domain search list.
|
|
Repeat this option to add more entries. Up to
|
|
10 domains are supported.</dd>
|
|
<dt><code>DNS</code> <tt class="docutils literal">address</tt></dt>
|
|
<dd><p class="first">Set primary domain name server IPv4 or IPv6 address.
|
|
Repeat this option to set secondary DNS server addresses.</p>
|
|
<p class="last">Note: DNS IPv6 servers are currently set using netsh (the existing
|
|
DHCP code can only do IPv4 DHCP, and that protocol only permits
|
|
IPv4 addresses anywhere). The option will be put into the
|
|
environment, so an <tt class="docutils literal"><span class="pre">--up</span></tt> script could act upon it if needed.</p>
|
|
</dd>
|
|
<dt><code>WINS</code> <tt class="docutils literal">address</tt></dt>
|
|
<dd>Set primary WINS server address (NetBIOS over TCP/IP Name Server).
|
|
Repeat this option to set secondary WINS server addresses.</dd>
|
|
<dt><code>NBDD</code> <tt class="docutils literal">address</tt></dt>
|
|
<dd>Set primary NBDD server address (NetBIOS over TCP/IP Datagram
|
|
Distribution Server). Repeat this option to set secondary NBDD
|
|
server addresses.</dd>
|
|
<dt><code>NTP</code> <tt class="docutils literal">address</tt></dt>
|
|
<dd>Set primary NTP server address (Network Time Protocol).
|
|
Repeat this option to set secondary NTP server addresses.</dd>
|
|
<dt><code>NBT</code> <tt class="docutils literal">type</tt></dt>
|
|
<dd><p class="first">Set NetBIOS over TCP/IP Node type. Possible options:</p>
|
|
<dl class="last docutils">
|
|
<dt><code>1</code></dt>
|
|
<dd>b-node (broadcasts)</dd>
|
|
<dt><code>2</code></dt>
|
|
<dd>p-node (point-to-point name queries to a WINS server)</dd>
|
|
<dt><code>4</code></dt>
|
|
<dd>m-node (broadcast then query name server)</dd>
|
|
<dt><code>8</code></dt>
|
|
<dd>h-node (query name server, then broadcast).</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>NBS</code> <tt class="docutils literal"><span class="pre">scope-id</span></tt></dt>
|
|
<dd>Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID provides an
|
|
extended naming service for the NetBIOS over TCP/IP (Known as NBT)
|
|
module. The primary purpose of a NetBIOS scope ID is to isolate
|
|
NetBIOS traffic on a single network to only those nodes with the
|
|
same NetBIOS scope ID. The NetBIOS scope ID is a character string
|
|
that is appended to the NetBIOS name. The NetBIOS scope ID on two
|
|
hosts must match, or the two hosts will not be able to communicate.
|
|
The NetBIOS Scope ID also allows computers to use the same computer
|
|
name, as they have different scope IDs. The Scope ID becomes a part
|
|
of the NetBIOS name, making the name unique. (This description of
|
|
NetBIOS scopes courtesy of <a class="reference external" href="mailto:NeonSurge@abyss.com">NeonSurge@abyss.com</a>)</dd>
|
|
<dt><code>DISABLE-NBT</code></dt>
|
|
<dd>Disable Netbios-over-TCP/IP.</dd>
|
|
</dl>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ifconfig <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Set TUN/TAP adapter parameters. It requires the <em>IP address</em> of the local
|
|
VPN endpoint. For TUN devices in point-to-point mode, the next argument
|
|
must be the VPN IP address of the remote VPN endpoint. For TAP devices,
|
|
or TUN devices used with <tt class="docutils literal"><span class="pre">--topology</span> subnet</tt>, the second argument
|
|
is the subnet mask of the virtual network segment which is being created
|
|
or connected to.</p>
|
|
<p>For TUN devices, which facilitate virtual point-to-point IP connections
|
|
(when used in <tt class="docutils literal"><span class="pre">--topology</span> net30</tt> or <tt class="docutils literal">p2p</tt> mode), the proper usage of
|
|
<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> is to use two private IP addresses which are not a member
|
|
of any existing subnet which is in use. The IP addresses may be
|
|
consecutive and should have their order reversed on the remote peer.
|
|
After the VPN is established, by pinging <tt class="docutils literal">rn</tt>, you will be pinging
|
|
across the VPN.</p>
|
|
<p>For TAP devices, which provide the ability to create virtual ethernet
|
|
segments, or TUN devices in <tt class="docutils literal"><span class="pre">--topology</span> subnet</tt> mode (which create
|
|
virtual "multipoint networks"), <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> is used to set an IP
|
|
address and subnet mask just as a physical ethernet adapter would be
|
|
similarly configured. If you are attempting to connect to a remote
|
|
ethernet bridge, the IP address and subnet should be set to values which
|
|
would be valid on the the bridged ethernet segment (note also that DHCP
|
|
can be used for the same purpose).</p>
|
|
<p>This option, while primarily a proxy for the <tt class="docutils literal">ifconfig</tt>(8) command,
|
|
is designed to simplify TUN/TAP tunnel configuration by providing a
|
|
standard interface to the different ifconfig implementations on
|
|
different platforms.</p>
|
|
<p><tt class="docutils literal"><span class="pre">--ifconfig</span></tt> parameters which are IP addresses can also be specified
|
|
as a DNS or /etc/hosts file resolvable name.</p>
|
|
<p>For TAP devices, <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> should not be used if the TAP interface
|
|
will be getting an IP address lease from a DHCP server.</p>
|
|
<p>Examples:</p>
|
|
<pre class="last literal-block">
|
|
# tun device in net30/p2p mode
|
|
ifconfig 10.8.0.2 10.8.0.1
|
|
|
|
# tun/tap device in subnet mode
|
|
ifconfig 10.8.0.2 255.255.255.0
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ifconfig-ipv6 <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Configure an IPv6 address on the <em>tun</em> device.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
ifconfig-ipv6 ipv6addr/bits [ipv6remote]
|
|
</pre>
|
|
<p>The <tt class="docutils literal">ipv6addr/bits</tt> argument is the IPv6 address to use. The
|
|
second parameter is used as route target for <tt class="docutils literal"><span class="pre">--route-ipv6</span></tt> if no
|
|
gateway is specified.</p>
|
|
<p class="last">The <tt class="docutils literal"><span class="pre">--topology</span></tt> option has no influence with <tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt></p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ifconfig-noexec</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Don't actually execute ifconfig/netsh commands, instead pass
|
|
<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> parameters to scripts using environmental variables.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ifconfig-nowarn</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Don't output an options consistency check warning if the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>
|
|
option on this side of the connection doesn't match the remote side.
|
|
This is useful when you want to retain the overall benefits of the
|
|
options consistency check (also see <tt class="docutils literal"><span class="pre">--disable-occ</span></tt> option) while only
|
|
disabling the ifconfig component of the check.</p>
|
|
<p>For example, if you have a configuration where the local host uses
|
|
<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> but the remote host does not, use <tt class="docutils literal"><span class="pre">--ifconfig-nowarn</span></tt>
|
|
on the local host.</p>
|
|
<p class="last">This option will also silence warnings about potential address conflicts
|
|
which occasionally annoy more experienced users by triggering "false
|
|
positive" warnings.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--lladdr <var>address</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Specify the link layer address, more commonly known as the MAC address.
|
|
Only applied to TAP devices.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--persist-tun</span></kbd></td>
|
|
<td><p class="first">Don't close and reopen TUN/TAP device or run up/down scripts across
|
|
<code>SIGUSR1</code> or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> restarts.</p>
|
|
<p class="last"><code>SIGUSR1</code> is a restart signal similar to <code>SIGHUP</code>, but which
|
|
offers finer-grained control over reset options.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--redirect-gateway <var>flags</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Automatically execute routing commands to cause all outgoing IP traffic
|
|
to be redirected over the VPN. This is a client-side option.</p>
|
|
<p>This option performs three steps:</p>
|
|
<ol class="arabic simple">
|
|
<li>Create a static route for the <tt class="docutils literal"><span class="pre">--remote</span></tt> address which
|
|
forwards to the pre-existing default gateway. This is done so that
|
|
<tt class="docutils literal">(3)</tt> will not create a routing loop.</li>
|
|
<li>Delete the default gateway route.</li>
|
|
<li>Set the new default gateway to be the VPN endpoint address
|
|
(derived either from <tt class="docutils literal"><span class="pre">--route-gateway</span></tt> or the second parameter to
|
|
<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is specified).</li>
|
|
</ol>
|
|
<p>When the tunnel is torn down, all of the above steps are reversed so
|
|
that the original default route is restored.</p>
|
|
<p>Option flags:</p>
|
|
<dl class="last docutils">
|
|
<dt><code>local</code></dt>
|
|
<dd>Add the <code>local</code> flag if both OpenVPN peers are directly
|
|
connected via a common subnet, such as with wireless. The
|
|
<code>local</code> flag will cause step <tt class="docutils literal">(1)</tt> above to be omitted.</dd>
|
|
<dt><code>autolocal</code></dt>
|
|
<dd>Try to automatically determine whether to enable <code>local</code>
|
|
flag above.</dd>
|
|
<dt><code>def1</code></dt>
|
|
<dd>Use this flag to override the default gateway by using
|
|
<code>0.0.0.0/1</code> and <code>128.0.0.0/1</code> rather than
|
|
<code>0.0.0.0/0</code>. This has the benefit of overriding but not
|
|
wiping out the original default gateway.</dd>
|
|
<dt><code>bypass-dhcp</code></dt>
|
|
<dd>Add a direct route to the DHCP server (if it is non-local) which
|
|
bypasses the tunnel (Available on Windows clients, may not be
|
|
available on non-Windows clients).</dd>
|
|
<dt><code>bypass-dns</code></dt>
|
|
<dd>Add a direct route to the DNS server(s) (if they are non-local)
|
|
which bypasses the tunnel (Available on Windows clients, may
|
|
not be available on non-Windows clients).</dd>
|
|
<dt><code>block-local</code></dt>
|
|
<dd>Block access to local LAN when the tunnel is active, except for
|
|
the LAN gateway itself. This is accomplished by routing the local
|
|
LAN (except for the LAN gateway address) into the tunnel.</dd>
|
|
<dt><code>ipv6</code></dt>
|
|
<dd>Redirect IPv6 routing into the tunnel. This works similar to
|
|
the <code>def1</code> flag, that is, more specific IPv6 routes are added
|
|
(<code>2000::/4</code>, <code>3000::/4</code>), covering the whole IPv6
|
|
unicast space.</dd>
|
|
<dt><code>!ipv4</code></dt>
|
|
<dd>Do not redirect IPv4 traffic - typically used in the flag pair
|
|
<code>ipv6 !ipv4</code> to redirect IPv6-only.</dd>
|
|
</dl>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--redirect-private <var>flags</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Like <tt class="docutils literal"><span class="pre">--redirect-gateway</span></tt>, but omit actually changing the default gateway.
|
|
Useful when pushing private subnets.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--route <var>args</var></span></kbd></td>
|
|
<td><p class="first">Add route to routing table after connection is established. Multiple
|
|
routes can be specified. Routes will be automatically torn down in
|
|
reverse order prior to TUN/TAP device close.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
route network/IP
|
|
route network/IP netmask
|
|
route network/IP netmask gateway
|
|
route network/IP netmask gateway metric
|
|
</pre>
|
|
<p>This option is intended as a convenience proxy for the <tt class="docutils literal">route</tt>(8)
|
|
shell command, while at the same time providing portable semantics
|
|
across OpenVPN's platform space.</p>
|
|
<dl class="docutils">
|
|
<dt><tt class="docutils literal">netmask</tt></dt>
|
|
<dd>defaults to <code>255.255.255.255</code> when not given</dd>
|
|
<dt><tt class="docutils literal">gateway</tt></dt>
|
|
<dd>default taken from <tt class="docutils literal"><span class="pre">--route-gateway</span></tt> or the second
|
|
parameter to <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is specified.</dd>
|
|
<dt><tt class="docutils literal">metric</tt></dt>
|
|
<dd>default taken from <tt class="docutils literal"><span class="pre">--route-metric</span></tt> if set, otherwise <code>0</code>.</dd>
|
|
</dl>
|
|
<p>The default can be specified by leaving an option blank or setting it to
|
|
<code>default</code>.</p>
|
|
<p>The <tt class="docutils literal">network</tt> and <tt class="docutils literal">gateway</tt> parameters can also be specified as a
|
|
DNS or <code>/etc/hosts</code> file resolvable name, or as one of three special
|
|
keywords:</p>
|
|
<dl class="last docutils">
|
|
<dt><code>vpn_gateway</code></dt>
|
|
<dd>The remote VPN endpoint address (derived either from
|
|
<tt class="docutils literal"><span class="pre">--route-gateway</span></tt> or the second parameter to <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>
|
|
when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is specified).</dd>
|
|
<dt><code>net_gateway</code></dt>
|
|
<dd>The pre-existing IP default gateway, read from the
|
|
routing table (not supported on all OSes).</dd>
|
|
<dt><code>remote_host</code></dt>
|
|
<dd>The <tt class="docutils literal"><span class="pre">--remote</span></tt> address if OpenVPN is being run in
|
|
client mode, and is undefined in server mode.</dd>
|
|
</dl>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--route-delay <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
route-delay
|
|
route-delay n
|
|
route-delay n m
|
|
</pre>
|
|
<p>Delay <tt class="docutils literal">n</tt> seconds (default <code>0</code>) after connection establishment,
|
|
before adding routes. If <tt class="docutils literal">n</tt> is <code>0</code>, routes will be added
|
|
immediately upon connection establishment. If <tt class="docutils literal"><span class="pre">--route-delay</span></tt> is
|
|
omitted, routes will be added immediately after TUN/TAP device open and
|
|
<tt class="docutils literal"><span class="pre">--up</span></tt> script execution, before any <tt class="docutils literal"><span class="pre">--user</span></tt> or <tt class="docutils literal"><span class="pre">--group</span></tt> privilege
|
|
downgrade (or <tt class="docutils literal"><span class="pre">--chroot</span></tt> execution.)</p>
|
|
<p>This option is designed to be useful in scenarios where DHCP is used to
|
|
set tap adapter addresses. The delay will give the DHCP handshake time
|
|
to complete before routes are added.</p>
|
|
<p class="last">On Windows, <tt class="docutils literal"><span class="pre">--route-delay</span></tt> tries to be more intelligent by waiting
|
|
<tt class="docutils literal">w</tt> seconds (default <code>30</code> by default) for the TAP-Win32 adapter
|
|
to come up before adding routes.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--route-ipv6 <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Setup IPv6 routing in the system to send the specified IPv6 network into
|
|
OpenVPN's <em>tun</em>.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
route-ipv6 ipv6addr/bits [gateway] [metric]
|
|
</pre>
|
|
<p class="last">The gateway parameter is only used for IPv6 routes across <em>tap</em> devices,
|
|
and if missing, the <tt class="docutils literal">ipv6remote</tt> field from <tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt> or
|
|
<tt class="docutils literal"><span class="pre">--route-ipv6-gateway</span></tt> is used.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--route-gateway <var>arg</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Specify a default <em>gateway</em> for use with <tt class="docutils literal"><span class="pre">--route</span></tt>.</p>
|
|
<p>If <code>dhcp</code> is specified as the parameter, the gateway address will
|
|
be extracted from a DHCP negotiation with the OpenVPN server-side LAN.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="last literal-block">
|
|
route-gateway gateway
|
|
route-gateway dhcp
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--route-ipv6-gateway <var>gw</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Specify a default gateway <tt class="docutils literal">gw</tt> for use with <tt class="docutils literal"><span class="pre">--route-ipv6</span></tt>.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--route-metric <var>m</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Specify a default metric <tt class="docutils literal">m</tt> for use with <tt class="docutils literal"><span class="pre">--route</span></tt>.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--route-noexec</span></kbd></td>
|
|
<td>Don't add or remove routes automatically. Instead pass routes to
|
|
<tt class="docutils literal"><span class="pre">--route-up</span></tt> script using environmental variables.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--route-nopull</span></kbd></td>
|
|
<td><p class="first">When used with <tt class="docutils literal"><span class="pre">--client</span></tt> or <tt class="docutils literal"><span class="pre">--pull</span></tt>, accept options pushed by
|
|
server EXCEPT for routes, block-outside-dns and dhcp options like DNS
|
|
servers.</p>
|
|
<p class="last">When used on the client, this option effectively bars the server from
|
|
adding routes to the client's routing table, however note that this
|
|
option still allows the server to set the TCP/IP properties of the
|
|
client's TUN/TAP interface.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--topology <var>mode</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Configure virtual addressing topology when running in <tt class="docutils literal"><span class="pre">--dev</span> tun</tt>
|
|
mode. This directive has no meaning in <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> mode, which always
|
|
uses a <code>subnet</code> topology.</p>
|
|
<p>If you set this directive on the server, the <tt class="docutils literal"><span class="pre">--server</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">--server-bridge</span></tt> directives will automatically push your chosen
|
|
topology setting to clients as well. This directive can also be manually
|
|
pushed to clients. Like the <tt class="docutils literal"><span class="pre">--dev</span></tt> directive, this directive must
|
|
always be compatible between client and server.</p>
|
|
<p><tt class="docutils literal">mode</tt> can be one of:</p>
|
|
<dl class="docutils">
|
|
<dt><code>net30</code></dt>
|
|
<dd>Use a point-to-point topology, by allocating one /30 subnet
|
|
per client. This is designed to allow point-to-point semantics when some
|
|
or all of the connecting clients might be Windows systems. This is the
|
|
default on OpenVPN 2.0.</dd>
|
|
<dt><code>p2p</code></dt>
|
|
<dd>Use a point-to-point topology where the remote endpoint of
|
|
the client's tun interface always points to the local endpoint of the
|
|
server's tun interface. This mode allocates a single IP address per
|
|
connecting client. Only use when none of the connecting clients are
|
|
Windows systems.</dd>
|
|
<dt><code>subnet</code></dt>
|
|
<dd>Use a subnet rather than a point-to-point topology by
|
|
configuring the tun interface with a local IP address and subnet mask,
|
|
similar to the topology used in <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> and ethernet bridging
|
|
mode. This mode allocates a single IP address per connecting client and
|
|
works on Windows as well. Only available when server and clients are
|
|
OpenVPN 2.1 or higher, or OpenVPN 2.0.x which has been manually patched
|
|
with the <tt class="docutils literal"><span class="pre">--topology</span></tt> directive code. When used on Windows, requires
|
|
version 8.2 or higher of the TAP-Win32 driver. When used on *nix,
|
|
requires that the tun driver supports an <tt class="docutils literal">ifconfig</tt>(8) command which
|
|
sets a subnet instead of a remote endpoint IP address.</dd>
|
|
</dl>
|
|
<p class="last"><em>Note:</em> Using <tt class="docutils literal"><span class="pre">--topology</span> subnet</tt> changes the interpretation of the
|
|
arguments of <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> to mean "address netmask", no longer "local
|
|
remote".</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--tun-mtu <var>n</var></span></kbd></td>
|
|
<td><p class="first">Take the TUN device MTU to be <strong>n</strong> and derive the link MTU from it
|
|
(default <code>1500</code>). In most cases, you will probably want to leave
|
|
this parameter set to its default value.</p>
|
|
<p>The MTU (Maximum Transmission Units) is the maximum datagram size in
|
|
bytes that can be sent unfragmented over a particular network path.
|
|
OpenVPN requires that packets on the control and data channels be sent
|
|
unfragmented.</p>
|
|
<p>MTU problems often manifest themselves as connections which hang during
|
|
periods of active usage.</p>
|
|
<p class="last">It's best to use the <tt class="docutils literal"><span class="pre">--fragment</span></tt> and/or <tt class="docutils literal"><span class="pre">--mssfix</span></tt> options to deal
|
|
with MTU sizing issues.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tun-mtu-extra <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Assume that the TUN/TAP device might return as many as <tt class="docutils literal">n</tt> bytes more
|
|
than the <tt class="docutils literal"><span class="pre">--tun-mtu</span></tt> size on read. This parameter defaults to 0, which
|
|
is sufficient for most TUN devices. TAP devices may introduce additional
|
|
overhead in excess of the MTU size, and a setting of 32 is the default
|
|
when TAP devices are used. This parameter only controls internal OpenVPN
|
|
buffer sizing, so there is no transmission overhead associated with
|
|
using a larger value.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="tun-tap-standalone-operations">
|
|
<h2>TUN/TAP standalone operations</h2>
|
|
<p>These two standalone operations will require <tt class="docutils literal"><span class="pre">--dev</span></tt> and optionally
|
|
<tt class="docutils literal"><span class="pre">--user</span></tt> and/or <tt class="docutils literal"><span class="pre">--group</span></tt>.</p>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--mktun</span></kbd></td>
|
|
<td><p class="first">(Standalone) Create a persistent tunnel on platforms which support them
|
|
such as Linux. Normally TUN/TAP tunnels exist only for the period of
|
|
time that an application has them open. This option takes advantage of
|
|
the TUN/TAP driver's ability to build persistent tunnels that live
|
|
through multiple instantiations of OpenVPN and die only when they are
|
|
deleted or the machine is rebooted.</p>
|
|
<p>One of the advantages of persistent tunnels is that they eliminate the
|
|
need for separate <tt class="docutils literal"><span class="pre">--up</span></tt> and <tt class="docutils literal"><span class="pre">--down</span></tt> scripts to run the appropriate
|
|
<tt class="docutils literal">ifconfig</tt>(8) and <tt class="docutils literal">route</tt>(8) commands. These commands can be
|
|
placed in the the same shell script which starts or terminates an
|
|
OpenVPN session.</p>
|
|
<p>Another advantage is that open connections through the TUN/TAP-based
|
|
tunnel will not be reset if the OpenVPN peer restarts. This can be
|
|
useful to provide uninterrupted connectivity through the tunnel in the
|
|
event of a DHCP reset of the peer's public IP address (see the
|
|
<tt class="docutils literal"><span class="pre">--ipchange</span></tt> option above).</p>
|
|
<p>One disadvantage of persistent tunnels is that it is harder to
|
|
automatically configure their MTU value (see <tt class="docutils literal"><span class="pre">--link-mtu</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">--tun-mtu</span></tt> above).</p>
|
|
<p class="last">On some platforms such as Windows, TAP-Win32 tunnels are persistent by
|
|
default.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--rmtun</span></kbd></td>
|
|
<td>(Standalone) Remove a persistent tunnel.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="virtual-routing-and-forwarding">
|
|
<h2>Virtual Routing and Forwarding</h2>
|
|
<p>Options in this section relates to configuration of virtual routing and
|
|
forwarding in combination with the underlying operating system.</p>
|
|
<p>As of today this is only supported on Linux, a kernel >= 4.9 is
|
|
recommended.</p>
|
|
<p>This could come in handy when for example the external network should be
|
|
only used as a means to connect to some VPN endpoints and all regular
|
|
traffic should only be routed through any tunnel(s). This could be
|
|
achieved by setting up a VRF and configuring the interface connected to
|
|
the external network to be part of the VRF. The examples below will cover
|
|
this setup.</p>
|
|
<p>Another option would be to put the tun/tap interface into a VRF. This could
|
|
be done by an up-script which uses the <code>ip link set</code> command shown
|
|
below.</p>
|
|
<div class="section" id="vrf-setup-with-iproute2">
|
|
<h3>VRF setup with iproute2</h3>
|
|
<p>Create VRF <code>vrf_external</code> and map it to routing table <code>1023</code></p>
|
|
<pre class="literal-block">
|
|
ip link add vrf_external type vrf table 1023
|
|
</pre>
|
|
<p>Move <code>eth0</code> into <code>vrf_external</code></p>
|
|
<pre class="literal-block">
|
|
ip link set master vrf_external dev eth0
|
|
</pre>
|
|
<p>Any prefixes configured on <code>eth0</code> will be moved from the :code`main`
|
|
routing table into routing table <cite>1023</cite></p>
|
|
</div>
|
|
<div class="section" id="vrf-setup-with-ifupdown">
|
|
<h3>VRF setup with ifupdown</h3>
|
|
<p>For Debian based Distributions <code>ifupdown2</code> provides an almost drop-in
|
|
replacement for <code>ifupdown</code> including VRFs and other features.
|
|
A configuration for an interface <code>eth0</code> being part of VRF
|
|
code:<cite>vrf_external</cite> could look like this:</p>
|
|
<pre class="literal-block">
|
|
auto eth0
|
|
iface eth0
|
|
address 192.0.2.42/24
|
|
address 2001:db8:08:15::42/64
|
|
gateway 192.0.2.1
|
|
gateway 2001:db8:08:15::1
|
|
vrf vrf_external
|
|
|
|
auto vrf_external
|
|
iface vrf_external
|
|
vrf-table 1023
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="openvpn-configuration">
|
|
<h3>OpenVPN configuration</h3>
|
|
<p>The OpenVPN configuration needs to contain this line:</p>
|
|
<pre class="literal-block">
|
|
bind-dev vrf_external
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="further-reading">
|
|
<h3>Further reading</h3>
|
|
<p>Wikipedia has nice page one VRFs: <a class="reference external" href="https://en.wikipedia.org/wiki/Virtual_routing_and_forwarding">https://en.wikipedia.org/wiki/Virtual_routing_and_forwarding</a></p>
|
|
<p>This talk from the Network Track of FrOSCon 2018 provides an overview about
|
|
advanced layer 2 and layer 3 features of Linux</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>Slides: <a class="reference external" href="https://www.slideshare.net/BarbarossaTM/l2l3-fr-fortgeschrittene-helle-und-dunkle-magie-im-linuxnetzwerkstack">https://www.slideshare.net/BarbarossaTM/l2l3-fr-fortgeschrittene-helle-und-dunkle-magie-im-linuxnetzwerkstack</a></li>
|
|
<li>Video (german): <a class="reference external" href="https://media.ccc.de/v/froscon2018-2247-l2_l3_fur_fortgeschrittene_-_helle_und_dunkle_magie_im_linux-netzwerkstack">https://media.ccc.de/v/froscon2018-2247-l2_l3_fur_fortgeschrittene_-_helle_und_dunkle_magie_im_linux-netzwerkstack</a></li>
|
|
</ul>
|
|
</blockquote>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="scripting-integration">
|
|
<h1>SCRIPTING INTEGRATION</h1>
|
|
<p>OpenVPN can execute external scripts in various phases of the lifetime of
|
|
the OpenVPN process.</p>
|
|
<div class="section" id="script-order-of-execution">
|
|
<h2>Script Order of Execution</h2>
|
|
<ol class="arabic">
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">--up</span></tt></p>
|
|
<p>Executed after TCP/UDP socket bind and TUN/TAP open.</p>
|
|
</li>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">--tls-verify</span></tt></p>
|
|
<p>Executed when we have a still untrusted remote peer.</p>
|
|
</li>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">--ipchange</span></tt></p>
|
|
<p>Executed after connection authentication, or remote IP address change.</p>
|
|
</li>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">--client-connect</span></tt></p>
|
|
<p>Executed in <strong>--mode server</strong> mode immediately after client
|
|
authentication.</p>
|
|
</li>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">--route-up</span></tt></p>
|
|
<p>Executed after connection authentication, either immediately after, or
|
|
some number of seconds after as defined by the <strong>--route-delay</strong> option.</p>
|
|
</li>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">--route-pre-down</span></tt></p>
|
|
<p>Executed right before the routes are removed.</p>
|
|
</li>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">--client-disconnect</span></tt></p>
|
|
<p>Executed in <tt class="docutils literal"><span class="pre">--mode</span> server</tt> mode on client instance shutdown.</p>
|
|
</li>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">--down</span></tt></p>
|
|
<p>Executed after TCP/UDP and TUN/TAP close.</p>
|
|
</li>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">--learn-address</span></tt></p>
|
|
<p>Executed in <tt class="docutils literal"><span class="pre">--mode</span> server</tt> mode whenever an IPv4 address/route or MAC
|
|
address is added to OpenVPN's internal routing table.</p>
|
|
</li>
|
|
<li><p class="first"><tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt></p>
|
|
<p>Executed in <tt class="docutils literal"><span class="pre">--mode</span> server</tt> mode on new client connections, when the
|
|
client is still untrusted.</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="section" id="script-hooks">
|
|
<h2>SCRIPT HOOKS</h2>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--auth-user-pass-verify <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Require the client to provide a username/password (possibly in addition
|
|
to a client certificate) for authentication.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
auth-user-pass-verify cmd method
|
|
</pre>
|
|
<p>OpenVPN will run command <tt class="docutils literal">cmd</tt> to validate the username/password
|
|
provided by the client.</p>
|
|
<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
|
|
followed by arguments. The path and arguments may be single- or
|
|
double-quoted and/or escaped using a backslash, and should be separated
|
|
by one or more spaces.</p>
|
|
<p>If <tt class="docutils literal">method</tt> is set to <code>via-env</code>, OpenVPN will call <tt class="docutils literal">script</tt>
|
|
with the environmental variables <code>username</code> and <code>password</code>
|
|
set to the username/password strings provided by the client. <em>Beware</em>
|
|
that this method is insecure on some platforms which make the environment
|
|
of a process publicly visible to other unprivileged processes.</p>
|
|
<p>If <tt class="docutils literal">method</tt> is set to <code>via-file</code>, OpenVPN will write the username
|
|
and password to the first two lines of a temporary file. The filename
|
|
will be passed as an argument to <tt class="docutils literal">script</tt>, and the file will be
|
|
automatically deleted by OpenVPN after the script returns. The location
|
|
of the temporary file is controlled by the <tt class="docutils literal"><span class="pre">--tmp-dir</span></tt> option, and
|
|
will default to the current directory if unspecified. For security,
|
|
consider setting <tt class="docutils literal"><span class="pre">--tmp-dir</span></tt> to a volatile storage medium such as
|
|
<code>/dev/shm</code> (if available) to prevent the username/password file
|
|
from touching the hard drive.</p>
|
|
<p>The script should examine the username and password, returning a success
|
|
exit code (<code>0</code>) if the client's authentication request is to be
|
|
accepted, or a failure code (<code>1</code>) to reject the client.</p>
|
|
<p>This directive is designed to enable a plugin-style interface for
|
|
extending OpenVPN's authentication capabilities.</p>
|
|
<p>To protect against a client passing a maliciously formed username or
|
|
password string, the username string must consist only of these
|
|
characters: alphanumeric, underbar ('<code>_</code>'), dash ('<code>-</code>'),
|
|
dot ('<code>.</code>'), or at ('<code>@</code>'). The password string can consist
|
|
of any printable characters except for CR or LF. Any illegal characters
|
|
in either the username or password string will be converted to
|
|
underbar ('<code>_</code>').</p>
|
|
<p>Care must be taken by any user-defined scripts to avoid creating a
|
|
security vulnerability in the way that these strings are handled. Never
|
|
use these strings in such a way that they might be escaped or evaluated
|
|
by a shell interpreter.</p>
|
|
<p class="last">For a sample script that performs PAM authentication, see
|
|
<code>sample-scripts/auth-pam.pl</code> in the OpenVPN source distribution.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--client-connect <var>cmd</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> on client connection.</p>
|
|
<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
|
|
followed by arguments. The path and arguments may be single- or
|
|
double-quoted and/or escaped using a backslash, and should be separated
|
|
by one or more spaces.</p>
|
|
<p>The command is passed the common name and IP address of the
|
|
just-authenticated client as environmental variables (see environmental
|
|
variable section below). The command is also passed the pathname of a
|
|
freshly created temporary file as the last argument (after any arguments
|
|
specified in <tt class="docutils literal">cmd</tt> ), to be used by the command to pass dynamically
|
|
generated config file directives back to OpenVPN.</p>
|
|
<p>If the script wants to generate a dynamic config file to be applied on
|
|
the server when the client connects, it should write it to the file
|
|
named by the last argument.</p>
|
|
<p>See the <tt class="docutils literal"><span class="pre">--client-config-dir</span></tt> option below for options which can be
|
|
legally used in a dynamically generated config file.</p>
|
|
<p>Note that the return value of <tt class="docutils literal">script</tt> is significant. If <tt class="docutils literal">script</tt>
|
|
returns a non-zero error status, it will cause the client to be
|
|
disconnected.</p>
|
|
<p class="last">If a <tt class="docutils literal"><span class="pre">--client-connect</span></tt> wants to defer the generating of the
|
|
configuration then the script needs to use the
|
|
<code>client_connect_deferred_file</code> and
|
|
<code>client_connect_config_file</code> environment variables, and write
|
|
status accordingly into these files. See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a>
|
|
section for more details.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--client-disconnect <var>cmd</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Like <tt class="docutils literal"><span class="pre">--client-connect</span></tt> but called on client instance shutdown. Will
|
|
not be called unless the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script and plugins (if
|
|
defined) were previously called on this instance with successful (0)
|
|
status returns.</p>
|
|
<p>The exception to this rule is if the <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> command or
|
|
plugins are cascaded, and at least one client-connect function
|
|
succeeded, then ALL of the client-disconnect functions for scripts and
|
|
plugins will be called on client instance object deletion, even in cases
|
|
where some of the related client-connect functions returned an error
|
|
status.</p>
|
|
<p class="last">The <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> command is not passed any extra arguments
|
|
(only those arguments specified in cmd, if any).</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--down <var>cmd</var></span></kbd></td>
|
|
<td><p class="first">Run command <tt class="docutils literal">cmd</tt> after TUN/TAP device close (post <tt class="docutils literal"><span class="pre">--user</span></tt> UID
|
|
change and/or <tt class="docutils literal"><span class="pre">--chroot</span></tt> ). <tt class="docutils literal">cmd</tt> consists of a path to script (or
|
|
executable program), optionally followed by arguments. The path and
|
|
arguments may be single- or double-quoted and/or escaped using a
|
|
backslash, and should be separated by one or more spaces.</p>
|
|
<p>Called with the same parameters and environmental variables as the
|
|
<tt class="docutils literal"><span class="pre">--up</span></tt> option above.</p>
|
|
<p class="last">Note that if you reduce privileges by using <tt class="docutils literal"><span class="pre">--user</span></tt> and/or
|
|
<tt class="docutils literal"><span class="pre">--group</span></tt>, your <tt class="docutils literal"><span class="pre">--down</span></tt> script will also run at reduced privilege.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--down-pre</span></kbd></td>
|
|
<td>Call <tt class="docutils literal"><span class="pre">--down</span></tt> cmd/script before, rather than after, TUN/TAP close.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--ipchange <var>cmd</var></span></kbd></td>
|
|
<td><p class="first">Run command <tt class="docutils literal">cmd</tt> when our remote ip-address is initially
|
|
authenticated or changes.</p>
|
|
<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
|
|
followed by arguments. The path and arguments may be single- or
|
|
double-quoted and/or escaped using a backslash, and should be separated
|
|
by one or more spaces.</p>
|
|
<p>When <tt class="docutils literal">cmd</tt> is executed two arguments are appended after any arguments
|
|
specified in <tt class="docutils literal">cmd</tt> , as follows:</p>
|
|
<pre class="literal-block">
|
|
cmd ip address port number
|
|
</pre>
|
|
<p>Don't use <tt class="docutils literal"><span class="pre">--ipchange</span></tt> in <tt class="docutils literal"><span class="pre">--mode</span> server</tt> mode. Use a
|
|
<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script instead.</p>
|
|
<p>See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional
|
|
parameters passed as environmental variables.</p>
|
|
<p>If you are running in a dynamic IP address environment where the IP
|
|
addresses of either peer could change without notice, you can use this
|
|
script, for example, to edit the <code>/etc/hosts</code> file with the current
|
|
address of the peer. The script will be run every time the remote peer
|
|
changes its IP address.</p>
|
|
<p class="last">Similarly if <em>our</em> IP address changes due to DHCP, we should configure
|
|
our IP address change script (see man page for <tt class="docutils literal">dhcpcd</tt>(8)) to
|
|
deliver a <tt class="docutils literal">SIGHUP</tt> or <tt class="docutils literal">SIGUSR1</tt> signal to OpenVPN. OpenVPN will
|
|
then re-establish a connection with its most recently authenticated
|
|
peer on its new IP address.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--learn-address <var>cmd</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> to validate client virtual addresses or routes.</p>
|
|
<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
|
|
followed by arguments. The path and arguments may be single- or
|
|
double-quoted and/or escaped using a backslash, and should be separated
|
|
by one or more spaces.</p>
|
|
<p>Three arguments will be appended to any arguments in <tt class="docutils literal">cmd</tt> as follows:</p>
|
|
<dl class="docutils">
|
|
<dt><code>$1</code> - [operation]</dt>
|
|
<dd><code>"add"</code>, <code>"update"</code>, or <code>"delete"</code> based on whether
|
|
or not the address is being added to, modified, or deleted from
|
|
OpenVPN's internal routing table.</dd>
|
|
<dt><code>$2</code> - [address]</dt>
|
|
<dd>The address being learned or unlearned. This can be an IPv4 address
|
|
such as <code>"198.162.10.14"</code>, an IPv4 subnet such as
|
|
<code>"198.162.10.0/24"</code>, or an ethernet MAC address (when
|
|
<tt class="docutils literal"><span class="pre">--dev</span> tap</tt> is being used) such as <code>"00:FF:01:02:03:04"</code>.</dd>
|
|
<dt><code>$3</code> - [common name]</dt>
|
|
<dd>The common name on the certificate associated with the client linked
|
|
to this address. Only present for <code>"add"</code> or <code>"update"</code>
|
|
operations, not <code>"delete"</code>.</dd>
|
|
</dl>
|
|
<p>On <code>"add"</code> or <code>"update"</code> methods, if the script returns
|
|
a failure code (non-zero), OpenVPN will reject the address and will not
|
|
modify its internal routing table.</p>
|
|
<p class="last">Normally, the <tt class="docutils literal">cmd</tt> script will use the information provided above to
|
|
set appropriate firewall entries on the VPN TUN/TAP interface. Since
|
|
OpenVPN provides the association between virtual IP or MAC address and
|
|
the client's authenticated common name, it allows a user-defined script
|
|
to configure firewall access policies with regard to the client's
|
|
high-level common name, rather than the low level client virtual
|
|
addresses.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--route-up <var>cmd</var></span></kbd></td>
|
|
<td><p class="first">Run command <tt class="docutils literal">cmd</tt> after routes are added, subject to <tt class="docutils literal"><span class="pre">--route-delay</span></tt>.</p>
|
|
<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
|
|
followed by arguments. The path and arguments may be single- or
|
|
double-quoted and/or escaped using a backslash, and should be separated
|
|
by one or more spaces.</p>
|
|
<p class="last">See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional
|
|
parameters passed as environmental variables.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--route-pre-down <var>cmd</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> before routes are removed upon disconnection.</p>
|
|
<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
|
|
followed by arguments. The path and arguments may be single- or
|
|
double-quoted and/or escaped using a backslash, and should be separated
|
|
by one or more spaces.</p>
|
|
<p class="last">See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional
|
|
parameters passed as environmental variables.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--setenv <var>args</var></span></kbd></td>
|
|
<td><p class="first">Set a custom environmental variable <code>name=value</code> to pass to script.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
setenv name value
|
|
setenv FORWARD_COMPATIBLE 1
|
|
setenv opt config_option
|
|
</pre>
|
|
<p>By setting <code>FORWARD_COMPATIBLE</code> to <code>1</code>, the config file
|
|
syntax checking is relaxed so that unknown directives will trigger a
|
|
warning but not a fatal error, on the assumption that a given unknown
|
|
directive might be valid in future OpenVPN versions.</p>
|
|
<p>This option should be used with caution, as there are good security
|
|
reasons for having OpenVPN fail if it detects problems in a config file.
|
|
Having said that, there are valid reasons for wanting new software
|
|
features to gracefully degrade when encountered by older software
|
|
versions.</p>
|
|
<p>It is also possible to tag a single directive so as not to trigger a
|
|
fatal error if the directive isn't recognized. To do this, prepend the
|
|
following before the directive: <tt class="docutils literal">setenv opt</tt></p>
|
|
<p>Versions prior to OpenVPN 2.3.3 will always ignore options set with the
|
|
<tt class="docutils literal">setenv opt</tt> directive.</p>
|
|
<p class="last">See also <tt class="docutils literal"><span class="pre">--ignore-unknown-option</span></tt></p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--setenv-safe <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Set a custom environmental variable <code>OPENVPN_name</code> to <code>value</code>
|
|
to pass to scripts.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
setenv-safe name value
|
|
</pre>
|
|
<p class="last">This directive is designed to be pushed by the server to clients, and
|
|
the prepending of <code>OPENVPN_</code> to the environmental variable is a
|
|
safety precaution to prevent a <code>LD_PRELOAD</code> style attack from a
|
|
malicious or compromised server.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tls-verify <var>cmd</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Run command <tt class="docutils literal">cmd</tt> to verify the X509 name of a pending TLS connection
|
|
that has otherwise passed all other tests of certification (except for
|
|
revocation via <tt class="docutils literal"><span class="pre">--crl-verify</span></tt> directive; the revocation test occurs
|
|
after the <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> test).</p>
|
|
<p><tt class="docutils literal">cmd</tt> should return <code>0</code> to allow the TLS handshake to proceed,
|
|
or <code>1</code> to fail.</p>
|
|
<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
|
|
followed by arguments. The path and arguments may be single- or
|
|
double-quoted and/or escaped using a backslash, and should be separated
|
|
by one or more spaces.</p>
|
|
<p>When <tt class="docutils literal">cmd</tt> is executed two arguments are appended after any arguments
|
|
specified in <tt class="docutils literal">cmd</tt>, as follows:</p>
|
|
<pre class="literal-block">
|
|
cmd certificate_depth subject
|
|
</pre>
|
|
<p>These arguments are, respectively, the current certificate depth and the
|
|
X509 subject distinguished name (dn) of the peer.</p>
|
|
<p>This feature is useful if the peer you want to trust has a certificate
|
|
which was signed by a certificate authority who also signed many other
|
|
certificates, where you don't necessarily want to trust all of them, but
|
|
rather be selective about which peer certificate you will accept. This
|
|
feature allows you to write a script which will test the X509 name on a
|
|
certificate and decide whether or not it should be accepted. For a
|
|
simple perl script which will test the common name field on the
|
|
certificate, see the file <tt class="docutils literal"><span class="pre">verify-cn</span></tt> in the OpenVPN distribution.</p>
|
|
<p class="last">See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional
|
|
parameters passed as environmental variables.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--up <var>cmd</var></span></kbd></td>
|
|
<td><p class="first">Run command <tt class="docutils literal">cmd</tt> after successful TUN/TAP device open (pre <tt class="docutils literal"><span class="pre">--user</span></tt>
|
|
UID change).</p>
|
|
<p><tt class="docutils literal">cmd</tt> consists of a path to a script (or executable program), optionally
|
|
followed by arguments. The path and arguments may be single- or
|
|
double-quoted and/or escaped using a backslash, and should be separated
|
|
by one or more spaces.</p>
|
|
<p>The up command is useful for specifying route commands which route IP
|
|
traffic destined for private subnets which exist at the other end of the
|
|
VPN connection into the tunnel.</p>
|
|
<p>For <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> execute as:</p>
|
|
<pre class="literal-block">
|
|
cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [init | restart]
|
|
</pre>
|
|
<p>For <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> execute as:</p>
|
|
<pre class="literal-block">
|
|
cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [init | restart]
|
|
</pre>
|
|
<p>See the <a class="reference internal" href="#environmental-variables">Environmental Variables</a> section below for additional
|
|
parameters passed as environmental variables.</p>
|
|
<p>Note that if <tt class="docutils literal">cmd</tt> includes arguments, all OpenVPN-generated arguments
|
|
will be appended to them to build an argument list with which the
|
|
executable will be called.</p>
|
|
<p>Typically, <tt class="docutils literal">cmd</tt> will run a script to add routes to the tunnel.</p>
|
|
<p>Normally the up script is called after the TUN/TAP device is opened. In
|
|
this context, the last command line parameter passed to the script will
|
|
be <em>init.</em> If the <tt class="docutils literal"><span class="pre">--up-restart</span></tt> option is also used, the up script
|
|
will be called for restarts as well. A restart is considered to be a
|
|
partial reinitialization of OpenVPN where the TUN/TAP instance is
|
|
preserved (the <tt class="docutils literal"><span class="pre">--persist-tun</span></tt> option will enable such preservation).
|
|
A restart can be generated by a SIGUSR1 signal, a <tt class="docutils literal"><span class="pre">--ping-restart</span></tt>
|
|
timeout, or a connection reset when the TCP protocol is enabled with the
|
|
<tt class="docutils literal"><span class="pre">--proto</span></tt> option. If a restart occurs, and <tt class="docutils literal"><span class="pre">--up-restart</span></tt> has been
|
|
specified, the up script will be called with <em>restart</em> as the last
|
|
parameter.</p>
|
|
<dl class="docutils">
|
|
<dt><em>NOTE:</em></dt>
|
|
<dd>On restart, OpenVPN will not pass the full set of environment
|
|
variables to the script. Namely, everything related to routing and
|
|
gateways will not be passed, as nothing needs to be done anyway - all
|
|
the routing setup is already in place. Additionally, the up-restart
|
|
script will run with the downgraded UID/GID settings (if configured).</dd>
|
|
</dl>
|
|
<p>The following standalone example shows how the <tt class="docutils literal"><span class="pre">--up</span></tt> script can be
|
|
called in both an initialization and restart context. (<em>NOTE:</em> for
|
|
security reasons, don't run the following example unless UDP port 9999
|
|
is blocked by your firewall. Also, the example will run indefinitely, so
|
|
you should abort with control-c).</p>
|
|
<pre class="literal-block">
|
|
openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 \
|
|
--up 'echo up' --down 'echo down' --persist-tun \
|
|
--up-restart
|
|
</pre>
|
|
<p>Note that OpenVPN also provides the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> option to
|
|
automatically ifconfig the TUN device, eliminating the need to define an
|
|
<tt class="docutils literal"><span class="pre">--up</span></tt> script, unless you also want to configure routes in the
|
|
<tt class="docutils literal"><span class="pre">--up</span></tt> script.</p>
|
|
<p>If <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> is also specified, OpenVPN will pass the ifconfig
|
|
local and remote endpoints on the command line to the <tt class="docutils literal"><span class="pre">--up</span></tt> script so
|
|
that they can be used to configure routes such as:</p>
|
|
<pre class="last literal-block">
|
|
route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
|
|
</pre>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--up-delay</span></kbd></td>
|
|
<td><p class="first">Delay TUN/TAP open and possible <tt class="docutils literal"><span class="pre">--up</span></tt> script execution until after
|
|
TCP/UDP connection establishment with peer.</p>
|
|
<p>In <tt class="docutils literal"><span class="pre">--proto</span> udp</tt> mode, this option normally requires the use of
|
|
<tt class="docutils literal"><span class="pre">--ping</span></tt> to allow connection initiation to be sensed in the absence of
|
|
tunnel data, since UDP is a "connectionless" protocol.</p>
|
|
<p class="last">On Windows, this option will delay the TAP-Win32 media state
|
|
transitioning to "connected" until connection establishment, i.e. the
|
|
receipt of the first authenticated packet from the peer.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--up-restart</span></kbd></td>
|
|
<td>Enable the <tt class="docutils literal"><span class="pre">--up</span></tt> and <tt class="docutils literal"><span class="pre">--down</span></tt> scripts to be called for restarts as
|
|
well as initial program start. This option is described more fully above
|
|
in the <tt class="docutils literal"><span class="pre">--up</span></tt> option documentation.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="string-types-and-remapping">
|
|
<h2>String Types and Remapping</h2>
|
|
<p>In certain cases, OpenVPN will perform remapping of characters in
|
|
strings. Essentially, any characters outside the set of permitted
|
|
characters for each string type will be converted to underbar ('_').</p>
|
|
<dl class="docutils">
|
|
<dt><em>Q: Why is string remapping necessary?</em></dt>
|
|
<dd>It's an important security feature to prevent the malicious
|
|
coding of strings from untrusted sources to be passed as parameters to
|
|
scripts, saved in the environment, used as a common name, translated to
|
|
a filename, etc.</dd>
|
|
<dt><em>Q: Can string remapping be disabled?</em></dt>
|
|
<dd>Yes, by using the <tt class="docutils literal"><span class="pre">--no-name-remapping</span></tt> option, however this
|
|
should be considered an advanced option.</dd>
|
|
</dl>
|
|
<p>Here is a brief rundown of OpenVPN's current string types and the
|
|
permitted character class for each string:</p>
|
|
<dl class="docutils">
|
|
<dt><em>X509 Names</em></dt>
|
|
<dd>Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), at
|
|
('@'), colon (':'), slash ('/'), and equal ('='). Alphanumeric is
|
|
defined as a character which will cause the C library isalnum() function
|
|
to return true.</dd>
|
|
<dt><em>Common Names</em></dt>
|
|
<dd>Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), and at ('@').</dd>
|
|
<dt><em>--auth-user-pass username</em></dt>
|
|
<dd>Same as Common Name, with one exception:
|
|
starting with OpenVPN 2.0.1, the username is passed to the
|
|
<code>OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY</code> plugin in its raw form,
|
|
without string remapping.</dd>
|
|
<dt><em>--auth-user-pass password</em></dt>
|
|
<dd>Any "printable" character except CR or LF. Printable is defined to be
|
|
a character which will cause the C library isprint() function to
|
|
return true.</dd>
|
|
<dt><em>--client-config-dir filename as derived from common name or`username</em></dt>
|
|
<dd>Alphanumeric, underbar ('_'), dash ('-'), and dot ('.') except for "."
|
|
or ".." as standalone strings. As of v2.0.1-rc6, the at ('@') character
|
|
has been added as well for compatibility with the common name character
|
|
class.</dd>
|
|
<dt><em>Environmental variable names</em></dt>
|
|
<dd>Alphanumeric or underbar ('_').</dd>
|
|
<dt><em>Environmental variable values</em></dt>
|
|
<dd>Any printable character.</dd>
|
|
</dl>
|
|
<p>For all cases, characters in a string which are not members of the legal
|
|
character class for that string type will be remapped to underbar
|
|
('_').</p>
|
|
</div>
|
|
<div class="section" id="environmental-variables">
|
|
<h2>Environmental Variables</h2>
|
|
<p>Once set, a variable is persisted indefinitely until it is reset by a
|
|
new value or a restart,</p>
|
|
<p>As of OpenVPN 2.0-beta12, in server mode, environmental variables set by
|
|
OpenVPN are scoped according to the client objects they are associated
|
|
with, so there should not be any issues with scripts having access to
|
|
stale, previously set variables which refer to different client
|
|
instances.</p>
|
|
<dl class="docutils">
|
|
<dt><code>bytes_received</code></dt>
|
|
<dd>Total number of bytes received from client during VPN session. Set prior
|
|
to execution of the <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> script.</dd>
|
|
<dt><code>bytes_sent</code></dt>
|
|
<dd>Total number of bytes sent to client during VPN session. Set prior to
|
|
execution of the <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> script.</dd>
|
|
<dt><code>client_connect_config_file</code></dt>
|
|
<dd>The path to the configuration file that should be written to by the
|
|
<tt class="docutils literal"><span class="pre">--client-connect</span></tt> script (optional, if per-session configuration
|
|
is desired). This is the same file name as passed via command line
|
|
argument on the call to the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</dd>
|
|
<dt><code>client_connect_deferred_file</code></dt>
|
|
<dd><p class="first">This file can be optionally written to in order to to communicate a
|
|
status code of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script or plgin. Only the
|
|
first character in the file is relevant. It must be either <code>1</code>
|
|
to indicate normal script execution, <code>0</code> indicates an error (in
|
|
the same way that a non zero exit status does) or <code>2</code> to indicate
|
|
that the script deferred returning the config file.</p>
|
|
<p>For deferred (background) handling, the script or plugin MUST write
|
|
<code>2</code> to the file to indicate the deferral and then return with
|
|
exit code <code>0</code> to signal <tt class="docutils literal">deferred handler started OK</tt>.</p>
|
|
<p>A background process or similar must then take care of writing the
|
|
configuration to the file indicated by the
|
|
<code>client_connect_config_file</code> environment variable and when
|
|
finished, write the a <code>1</code> to this file (or <code>0</code> in case of
|
|
an error).</p>
|
|
<p class="last">The absence of any character in the file when the script finishes
|
|
executing is interpreted the same as <code>1</code>. This allows scripts
|
|
that are not written to support the defer mechanism to be used
|
|
unmodified.</p>
|
|
</dd>
|
|
<dt><code>common_name</code></dt>
|
|
<dd>The X509 common name of an authenticated client. Set prior to execution
|
|
of <tt class="docutils literal"><span class="pre">--client-connect</span></tt>, <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> scripts.</dd>
|
|
<dt><code>config</code></dt>
|
|
<dd>Name of first <tt class="docutils literal"><span class="pre">--config</span></tt> file. Set on program initiation and reset on
|
|
SIGHUP.</dd>
|
|
<dt><code>daemon</code></dt>
|
|
<dd>Set to "1" if the <tt class="docutils literal"><span class="pre">--daemon</span></tt> directive is specified, or "0" otherwise.
|
|
Set on program initiation and reset on SIGHUP.</dd>
|
|
<dt><code>daemon_log_redirect</code></dt>
|
|
<dd>Set to "1" if the <tt class="docutils literal"><span class="pre">--log</span></tt> or <tt class="docutils literal"><span class="pre">--log-append</span></tt> directives are
|
|
specified, or "0" otherwise. Set on program initiation and reset on
|
|
SIGHUP.</dd>
|
|
<dt><code>dev</code></dt>
|
|
<dd>The actual name of the TUN/TAP device, including a unit number if it
|
|
exists. Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt> or <tt class="docutils literal"><span class="pre">--down</span></tt> script execution.</dd>
|
|
<dt><code>dev_idx</code></dt>
|
|
<dd>On Windows, the device index of the TUN/TAP adapter (to be used in
|
|
netsh.exe calls which sometimes just do not work right with interface
|
|
names). Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt> or <tt class="docutils literal"><span class="pre">--down</span></tt> script execution.</dd>
|
|
<dt><code>foreign_option_{n}</code></dt>
|
|
<dd>An option pushed via <tt class="docutils literal"><span class="pre">--push</span></tt> to a client which does not natively
|
|
support it, such as <tt class="docutils literal"><span class="pre">--dhcp-option</span></tt> on a non-Windows system, will be
|
|
recorded to this environmental variable sequence prior to <tt class="docutils literal"><span class="pre">--up</span></tt>
|
|
script execution.</dd>
|
|
<dt><code>ifconfig_broadcast</code></dt>
|
|
<dd>The broadcast address for the virtual ethernet segment which is derived
|
|
from the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> option when <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> is used. Set prior to
|
|
OpenVPN calling the <code>ifconfig</code> or <code>netsh</code> (windows version
|
|
of ifconfig) commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script
|
|
execution.</dd>
|
|
<dt><code>ifconfig_ipv6_local</code></dt>
|
|
<dd>The local VPN endpoint IPv6 address specified in the
|
|
<tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt> option (first parameter). Set prior to OpenVPN
|
|
calling the <code>ifconfig</code> or code:<cite>netsh</cite> (windows version of
|
|
ifconfig) commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script
|
|
execution.</dd>
|
|
<dt><code>ifconfig_ipv6_netbits</code></dt>
|
|
<dd>The prefix length of the IPv6 network on the VPN interface. Derived
|
|
from the /nnn parameter of the IPv6 address in the <tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt>
|
|
option (first parameter). Set prior to OpenVPN calling the
|
|
<code>ifconfig</code> or <code>netsh</code> (windows version of ifconfig)
|
|
commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</dd>
|
|
<dt><code>ifconfig_ipv6_remote</code></dt>
|
|
<dd>The remote VPN endpoint IPv6 address specified in the
|
|
<tt class="docutils literal"><span class="pre">--ifconfig-ipv6</span></tt> option (second parameter). Set prior to OpenVPN
|
|
calling the <code>ifconfig</code> or <code>netsh</code> (windows version of
|
|
ifconfig) commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script
|
|
execution.</dd>
|
|
<dt><code>ifconfig_local</code></dt>
|
|
<dd>The local VPN endpoint IP address specified in the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>
|
|
option (first parameter). Set prior to OpenVPN calling the
|
|
<code>ifconfig</code> or <code>netsh</code> (windows version of ifconfig)
|
|
commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</dd>
|
|
<dt><code>ifconfig_remote</code></dt>
|
|
<dd>The remote VPN endpoint IP address specified in the <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>
|
|
option (second parameter) when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is used. Set prior to
|
|
OpenVPN calling the <code>ifconfig</code> or <code>netsh</code> (windows version
|
|
of ifconfig) commands which normally occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script
|
|
execution.</dd>
|
|
<dt><code>ifconfig_netmask</code></dt>
|
|
<dd>The subnet mask of the virtual ethernet segment that is specified as
|
|
the second parameter to <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> when <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> is being
|
|
used. Set prior to OpenVPN calling the <code>ifconfig</code> or
|
|
<code>netsh</code> (windows version of ifconfig) commands which normally
|
|
occurs prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</dd>
|
|
<dt><code>ifconfig_pool_local_ip</code></dt>
|
|
<dd>The local virtual IP address for the TUN/TAP tunnel taken from an
|
|
<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt> directive if specified, or otherwise from the
|
|
ifconfig pool (controlled by the <tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> config file
|
|
directive). Only set for <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> tunnels. This option is set on
|
|
the server prior to execution of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts.</dd>
|
|
<dt><code>ifconfig_pool_netmask</code></dt>
|
|
<dd>The virtual IP netmask for the TUN/TAP tunnel taken from an
|
|
<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt> directive if specified, or otherwise from the
|
|
ifconfig pool (controlled by the <tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> config file
|
|
directive). Only set for <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> tunnels. This option is set on
|
|
the server prior to execution of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts.</dd>
|
|
<dt><code>ifconfig_pool_remote_ip</code></dt>
|
|
<dd>The remote virtual IP address for the TUN/TAP tunnel taken from an
|
|
<tt class="docutils literal"><span class="pre">--ifconfig-push</span></tt> directive if specified, or otherwise from the
|
|
ifconfig pool (controlled by the <tt class="docutils literal"><span class="pre">--ifconfig-pool</span></tt> config file
|
|
directive). This option is set on the server prior to execution of the
|
|
<tt class="docutils literal"><span class="pre">--client-connect</span></tt> and <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts.</dd>
|
|
<dt><code>link_mtu</code></dt>
|
|
<dd>The maximum packet size (not including the IP header) of tunnel data in
|
|
UDP tunnel transport mode. Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt> or <tt class="docutils literal"><span class="pre">--down</span></tt> script
|
|
execution.</dd>
|
|
<dt><code>local</code></dt>
|
|
<dd>The <tt class="docutils literal"><span class="pre">--local</span></tt> parameter. Set on program initiation and reset on
|
|
SIGHUP.</dd>
|
|
<dt><code>local_port</code></dt>
|
|
<dd>The local port number or name, specified by <tt class="docutils literal"><span class="pre">--port</span></tt> or <tt class="docutils literal"><span class="pre">--lport</span></tt>.
|
|
Set on program initiation and reset on SIGHUP.</dd>
|
|
<dt><code>password</code></dt>
|
|
<dd>The password provided by a connecting client. Set prior to
|
|
<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script execution only when the <tt class="docutils literal"><span class="pre">via-env</span></tt>
|
|
modifier is specified, and deleted from the environment after the script
|
|
returns.</dd>
|
|
<dt><code>proto</code></dt>
|
|
<dd>The <tt class="docutils literal"><span class="pre">--proto</span></tt> parameter. Set on program initiation and reset on
|
|
SIGHUP.</dd>
|
|
<dt><code>remote_{n}</code></dt>
|
|
<dd>The <tt class="docutils literal"><span class="pre">--remote</span></tt> parameter. Set on program initiation and reset on
|
|
SIGHUP.</dd>
|
|
<dt><code>remote_port_{n}</code></dt>
|
|
<dd>The remote port number, specified by <tt class="docutils literal"><span class="pre">--port</span></tt> or <tt class="docutils literal"><span class="pre">--rport</span></tt>. Set on
|
|
program initiation and reset on SIGHUP.</dd>
|
|
<dt><code>route_net_gateway</code></dt>
|
|
<dd>The pre-existing default IP gateway in the system routing table. Set
|
|
prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</dd>
|
|
<dt><code>route_vpn_gateway</code></dt>
|
|
<dd>The default gateway used by <tt class="docutils literal"><span class="pre">--route</span></tt> options, as specified in either
|
|
the <tt class="docutils literal"><span class="pre">--route-gateway</span></tt> option or the second parameter to
|
|
<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> when <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> is specified. Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt>
|
|
script execution.</dd>
|
|
<dt><code>route_{parm}_{n}</code></dt>
|
|
<dd><p class="first">A set of variables which define each route to be added, and are set
|
|
prior to <tt class="docutils literal"><span class="pre">--up</span></tt> script execution.</p>
|
|
<p><tt class="docutils literal">parm</tt> will be one of <code>network</code>, <code>netmask"</code>,
|
|
<code>gateway</code>, or <code>metric</code>.</p>
|
|
<p><tt class="docutils literal">n</tt> is the OpenVPN route number, starting from 1.</p>
|
|
<p class="last">If the network or gateway are resolvable DNS names, their IP address
|
|
translations will be recorded rather than their names as denoted on the
|
|
command line or configuration file.</p>
|
|
</dd>
|
|
<dt><code>route_ipv6_{parm}_{n}</code></dt>
|
|
<dd><p class="first">A set of variables which define each IPv6 route to be added, and are
|
|
set prior to <strong>--up</strong> script execution.</p>
|
|
<p><tt class="docutils literal">parm</tt> will be one of <code>network</code>, <code>gateway</code> or
|
|
<code>metric</code>. <tt class="docutils literal">route_ipv6_network_{n}</tt> contains <code>netmask</code>
|
|
as <code>/nnn</code>, unlike IPv4 where it is passed in a separate environment
|
|
variable.</p>
|
|
<p><tt class="docutils literal">n</tt> is the OpenVPN route number, starting from 1.</p>
|
|
<p class="last">If the network or gateway are resolvable DNS names, their IP address
|
|
translations will be recorded rather than their names as denoted on the
|
|
command line or configuration file.</p>
|
|
</dd>
|
|
<dt><code>peer_cert</code></dt>
|
|
<dd>Temporary file name containing the client certificate upon connection.
|
|
Useful in conjunction with <tt class="docutils literal"><span class="pre">--tls-verify</span></tt>.</dd>
|
|
<dt><code>script_context</code></dt>
|
|
<dd>Set to "init" or "restart" prior to up/down script execution. For more
|
|
information, see documentation for <tt class="docutils literal"><span class="pre">--up</span></tt>.</dd>
|
|
<dt><code>script_type</code></dt>
|
|
<dd>Prior to execution of any script, this variable is set to the type of
|
|
script being run. It can be one of the following: <code>up</code>,
|
|
<code>down</code>, <code>ipchange</code>, <code>route-up</code>, <code>tls-verify</code>,
|
|
<code>auth-user-pass-verify</code>, <code>client-connect</code>,
|
|
<code>client-disconnect</code> or <code>learn-address</code>. Set prior to
|
|
execution of any script.</dd>
|
|
<dt><code>signal</code></dt>
|
|
<dd>The reason for exit or restart. Can be one of <code>sigusr1</code>,
|
|
<code>sighup</code>, <code>sigterm</code>, <code>sigint</code>, <code>inactive</code>
|
|
(controlled by <tt class="docutils literal"><span class="pre">--inactive</span></tt> option), <code>ping-exit</code> (controlled
|
|
by <tt class="docutils literal"><span class="pre">--ping-exit</span></tt> option), <code>ping-restart</code> (controlled by
|
|
<tt class="docutils literal"><span class="pre">--ping-restart</span></tt> option), <code>connection-reset</code> (triggered on TCP
|
|
connection reset), <code>error</code> or <code>unknown</code> (unknown signal).
|
|
This variable is set just prior to down script execution.</dd>
|
|
<dt><code>time_ascii</code></dt>
|
|
<dd>Client connection timestamp, formatted as a human-readable time string.
|
|
Set prior to execution of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</dd>
|
|
<dt><code>time_duration</code></dt>
|
|
<dd>The duration (in seconds) of the client session which is now
|
|
disconnecting. Set prior to execution of the <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt>
|
|
script.</dd>
|
|
<dt><code>time_unix</code></dt>
|
|
<dd>Client connection timestamp, formatted as a unix integer date/time
|
|
value. Set prior to execution of the <tt class="docutils literal"><span class="pre">--client-connect</span></tt> script.</dd>
|
|
<dt><code>tls_digest_{n}</code> / <code>tls_digest_sha256_{n}</code></dt>
|
|
<dd>Contains the certificate SHA1 / SHA256 fingerprint, where <tt class="docutils literal">n</tt> is the
|
|
verification level. Only set for TLS connections. Set prior to execution
|
|
of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script.</dd>
|
|
<dt><code>tls_id_{n}</code></dt>
|
|
<dd>A series of certificate fields from the remote peer, where <tt class="docutils literal">n</tt> is the
|
|
verification level. Only set for TLS connections. Set prior to execution
|
|
of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script.</dd>
|
|
<dt><code>tls_serial_{n}</code></dt>
|
|
<dd>The serial number of the certificate from the remote peer, where <tt class="docutils literal">n</tt>
|
|
is the verification level. Only set for TLS connections. Set prior to
|
|
execution of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script. This is in the form of a decimal
|
|
string like "933971680", which is suitable for doing serial-based OCSP
|
|
queries (with OpenSSL, do not prepend "0x" to the string) If something
|
|
goes wrong while reading the value from the certificate it will be an
|
|
empty string, so your code should check that. See the
|
|
<code>contrib/OCSP_check/OCSP_check.sh</code> script for an example.</dd>
|
|
<dt><code>tls_serial_hex_{n}</code></dt>
|
|
<dd>Like <code>tls_serial_{n}</code>, but in hex form (e.g.
|
|
<code>12:34:56:78:9A</code>).</dd>
|
|
<dt><code>tun_mtu</code></dt>
|
|
<dd>The MTU of the TUN/TAP device. Set prior to <tt class="docutils literal"><span class="pre">--up</span></tt> or <tt class="docutils literal"><span class="pre">--down</span></tt>
|
|
script execution.</dd>
|
|
<dt><code>trusted_ip</code> / <code>trusted_ip6</code>)</dt>
|
|
<dd>Actual IP address of connecting client or peer which has been
|
|
authenticated. Set prior to execution of <tt class="docutils literal"><span class="pre">--ipchange</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--client-connect</span></tt> and <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts. If using ipv6
|
|
endpoints (udp6, tcp6), <code>trusted_ip6</code> will be set instead.</dd>
|
|
<dt><code>trusted_port</code></dt>
|
|
<dd>Actual port number of connecting client or peer which has been
|
|
authenticated. Set prior to execution of <tt class="docutils literal"><span class="pre">--ipchange</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--client-connect</span></tt> and <tt class="docutils literal"><span class="pre">--client-disconnect</span></tt> scripts.</dd>
|
|
<dt><code>untrusted_ip</code> / <code>untrusted_ip6</code></dt>
|
|
<dd>Actual IP address of connecting client or peer which has not been
|
|
authenticated yet. Sometimes used to <em>nmap</em> the connecting host in a
|
|
<tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script to ensure it is firewalled properly. Set prior
|
|
to execution of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> and <tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt>
|
|
scripts. If using ipv6 endpoints (udp6, tcp6), <code>untrusted_ip6</code>
|
|
will be set instead.</dd>
|
|
<dt><code>untrusted_port</code></dt>
|
|
<dd>Actual port number of connecting client or peer which has not been
|
|
authenticated yet. Set prior to execution of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> scripts.</dd>
|
|
<dt><code>username</code></dt>
|
|
<dd>The username provided by a connecting client. Set prior to
|
|
<tt class="docutils literal"><span class="pre">--auth-user-pass-verify</span></tt> script execution only when the
|
|
<code>via-env</code> modifier is specified.</dd>
|
|
<dt><code>X509_{n}_{subject_field}</code></dt>
|
|
<dd><p class="first">An X509 subject field from the remote peer certificate, where <tt class="docutils literal">n</tt> is
|
|
the verification level. Only set for TLS connections. Set prior to
|
|
execution of <tt class="docutils literal"><span class="pre">--tls-verify</span></tt> script. This variable is similar to
|
|
<code>tls_id_{n}</code> except the component X509 subject fields are broken
|
|
out, and no string remapping occurs on these field values (except for
|
|
remapping of control characters to "<code>_</code>"). For example, the
|
|
following variables would be set on the OpenVPN server using the sample
|
|
client certificate in sample-keys (client.crt). Note that the
|
|
verification level is 0 for the client certificate and 1 for the CA
|
|
certificate.</p>
|
|
<pre class="last literal-block">
|
|
X509_0_emailAddress=me@myhost.mydomain
|
|
X509_0_CN=Test-Client
|
|
X509_0_O=OpenVPN-TEST
|
|
X509_0_ST=NA
|
|
X509_0_C=KG
|
|
X509_1_emailAddress=me@myhost.mydomain
|
|
X509_1_O=OpenVPN-TEST
|
|
X509_1_L=BISHKEK
|
|
X509_1_ST=NA
|
|
X509_1_C=KG
|
|
</pre>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="section" id="management-interface-options">
|
|
<h2>Management Interface Options</h2>
|
|
<p>OpenVPN provides a feature rich socket based management interface for both
|
|
server and client mode operations.</p>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Enable a management server on a <tt class="docutils literal"><span class="pre">socket-name</span></tt> Unix socket on those
|
|
platforms supporting it, or on a designated TCP port.</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
management socket-name unix #
|
|
management socket-name unix pw-file # (recommended)
|
|
management IP port # (INSECURE)
|
|
management IP port pw-file #
|
|
</pre>
|
|
<p><tt class="docutils literal"><span class="pre">pw-file</span></tt>, if specified, is a password file where the password must
|
|
be on first line. Instead of a filename it can use the keyword stdin
|
|
which will prompt the user for a password to use when OpenVPN is
|
|
starting.</p>
|
|
<p>For unix sockets, the default behaviour is to create a unix domain
|
|
socket that may be connected to by any process. Use the
|
|
<tt class="docutils literal"><span class="pre">--management-client-user</span></tt> and <tt class="docutils literal"><span class="pre">--management-client-group</span></tt>
|
|
directives to restrict access.</p>
|
|
<p>The management interface provides a special mode where the TCP
|
|
management link can operate over the tunnel itself. To enable this mode,
|
|
set IP to <tt class="docutils literal">tunnel</tt>. Tunnel mode will cause the management interface to
|
|
listen for a TCP connection on the local VPN address of the TUN/TAP
|
|
interface.</p>
|
|
<p><strong>*BEWARE*</strong> of enabling the management interface over TCP. In these cases
|
|
you should <em>ALWAYS</em> make use of <tt class="docutils literal"><span class="pre">pw-file</span></tt> to password protect the
|
|
management interface. Any user who can connect to this TCP <tt class="docutils literal">IP:port</tt>
|
|
will be able to manage and control (and interfere with) the OpenVPN
|
|
process. It is also strongly recommended to set IP to 127.0.0.1
|
|
(localhost) to restrict accessibility of the management server to local
|
|
clients.</p>
|
|
<p>While the management port is designed for programmatic control of
|
|
OpenVPN by other applications, it is possible to telnet to the port,
|
|
using a telnet client in "raw" mode. Once connected, type <code>help</code>
|
|
for a list of commands.</p>
|
|
<p class="last">For detailed documentation on the management interface, see the
|
|
<em>management-notes.txt</em> file in the management folder of the OpenVPN
|
|
source distribution.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-client</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Management interface will connect as a TCP/unix domain client to
|
|
<tt class="docutils literal">IP:port</tt> specified by <tt class="docutils literal"><span class="pre">--management</span></tt> rather than listen as a TCP
|
|
server or on a unix domain socket.</p>
|
|
<p class="last">If the client connection fails to connect or is disconnected, a SIGTERM
|
|
signal will be generated causing OpenVPN to quit.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-client-auth</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Gives management interface client the responsibility to authenticate
|
|
clients after their client certificate has been verified. See
|
|
<code>management-notes.txt</code> in OpenVPN distribution for detailed notes.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-client-group <var>g</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>When the management interface is listening on a unix domain socket, only
|
|
allow connections from group <tt class="docutils literal">g</tt>.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-client-pf</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Management interface clients must specify a packet filter file for each
|
|
connecting client. See <code>management-notes.txt</code> in OpenVPN
|
|
distribution for detailed notes.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-client-user <var>u</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>When the management interface is listening on a unix domain socket, only
|
|
allow connections from user <tt class="docutils literal">u</tt>.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-external-cert <var>certificate-hint</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Allows usage for external certificate instead of <tt class="docutils literal"><span class="pre">--cert</span></tt> option
|
|
(client-only). <tt class="docutils literal"><span class="pre">certificate-hint</span></tt> is an arbitrary string which is
|
|
passed to a management interface client as an argument of
|
|
<em>NEED-CERTIFICATE</em> notification. Requires <tt class="docutils literal"><span class="pre">--management-external-key</span></tt>.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-external-key <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Allows usage for external private key file instead of <tt class="docutils literal"><span class="pre">--key</span></tt> option
|
|
(client-only).</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
management-external-key
|
|
management-external-key nopadding
|
|
management-external-key pkcs1
|
|
management-external-key nopadding pkcs1
|
|
</pre>
|
|
<p class="last">The optional parameters <code>nopadding</code> and <code>pkcs1</code> signal
|
|
support for different padding algorithms. See
|
|
<code>doc/mangement-notes.txt</code> for a complete description of this
|
|
feature.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-forget-disconnect</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Make OpenVPN forget passwords when management session disconnects.</p>
|
|
<p class="last">This directive does not affect the <tt class="docutils literal"><span class="pre">--http-proxy</span></tt> username/password.
|
|
It is always cached.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-hold</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Start OpenVPN in a hibernating state, until a client of the management
|
|
interface explicitly starts it with the <code>hold release</code> command.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-log-cache <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Cache the most recent <tt class="docutils literal">n</tt> lines of log file history for usage by the
|
|
management channel.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-query-passwords</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Query management channel for private key password and
|
|
<tt class="docutils literal"><span class="pre">--auth-user-pass</span></tt> username/password. Only query the management
|
|
channel for inputs which ordinarily would have been queried from the
|
|
console.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-query-proxy</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Query management channel for proxy server information for a specific
|
|
<tt class="docutils literal"><span class="pre">--remote</span></tt> (client-only).</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-query-remote</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Allow management interface to override <tt class="docutils literal"><span class="pre">--remote</span></tt> directives
|
|
(client-only).</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-signal</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Send SIGUSR1 signal to OpenVPN if management session disconnects. This
|
|
is useful when you wish to disconnect an OpenVPN session on user logoff.
|
|
For <tt class="docutils literal"><span class="pre">--management-client</span></tt> this option is not needed since a disconnect
|
|
will always generate a <code>SIGTERM</code>.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--management-up-down</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Report tunnel up/down events to management interface.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="plug-in-interface-options">
|
|
<h2>Plug-in Interface Options</h2>
|
|
<p>OpenVPN can be extended by loading external plug-in modules at runtime. These
|
|
plug-ins must be prebuilt and adhere to the OpenVPN Plug-In API.</p>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--plugin <var>args</var></span></kbd></td>
|
|
<td><p class="first">Loads an OpenVPN plug-in module.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
plugin module-name
|
|
plugin module-name "arguments"
|
|
</pre>
|
|
<p>The <tt class="docutils literal"><span class="pre">module-name</span></tt> needs to be the first
|
|
argument, indicating the plug-in to load. The second argument is an
|
|
optional init string which will be passed directly to the plug-in.
|
|
If the init consists of multiple arguments it must be enclosed in
|
|
double-quotes ("). Multiple plugin modules may be loaded into one
|
|
OpenVPN process.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">module-name</span></tt> argument can be just a filename or a filename
|
|
with a relative or absolute path. The format of the filename and path
|
|
defines if the plug-in will be loaded from a default plug-in directory
|
|
or outside this directory.</p>
|
|
<pre class="literal-block">
|
|
--plugin path Effective directory used
|
|
===================== =============================
|
|
myplug.so DEFAULT_DIR/myplug.so
|
|
subdir/myplug.so DEFAULT_DIR/subdir/myplug.so
|
|
./subdir/myplug.so CWD/subdir/myplug.so
|
|
/usr/lib/my/plug.so /usr/lib/my/plug.so
|
|
</pre>
|
|
<p><tt class="docutils literal">DEFAULT_DIR</tt> is replaced by the default plug-in directory, which is
|
|
configured at the build time of OpenVPN. <tt class="docutils literal">CWD</tt> is the current directory
|
|
where OpenVPN was started or the directory OpenVPN have switched into
|
|
via the <tt class="docutils literal"><span class="pre">--cd</span></tt> option before the <tt class="docutils literal"><span class="pre">--plugin</span></tt> option.</p>
|
|
<p>For more information and examples on how to build OpenVPN plug-in
|
|
modules, see the README file in the <tt class="docutils literal">plugin</tt> folder of the OpenVPN
|
|
source distribution.</p>
|
|
<p>If you are using an RPM install of OpenVPN, see
|
|
<code>/usr/share/openvpn/plugin</code>. The documentation is in <tt class="docutils literal">doc</tt> and
|
|
the actual plugin modules are in <tt class="docutils literal">lib</tt>.</p>
|
|
<p class="last">Multiple plugin modules can be cascaded, and modules can be used in
|
|
tandem with scripts. The modules will be called by OpenVPN in the order
|
|
that they are declared in the config file. If both a plugin and script
|
|
are configured for the same callback, the script will be called last. If
|
|
the return code of the module/script controls an authentication function
|
|
(such as tls-verify, auth-user-pass-verify, or client-connect), then
|
|
every module and script must return success (<code>0</code>) in order for the
|
|
connection to be authenticated.</p>
|
|
</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="windows-specific-options">
|
|
<h2>Windows-Specific Options</h2>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--allow-nonadmin <var>TAP-adapter</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>(Standalone) Set <tt class="docutils literal"><span class="pre">TAP-adapter</span></tt> to allow access from non-administrative
|
|
accounts. If <tt class="docutils literal"><span class="pre">TAP-adapter</span></tt> is omitted, all TAP adapters on the system
|
|
will be configured to allow non-admin access. The non-admin access
|
|
setting will only persist for the length of time that the TAP-Win32
|
|
device object and driver remain loaded, and will need to be re-enabled
|
|
after a reboot, or if the driver is unloaded and reloaded. This
|
|
directive can only be used by an administrator.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--block-outside-dns</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Block DNS servers on other network adapters to prevent DNS leaks. This
|
|
option prevents any application from accessing TCP or UDP port 53 except
|
|
one inside the tunnel. It uses Windows Filtering Platform (WFP) and
|
|
works on Windows Vista or later.</p>
|
|
<p class="last">This option is considered unknown on non-Windows platforms and
|
|
unsupported on Windows XP, resulting in fatal error. You may want to use
|
|
<tt class="docutils literal"><span class="pre">--setenv</span> opt</tt> or <tt class="docutils literal"><span class="pre">--ignore-unknown-option</span></tt> (not suitable for
|
|
Windows XP) to ignore said error. Note that pushing unknown options from
|
|
server does not trigger fatal errors.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--cryptoapicert <var>select-string</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first"><em>(Windows/OpenSSL Only)</em> Load the certificate and private key from the
|
|
Windows Certificate System Store.</p>
|
|
<p>Use this option instead of <tt class="docutils literal"><span class="pre">--cert</span></tt> and <tt class="docutils literal"><span class="pre">--key</span></tt>.</p>
|
|
<p>This makes it possible to use any smart card, supported by Windows, but
|
|
also any kind of certificate, residing in the Cert Store, where you have
|
|
access to the private key. This option has been tested with a couple of
|
|
different smart cards (GemSAFE, Cryptoflex, and Swedish Post Office eID)
|
|
on the client side, and also an imported PKCS12 software certificate on
|
|
the server side.</p>
|
|
<p>To select a certificate, based on a substring search in the
|
|
certificate's subject:</p>
|
|
<pre class="literal-block">
|
|
cryptoapicert "SUBJ:Peter Runestig"
|
|
</pre>
|
|
<p>To select a certificate, based on certificate's thumbprint:</p>
|
|
<pre class="literal-block">
|
|
cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."
|
|
</pre>
|
|
<p class="last">The thumbprint hex string can easily be copy-and-pasted from the Windows
|
|
Certificate Store GUI.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--dhcp-release</span></kbd></td>
|
|
<td>Ask Windows to release the TAP adapter lease on shutdown. This option
|
|
has no effect now, as it is enabled by default starting with
|
|
OpenVPN 2.4.1.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--dhcp-renew</span></kbd></td>
|
|
<td>Ask Windows to renew the TAP adapter lease on startup. This option is
|
|
normally unnecessary, as Windows automatically triggers a DHCP
|
|
renegotiation on the TAP adapter when it comes up, however if you set
|
|
the TAP-Win32 adapter Media Status property to "Always Connected", you
|
|
may need this flag.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ip-win32 <var>method</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">When using <tt class="docutils literal"><span class="pre">--ifconfig</span></tt> on Windows, set the TAP-Win32 adapter IP
|
|
address and netmask using <tt class="docutils literal">method</tt>. Don't use this option unless you
|
|
are also using <tt class="docutils literal"><span class="pre">--ifconfig</span></tt>.</p>
|
|
<dl class="last docutils">
|
|
<dt><code>manual</code></dt>
|
|
<dd>Don't set the IP address or netmask automatically. Instead
|
|
output a message to the console telling the user to configure the
|
|
adapter manually and indicating the IP/netmask which OpenVPN
|
|
expects the adapter to be set to.</dd>
|
|
<dt><code>dynamic [offset] [lease-time]</code></dt>
|
|
<dd><p class="first">Automatically set the IP address and netmask by replying to DHCP
|
|
query messages generated by the kernel. This mode is probably the
|
|
"cleanest" solution for setting the TCP/IP properties since it
|
|
uses the well-known DHCP protocol. There are, however, two
|
|
prerequisites for using this mode:</p>
|
|
<ol class="arabic simple">
|
|
<li>The TCP/IP properties for the TAP-Win32 adapter must be set
|
|
to "Obtain an IP address automatically", and</li>
|
|
<li>OpenVPN needs to claim an IP address in the subnet for use
|
|
as the virtual DHCP server address.</li>
|
|
</ol>
|
|
<p>By default in <tt class="docutils literal"><span class="pre">--dev</span> tap</tt> mode, OpenVPN will take the normally
|
|
unused first address in the subnet. For example, if your subnet is
|
|
<code>192.168.4.0 netmask 255.255.255.0</code>, then OpenVPN will take
|
|
the IP address <code>192.168.4.0</code> to use as the virtual DHCP
|
|
server address. In <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> mode, OpenVPN will cause the DHCP
|
|
server to masquerade as if it were coming from the remote endpoint.</p>
|
|
<p>The optional offset parameter is an integer which is > <code>-256</code>
|
|
and < <code>256</code> and which defaults to 0. If offset is positive,
|
|
the DHCP server will masquerade as the IP address at network
|
|
address + offset. If offset is negative, the DHCP server will
|
|
masquerade as the IP address at broadcast address + offset.</p>
|
|
<p>The Windows <code>ipconfig /all</code> command can be used to show what
|
|
Windows thinks the DHCP server address is. OpenVPN will "claim"
|
|
this address, so make sure to use a free address. Having said that,
|
|
different OpenVPN instantiations, including different ends of
|
|
the same connection, can share the same virtual DHCP server
|
|
address.</p>
|
|
<p class="last">The <tt class="docutils literal"><span class="pre">lease-time</span></tt> parameter controls the lease time of the DHCP
|
|
assignment given to the TAP-Win32 adapter, and is denoted in
|
|
seconds. Normally a very long lease time is preferred because it
|
|
prevents routes involving the TAP-Win32 adapter from being lost
|
|
when the system goes to sleep. The default lease time is one year.</p>
|
|
</dd>
|
|
<dt><code>netsh</code></dt>
|
|
<dd>Automatically set the IP address and netmask using the Windows
|
|
command-line "netsh" command. This method appears to work correctly
|
|
on Windows XP but not Windows 2000.</dd>
|
|
<dt><code>ipapi</code></dt>
|
|
<dd>Automatically set the IP address and netmask using the Windows IP
|
|
Helper API. This approach does not have ideal semantics, though
|
|
testing has indicated that it works okay in practice. If you use
|
|
this option, it is best to leave the TCP/IP properties for the
|
|
TAP-Win32 adapter in their default state, i.e. "Obtain an IP
|
|
address automatically."</dd>
|
|
<dt><code>adaptive</code> (Default)</dt>
|
|
<dd><p class="first">Try <code>dynamic</code> method initially and fail over to <code>netsh</code>
|
|
if the DHCP negotiation with the TAP-Win32 adapter does not succeed
|
|
in 20 seconds. Such failures have been known to occur when certain
|
|
third-party firewall packages installed on the client machine block
|
|
the DHCP negotiation used by the TAP-Win32 adapter. Note that if
|
|
the <code>netsh</code> failover occurs, the TAP-Win32 adapter TCP/IP
|
|
properties will be reset from DHCP to static, and this will cause
|
|
future OpenVPN startups using the <code>adaptive</code> mode to use
|
|
<code>netsh</code> immediately, rather than trying <code>dynamic</code> first.</p>
|
|
<p class="last">To "unstick" the <code>adaptive</code> mode from using <code>netsh</code>,
|
|
run OpenVPN at least once using the <code>dynamic</code> mode to restore
|
|
the TAP-Win32 adapter TCP/IP properties to a DHCP configuration.</p>
|
|
</dd>
|
|
</dl>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--pause-exit</span></kbd></td>
|
|
<td>Put up a "press any key to continue" message on the console prior to
|
|
OpenVPN program exit. This option is automatically used by the Windows
|
|
explorer when OpenVPN is run on a configuration file using the
|
|
right-click explorer menu.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--register-dns</span></kbd></td>
|
|
<td>Run <code>ipconfig /flushdns</code> and <code>ipconfig /registerdns</code> on
|
|
connection initiation. This is known to kick Windows into recognizing
|
|
pushed DNS servers.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--route-method <var>m</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Which method <tt class="docutils literal">m</tt> to use for adding routes on Windows?</p>
|
|
<dl class="last docutils">
|
|
<dt><code>adaptive</code> (default)</dt>
|
|
<dd>Try IP helper API first. If that fails, fall back to the route.exe
|
|
shell command.</dd>
|
|
<dt><code>ipapi</code></dt>
|
|
<dd>Use IP helper API.</dd>
|
|
<dt><code>exe</code></dt>
|
|
<dd>Call the route.exe shell command.</dd>
|
|
</dl>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--service <var>args</var></span></kbd></td>
|
|
<td><p class="first">Should be used when OpenVPN is being automatically executed by another
|
|
program in such a context that no interaction with the user via display
|
|
or keyboard is possible.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
service exit-event [0|1]
|
|
</pre>
|
|
<p>In general, end-users should never need to explicitly use this option,
|
|
as it is automatically added by the OpenVPN service wrapper when a given
|
|
OpenVPN configuration is being run as a service.</p>
|
|
<p><tt class="docutils literal"><span class="pre">exit-event</span></tt> is the name of a Windows global event object, and OpenVPN
|
|
will continuously monitor the state of this event object and exit when
|
|
it becomes signaled.</p>
|
|
<p>The second parameter indicates the initial state of <tt class="docutils literal"><span class="pre">exit-event</span></tt> and
|
|
normally defaults to 0.</p>
|
|
<p>Multiple OpenVPN processes can be simultaneously executed with the same
|
|
<tt class="docutils literal"><span class="pre">exit-event</span></tt> parameter. In any case, the controlling process can
|
|
signal <tt class="docutils literal"><span class="pre">exit-event</span></tt>, causing all such OpenVPN processes to exit.</p>
|
|
<p class="last">When executing an OpenVPN process using the <tt class="docutils literal"><span class="pre">--service</span></tt> directive,
|
|
OpenVPN will probably not have a console window to output status/error
|
|
messages, therefore it is useful to use <tt class="docutils literal"><span class="pre">--log</span></tt> or <tt class="docutils literal"><span class="pre">--log-append</span></tt> to
|
|
write these messages to a file.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--show-adapters</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>(Standalone) Show available TAP-Win32 adapters which can be selected
|
|
using the <tt class="docutils literal"><span class="pre">--dev-node</span></tt> option. On non-Windows systems, the
|
|
<tt class="docutils literal">ifconfig</tt>(8) command provides similar functionality.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--show-net</span></kbd></td>
|
|
<td>(Standalone) Show OpenVPN's view of the system routing table and network
|
|
adapter list.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--show-net-up</span></kbd></td>
|
|
<td>Output OpenVPN's view of the system routing table and network adapter
|
|
list to the syslog or log file after the TUN/TAP adapter has been
|
|
brought up and any routes have been added.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--show-valid-subnets</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">(Standalone) Show valid subnets for <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> emulation. Since the
|
|
TAP-Win32 driver exports an ethernet interface to Windows, and since TUN
|
|
devices are point-to-point in nature, it is necessary for the TAP-Win32
|
|
driver to impose certain constraints on TUN endpoint address selection.</p>
|
|
<p class="last">Namely, the point-to-point endpoints used in TUN device emulation must
|
|
be the middle two addresses of a /30 subnet (netmask 255.255.255.252).</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--tap-sleep <var>n</var></span></kbd></td>
|
|
<td><p class="first">Cause OpenVPN to sleep for <tt class="docutils literal">n</tt> seconds immediately after the TAP-Win32
|
|
adapter state is set to "connected".</p>
|
|
<p class="last">This option is intended to be used to troubleshoot problems with the
|
|
<tt class="docutils literal"><span class="pre">--ifconfig</span></tt> and <tt class="docutils literal"><span class="pre">--ip-win32</span></tt> options, and is used to give the
|
|
TAP-Win32 adapter time to come up before Windows IP Helper API
|
|
operations are applied to it.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--win-sys <var>path</var></span></kbd></td>
|
|
<td><p class="first">Set the Windows system directory pathname to use when looking for system
|
|
executables such as <tt class="docutils literal">route.exe</tt> and <tt class="docutils literal">netsh.exe</tt>. By default, if this
|
|
directive is not specified, OpenVPN will use the SystemRoot environment
|
|
variable.</p>
|
|
<p class="last">This option has changed behaviour since OpenVPN 2.3. Earlier you had to
|
|
define <tt class="docutils literal"><span class="pre">--win-sys</span> env</tt> to use the SystemRoot environment variable,
|
|
otherwise it defaulted to <code>C:\\WINDOWS</code>. It is not needed to use
|
|
the <tt class="docutils literal">env</tt> keyword any more, and it will just be ignored. A warning is
|
|
logged when this is found in the configuration file.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--windows-driver <var>drv</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Specifies which tun driver to use. Values are <code>tap-windows6</code>
|
|
(default) and <code>wintun</code>. This is a Windows-only option.
|
|
<code>wintun</code>" requires <tt class="docutils literal"><span class="pre">--dev</span> tun</tt> and the OpenVPN process to run
|
|
elevated, or be invoked using the Interactive Service.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="standalone-debug-options">
|
|
<h2>Standalone Debug Options</h2>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--show-gateway <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">(Standalone) Show current IPv4 and IPv6 default gateway and interface
|
|
towards the gateway (if the protocol in question is enabled).</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
--show-gateway
|
|
--show-gateway IPv6-target
|
|
</pre>
|
|
<p class="last">For IPv6 this queries the route towards ::/128, or the specified IPv6
|
|
target address if passed as argument.
|
|
For IPv4 on Linux, Windows, MacOS and BSD it looks for a 0.0.0.0/0 route.
|
|
If there are more specific routes, the result will not always be matching
|
|
the route of the IPv4 packets to the VPN gateway.</p>
|
|
</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="advanced-expert-options">
|
|
<h2>Advanced Expert Options</h2>
|
|
<p>These are options only required when special tweaking is needed, often
|
|
used when debugging or testing out special usage scenarios.</p>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--hash-size <var>args</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Set the size of the real address hash table to <tt class="docutils literal">r</tt> and the virtual
|
|
address table to <tt class="docutils literal">v</tt>.</p>
|
|
<p>Valid syntax:</p>
|
|
<pre class="literal-block">
|
|
hash-size r v
|
|
</pre>
|
|
<p class="last">By default, both tables are sized at 256 buckets.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--bcast-buffers <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Allocate <tt class="docutils literal">n</tt> buffers for broadcast datagrams (default <code>256</code>).</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--persist-local-ip</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Preserve initially resolved local IP address and port number across
|
|
<tt class="docutils literal">SIGUSR1</tt> or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> restarts.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--persist-remote-ip</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Preserve most recently authenticated remote IP address and port number
|
|
across <code>SIGUSR1</code> or <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> restarts.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--prng <var>args</var></span></kbd></td>
|
|
<td><p class="first"><em>(Advanced)</em> Change the PRNG (Pseudo-random number generator) parameters</p>
|
|
<p>Valid syntaxes:</p>
|
|
<pre class="literal-block">
|
|
prng alg
|
|
prng alg nsl
|
|
</pre>
|
|
<p>Changes the PRNG to use digest algorithm <strong>alg</strong> (default <code>sha1</code>),
|
|
and set <tt class="docutils literal">nsl</tt> (default <code>16</code>) to the size in bytes of the nonce
|
|
secret length (between 16 and 64).</p>
|
|
<p class="last">Set <tt class="docutils literal">alg</tt> to <code>none</code> to disable the PRNG and use the OpenSSL
|
|
RAND_bytes function instead for all of OpenVPN's pseudo-random number
|
|
needs.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--rcvbuf <var>size</var></span></kbd></td>
|
|
<td>Set the TCP/UDP socket receive buffer size. Defaults to operating system
|
|
default.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--shaper <var>n</var></span></kbd></td>
|
|
<td><p class="first">Limit bandwidth of outgoing tunnel data to <tt class="docutils literal">n</tt> bytes per second on the
|
|
TCP/UDP port. Note that this will only work if mode is set to
|
|
<code>p2p</code>. If you want to limit the bandwidth in both directions, use
|
|
this option on both peers.</p>
|
|
<p>OpenVPN uses the following algorithm to implement traffic shaping: Given
|
|
a shaper rate of <tt class="docutils literal">n</tt> bytes per second, after a datagram write of <tt class="docutils literal">b</tt>
|
|
bytes is queued on the TCP/UDP port, wait a minimum of <tt class="docutils literal">(b / n)</tt>
|
|
seconds before queuing the next write.</p>
|
|
<p>It should be noted that OpenVPN supports multiple tunnels between the
|
|
same two peers, allowing you to construct full-speed and reduced
|
|
bandwidth tunnels at the same time, routing low-priority data such as
|
|
off-site backups over the reduced bandwidth tunnel, and other data over
|
|
the full-speed tunnel.</p>
|
|
<p>Also note that for low bandwidth tunnels (under 1000 bytes per second),
|
|
you should probably use lower MTU values as well (see above), otherwise
|
|
the packet latency will grow so large as to trigger timeouts in the TLS
|
|
layer and TCP connections running over the tunnel.</p>
|
|
<p class="last">OpenVPN allows <tt class="docutils literal">n</tt> to be between 100 bytes/sec and 100 Mbytes/sec.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--sndbuf <var>size</var></span></kbd></td>
|
|
<td>Set the TCP/UDP socket send buffer size. Defaults to operating system
|
|
default.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--tcp-queue-limit <var>n</var></span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td><p class="first">Maximum number of output packets queued before TCP (default <code>64</code>).</p>
|
|
<p class="last">When OpenVPN is tunneling data from a TUN/TAP device to a remote client
|
|
over a TCP connection, it is possible that the TUN/TAP device might
|
|
produce data at a faster rate than the TCP connection can support. When
|
|
the number of output packets queued before sending to the TCP socket
|
|
reaches this limit for a given client connection, OpenVPN will start to
|
|
drop outgoing packets directed at this client.</p>
|
|
</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--txqueuelen <var>n</var></span></kbd></td>
|
|
<td><em>(Linux only)</em> Set the TX queue length on the TUN/TAP interface.
|
|
Currently defaults to operating system default.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="unsupported-options">
|
|
<h1>UNSUPPORTED OPTIONS</h1>
|
|
<p>Options listed in this section have been removed from OpenVPN and are no
|
|
longer supported</p>
|
|
<table class="docutils option-list" frame="void" rules="none">
|
|
<col class="option" />
|
|
<col class="description" />
|
|
<tbody valign="top">
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--client-cert-not-required</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Removed in OpenVPN 2.5. This should be replaxed with
|
|
<tt class="docutils literal"><span class="pre">--verify-client-cert</span> none</tt>.</td></tr>
|
|
<tr><td class="option-group" colspan="2">
|
|
<kbd><span class="option">--ifconfig-pool-linear</span></kbd></td>
|
|
</tr>
|
|
<tr><td> </td><td>Removed in OpenVPN 2.5. This should be replaced with <tt class="docutils literal"><span class="pre">--topology</span> p2p</tt>.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--key-method</span></kbd></td>
|
|
<td>Removed in OpenVPN 2.5. This option should not be used, as using the old
|
|
<tt class="docutils literal"><span class="pre">key-method</span></tt> weakens the VPN tunnel security. The old <tt class="docutils literal"><span class="pre">key-method</span></tt>
|
|
was also only needed when the remote side was older than OpenVPN 2.0.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--no-iv</span></kbd></td>
|
|
<td>Removed in OpenVPN 2.5. This option should not be used as it weakens the
|
|
VPN tunnel security. This has been a NOOP option since OpenVPN 2.4.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--no-replay</span></kbd></td>
|
|
<td>Removed in OpenVPN 2.5. This option should not be used as it weakens the
|
|
VPN tunnel security.</td></tr>
|
|
<tr><td class="option-group">
|
|
<kbd><span class="option">--ns-cert-type</span></kbd></td>
|
|
<td>Removed in OpenVPN 2.5. The <tt class="docutils literal">nsCertType</tt> field is no longer supported
|
|
in recent SSL/TLS libraries. If your certificates does not include <em>key
|
|
usage</em> and <em>extended key usage</em> fields, they must be upgraded and the
|
|
<tt class="docutils literal"><span class="pre">--remote-cert-tls</span></tt> option should be used instead.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="connection-profiles">
|
|
<h1>CONNECTION PROFILES</h1>
|
|
<p>Client configuration files may contain multiple remote servers which
|
|
it will attempt to connect against. But there are some configuration
|
|
options which are related to specific <tt class="docutils literal"><span class="pre">--remote</span></tt> options. For these
|
|
use cases, connection profiles are the solution.</p>
|
|
<p>By enacpulating the <tt class="docutils literal"><span class="pre">--remote</span></tt> option and related options within
|
|
<tt class="docutils literal"><connection></tt> and <tt class="docutils literal"></connection></tt>, these options are handled as a
|
|
group.</p>
|
|
<p>An OpenVPN client will try each connection profile sequentially until it
|
|
achieves a successful connection.</p>
|
|
<p><tt class="docutils literal"><span class="pre">--remote-random</span></tt> can be used to initially "scramble" the connection
|
|
list.</p>
|
|
<p>Here is an example of connection profile usage:</p>
|
|
<pre class="literal-block">
|
|
client
|
|
dev tun
|
|
|
|
<connection>
|
|
remote 198.19.34.56 1194 udp
|
|
</connection>
|
|
|
|
<connection>
|
|
remote 198.19.34.56 443 tcp
|
|
</connection>
|
|
|
|
<connection>
|
|
remote 198.19.34.56 443 tcp
|
|
http-proxy 192.168.0.8 8080
|
|
</connection>
|
|
|
|
<connection>
|
|
remote 198.19.36.99 443 tcp
|
|
http-proxy 192.168.0.8 8080
|
|
</connection>
|
|
|
|
persist-key
|
|
persist-tun
|
|
pkcs12 client.p12
|
|
remote-cert-tls server
|
|
verb 3
|
|
</pre>
|
|
<p>First we try to connect to a server at 198.19.34.56:1194 using UDP. If
|
|
that fails, we then try to connect to 198.19.34.56:443 using TCP. If
|
|
that also fails, then try connecting through an HTTP proxy at
|
|
192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to connect
|
|
through the same proxy to a server at 198.19.36.99:443 using TCP.</p>
|
|
<p>The following OpenVPN options may be used inside of a <tt class="docutils literal"><connection></tt>
|
|
block:</p>
|
|
<p><tt class="docutils literal">bind</tt>, <tt class="docutils literal"><span class="pre">connect-retry</span></tt>, <tt class="docutils literal"><span class="pre">connect-retry-max</span></tt>, <tt class="docutils literal"><span class="pre">connect-timeout</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">explicit-exit-notify</span></tt>, <tt class="docutils literal">float</tt>, <tt class="docutils literal">fragment</tt>, <tt class="docutils literal"><span class="pre">http-proxy</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">http-proxy-option</span></tt>, <tt class="docutils literal"><span class="pre">key-direction</span></tt>, <tt class="docutils literal"><span class="pre">link-mtu</span></tt>, <tt class="docutils literal">local</tt>,
|
|
<tt class="docutils literal">lport</tt>, <tt class="docutils literal">mssfix</tt>, <tt class="docutils literal"><span class="pre">mtu-disc</span></tt>, <tt class="docutils literal">nobind</tt>, <tt class="docutils literal">port</tt>, <tt class="docutils literal">proto</tt>,
|
|
<tt class="docutils literal">remote</tt>, <tt class="docutils literal">rport</tt>, <tt class="docutils literal"><span class="pre">socks-proxy</span></tt>, <tt class="docutils literal"><span class="pre">tls-auth</span></tt>, <tt class="docutils literal"><span class="pre">tls-crypt</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">tun-mtu</span> and</tt>, <tt class="docutils literal"><span class="pre">tun-mtu-extra</span></tt>.</p>
|
|
<p>A defaulting mechanism exists for specifying options to apply to all
|
|
<tt class="docutils literal"><connection></tt> profiles. If any of the above options (with the
|
|
exception of <tt class="docutils literal">remote</tt> ) appear outside of a <tt class="docutils literal"><connection></tt> block,
|
|
but in a configuration file which has one or more <tt class="docutils literal"><connection></tt>
|
|
blocks, the option setting will be used as a default for
|
|
<tt class="docutils literal"><connection></tt> blocks which follow it in the configuration file.</p>
|
|
<p>For example, suppose the <tt class="docutils literal">nobind</tt> option were placed in the sample
|
|
configuration file above, near the top of the file, before the first
|
|
<tt class="docutils literal"><connection></tt> block. The effect would be as if <tt class="docutils literal">nobind</tt> were
|
|
declared in all <tt class="docutils literal"><connection></tt> blocks below it.</p>
|
|
</div>
|
|
<div class="section" id="inline-file-support">
|
|
<h1>INLINE FILE SUPPORT</h1>
|
|
<p>OpenVPN allows including files in the main configuration for the <tt class="docutils literal"><span class="pre">--ca</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--cert</span></tt>, <tt class="docutils literal"><span class="pre">--dh</span></tt>, <tt class="docutils literal"><span class="pre">--extra-certs</span></tt>, <tt class="docutils literal"><span class="pre">--key</span></tt>, <tt class="docutils literal"><span class="pre">--pkcs12</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--secret</span></tt>, <tt class="docutils literal"><span class="pre">--crl-verify</span></tt>, <tt class="docutils literal"><span class="pre">--http-proxy-user-pass</span></tt>, <tt class="docutils literal"><span class="pre">--tls-auth</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--auth-gen-token-secret</span></tt>, <tt class="docutils literal"><span class="pre">--tls-crypt</span></tt> and <tt class="docutils literal"><span class="pre">--tls-crypt-v2</span></tt>
|
|
options.</p>
|
|
<p>Each inline file started by the line <tt class="docutils literal"><option></tt> and ended by the line
|
|
<tt class="docutils literal"></option></tt></p>
|
|
<p>Here is an example of an inline file usage</p>
|
|
<pre class="literal-block">
|
|
<cert>
|
|
-----BEGIN CERTIFICATE-----
|
|
[...]
|
|
-----END CERTIFICATE-----
|
|
</cert>
|
|
</pre>
|
|
<p>When using the inline file feature with <tt class="docutils literal"><span class="pre">--pkcs12</span></tt> the inline file has
|
|
to be base64 encoded. Encoding of a .p12 file into base64 can be done
|
|
for example with OpenSSL by running <code>openssl base64 -in input.p12</code></p>
|
|
</div>
|
|
<div class="section" id="signals">
|
|
<h1>SIGNALS</h1>
|
|
<dl class="docutils">
|
|
<dt><code>SIGHUP</code></dt>
|
|
<dd>Cause OpenVPN to close all TUN/TAP and network connections, restart,
|
|
re-read the configuration file (if any), and reopen TUN/TAP and network
|
|
connections.</dd>
|
|
<dt><code>SIGUSR1</code></dt>
|
|
<dd><p class="first">Like <code>SIGHUP`</code>, except don't re-read configuration file, and
|
|
possibly don't close and reopen TUN/TAP device, re-read key files,
|
|
preserve local IP address/port, or preserve most recently authenticated
|
|
remote IP address/port based on <tt class="docutils literal"><span class="pre">--persist-tun</span></tt>, <tt class="docutils literal"><span class="pre">--persist-key</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">--persist-local-ip</span></tt> and <tt class="docutils literal"><span class="pre">--persist-remote-ip</span></tt> options respectively
|
|
(see above).</p>
|
|
<p>This signal may also be internally generated by a timeout condition,
|
|
governed by the <tt class="docutils literal"><span class="pre">--ping-restart</span></tt> option.</p>
|
|
<p class="last">This signal, when combined with <tt class="docutils literal"><span class="pre">--persist-remote-ip</span></tt>, may be sent
|
|
when the underlying parameters of the host's network interface change
|
|
such as when the host is a DHCP client and is assigned a new IP address.
|
|
See <tt class="docutils literal"><span class="pre">--ipchange</span></tt> for more information.</p>
|
|
</dd>
|
|
<dt><code>SIGUSR2</code></dt>
|
|
<dd>Causes OpenVPN to display its current statistics (to the syslog file if
|
|
<tt class="docutils literal"><span class="pre">--daemon</span></tt> is used, or stdout otherwise).</dd>
|
|
<dt><code>SIGINT</code>, <code>SIGTERM</code></dt>
|
|
<dd>Causes OpenVPN to exit gracefully.</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="section" id="faq">
|
|
<h1>FAQ</h1>
|
|
<p><a class="reference external" href="https://community.openvpn.net/openvpn/wiki/FAQ">https://community.openvpn.net/openvpn/wiki/FAQ</a></p>
|
|
</div>
|
|
<div class="section" id="howto">
|
|
<h1>HOWTO</h1>
|
|
<p>For a more comprehensive guide to setting up OpenVPN in a production
|
|
setting, see the OpenVPN HOWTO at
|
|
<a class="reference external" href="https://openvpn.net/community-resources/how-to/">https://openvpn.net/community-resources/how-to/</a></p>
|
|
</div>
|
|
<div class="section" id="protocol">
|
|
<h1>PROTOCOL</h1>
|
|
<p>For a description of OpenVPN's underlying protocol, see
|
|
<a class="reference external" href="https://openvpn.net/community-resources/openvpn-protocol/">https://openvpn.net/community-resources/openvpn-protocol/</a></p>
|
|
</div>
|
|
<div class="section" id="web">
|
|
<h1>WEB</h1>
|
|
<p>OpenVPN's web site is at <a class="reference external" href="https://openvpn.net/">https://openvpn.net/</a></p>
|
|
<p>Go here to download the latest version of OpenVPN, subscribe to the
|
|
mailing lists, read the mailing list archives, or browse the SVN
|
|
repository.</p>
|
|
</div>
|
|
<div class="section" id="bugs">
|
|
<h1>BUGS</h1>
|
|
<p>Report all bugs to the OpenVPN team <a class="reference external" href="mailto:info@openvpn.net">info@openvpn.net</a></p>
|
|
</div>
|
|
<div class="section" id="see-also">
|
|
<h1>SEE ALSO</h1>
|
|
<p><tt class="docutils literal"><span class="pre">openvpn-examples</span></tt>(5),
|
|
<tt class="docutils literal">dhcpcd</tt>(8),
|
|
<tt class="docutils literal">ifconfig</tt>(8),
|
|
<tt class="docutils literal">openssl</tt>(1),
|
|
<tt class="docutils literal">route</tt>(8),
|
|
<tt class="docutils literal">scp</tt>(1)
|
|
<tt class="docutils literal">ssh</tt>(1)</p>
|
|
</div>
|
|
<div class="section" id="notes">
|
|
<h1>NOTES</h1>
|
|
<p>This product includes software developed by the OpenSSL Project
|
|
(<a class="reference external" href="https://www.openssl.org/">https://www.openssl.org/</a>)</p>
|
|
<p>For more information on the TLS protocol, see
|
|
<a class="reference external" href="http://www.ietf.org/rfc/rfc2246.txt">http://www.ietf.org/rfc/rfc2246.txt</a></p>
|
|
<p>For more information on the LZO real-time compression library see
|
|
<a class="reference external" href="https://www.oberhumer.com/opensource/lzo/">https://www.oberhumer.com/opensource/lzo/</a></p>
|
|
</div>
|
|
<div class="section" id="copyright">
|
|
<h1>COPYRIGHT</h1>
|
|
<p>Copyright (C) 2002-2020 OpenVPN Inc This program is free software; you
|
|
can redistribute it and/or modify it under the terms of the GNU General
|
|
Public License version 2 as published by the Free Software Foundation.</p>
|
|
</div>
|
|
<div class="section" id="authors">
|
|
<h1>AUTHORS</h1>
|
|
<p>James Yonan <a class="reference external" href="mailto:james@openvpn.net">james@openvpn.net</a></p>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|