vtunngd.conf.5

.\" Manual page for vtund.conf
.\" $Id: vtund.conf.5,v 1.4.2.6 2016/09/17 20:01:24 mtbishop Exp $
.TH VTUND.CONF 5

.SH NAME
vtund.conf \- VTun(Virtual Tunnel) daemon configuration file.

.SH DESCRIPTION

Configuration file for
.BR vtund (8)
virtual tunnel daemon.
.LP
File consists of sections in the form:
.IP
.nf
.IR name " {"
.IR "  keyword value" ;
.IR "  keyword value" ;
  ..
}
.fi

.LP
Semicolon at the end of each keyword-value pair is required,
as well as grouping curly braces {}.
Lines which begin with '#' characters are comments.
.LP
Name of section (\fIname\fR) can be one of:
.IP \fBoptions\fR
this section specifies general options for vtund
.IP \fBdefault\fR
specifies default options for all sessions
.IP \fIsession\fR
(any other word except "options" and "default")
introduces new session and specifies options for it.
.LP
All keyword names can be abbreviated to a minimum of 4 characters.
.LP

.SH "GENERAL OPTIONS"

.LP
This section, named
.BR options ,
specifies general options to use by
.BR vtund (8).
Possible \fIkeyword\fRs are:
.IP \fBtype\fR\ \fBstand\fR|\fBinetd\fR
server type. \fBvtund\fR(8) can operate in standalone
mode (\fBstand\fR), that is the default (but not available on no-MMU systems), or be invoked from
.BR inetd (8).

.IP \fBport\ \fIportnumber\fR
server port number to listen on or connect to.
By default, \fBvtund\fR(8) uses port 5000.

.IP \fBbindaddr\ \fIlist\fR
server listen address. Used to force vtund to bind to the specific
address and port in server mode.  Format:
.nf
  \fBbindaddr\fR {
   \fIoption \fIvalue\fR;
  };
.fi
.IP
\fBbindaddr\fR options:
.RS
.IP \fBiface\ \fIif_name\fR
use interface address \fIif_name\fR as the bind address.
.IP \fBaddr\ \fIaddr\fR
bind address.  Can be either IP address or host name.
.RE

.IP \fBtimeout\ \fIseconds\fR
General timeout.

.IP \fBpersist\fR\ \fByes\fR|\fBkeep\fR|\fBno\fR
persist mode.  If \fByes\fR, the client will try to reconnect to the server
after connection termination.  If \fBkeep\fR, the client will not remove
and re-add the \fBtun\fIXX\fR or \fBtap\fIXX\fR device when reconnecting.
If \fBno\fR, the client will exit (default).
This option is ignored by the server.

.IP \fBsyslog\fR\ \fBnumber\fR|\fBname\fR
syslog facility specification, either numeric or name (from syslog (3)).

.IP \fBhardening\fR\ \fBdropcaps\fR\ \fBsetuid\fR\ \fBsetgid\fR
Enable hardening features such as dropcaps or setuid.

Dropcaps will on supported platforms
(currently FreeBSD and Linux) drop kernel capabilites when
interacting over external network. This reduces the potential
concequences of a RCE breach by limiting access to resources and
kernel interfaces.

Setuid will change the user id to something else than root while
communicating on external network. This also limits the concequences
of a potential RCE breach similarly to dropcaps by limiting access.
Default user and group is nobody, but can be changed by using setuid
and setgid options (see below).

Dropcaps and setuid will cause vtunngd to
fork for both authenticating with remote hosts and tunneling traffic
to and from remote hosts. This hurts performance and may cause a server
to be more susceptible to denial of service attacks. While on the
positive side this helps protect against RCE vulnerabilities by
restricting what capabilities an attacker is able to exploit if they
gain access.

.IP \fBsetuid\fR\ \fB<user>\fR
Set the user id to change to when running network communication. Setting
this option will enable the setuid hardening feature (see hardening above). This option
accepts both a username and a user id.

.IP \fBsetgid\fR\ \fB<group>\fR
Set the group id to change to when running network communication. Setting
this option will enable the setgid hardening feature (see hardening above). This
option accepts both a group name and a group id.

.IP \fBppp\ \fIpath\fR
path to \fBpppd\fR(8) program.  Can be used in session sections.

.IP \fBifconfig\ \fIpath\fR
path to \fBifconfig\fR(8) program.  Can be used in session sections.

.IP \fBroute\ \fIpath\fR
path to \fBroute\fR(8) program.  Can be used in session sections.

.IP \fBip\ \fIpath\fR
path to \fBiproute\fR(8) program.  Can be used in session sections.

.IP \fBfirewall\ \fIpath\fR
program for the firewall setup.

.LP
All the \fBppp\fR, \fBifconfig\fR, \fBroute\fR and \fBfirewall\fR
parameters can specify a filename for corresponding program or
equivalent (or shell script).  This parameters are used in session sections
to setup network interfaces.

.SH "SESSION OPTIONS"

.LP
Session options can be specified inside session section or
inside \fBdefault\fR section.  Default parameters apply
to any session section but can be overwritten there.
Parameters are:

.IP \fBpasswd\ \fIsecret\fR
password for authentication.  This should be the same in
client and server.

.IP \fBtype\ \fItype\fR
type of tunnel.  Possible tunnel types are:
.RS
.IP \fBtun\fR
IP tunnel (no PPP, Ether etc headers)
.IP \fBether\fR
Ethernet tunnel
.IP \fBtty\fR
serial tunnel (PPP, SLIP etc)
.IP \fBpipe\fR
pipe tunnel
.RE
.IP
Default tunnel type is \fBtty\fR.
This option is ignored by client.

.IP \fBdevice\ \fIdev\fR
network device to use.  You can choose
\fBtap\fIXX\fR for \fBether\fR tunnel
or \fBtun\fIXX\fR for \fBtun\fR tunnel.
By default \fBvtund\fR(8) will automatically select available device.

.IP \fBproto\ \fBtcp\fR|\fBudp\fR
protocol to use.  By default, \fBvtund\fR(8) will use TCP protocol.
UDP is recommended for \fBether\fR and \fBtun\fR tunnels only.
This option is ignored by the client.

.IP \fBnat_hack\ \fBclient\fR|\fBserver\fR|\fBno\fR
side to use nat_hack on.  By default, \fBvtund\fR(8) uses a 'no' setting.
The side that the NAT hack is enabled on will perform a delayed UDP socket
connect. Should only be enabled for the side outside of the NAT (typically 
the server)! Setting 'client' on the server or 'server' on the client is 
ignored, as to make a single configuration file reusable on both sides.

This is only relevant if you use \fBproto udp\fR. The NAT hack delays
the UDP socket connect until the first UDP packet is received from the other
side of the tunnel. The socket is then connected to the actual source port of
the packet (on the NAT box) and not to the one indicated in the handshake 
(which is behind NAT and probably unreachable). 
The first echo request is also disabled on the side with the NAT hack enabled.

Currently the mechanism works only for one side, for a single NAT traversal.
If you enable it for both sides, both will wait for a first packet and the 
tunnel will never transport any data.

\fBSecurity warning!\fR Due to the nature of the delayed connection, the tunnel
can be hijacked in theory by an attacker behind the same NAT, sending the first 
UDP packet to the server UDP port, before the real client does. If you do not 
understand the risks, or want to remain as secure as possible behind this kind
of NAT router, use \fBproto tcp\fR as a NAT traversal solution.

Because of the security issue mentioned above, this option might be disabled
during compilation (configure --disable-nathack). 

.IP \fBtimeout\ \fIsecounds\fR
Connect timeout.

.IP \fBcompress\ \fImethod\fR[\fB:\fIlevel\fR]
specifies compression method to use.  Compression \fImethod\fRs include:
.RS
.IP \fBno\fR
no compression
.IP \fByes\fR
default compression method
.IP \fBzlib\fR
ZLIB compression
.IP \fBlzo\fR
LZO compression (if compiled in)
.RE
.IP
You can also specify \fIlevel\fR of compression using one
digit (1 is best speed, 9 is best compression ratio).
This option is ignored by the client.

.IP \fBencrypt\ \fImethod\fR[\fB:\fIlevel\fR]
specifies encryption method to use.  Encryption \fImethod\fRs include:
.RS
.IP \fBno\fR
no encryption
.IP \fByes\fR
default encryption method (\fBblowfish128ecb\fR)
.IP \fBblowfish128ecb\fR
Blowfish cipher, 128 bit key, mode ECB
.IP \fBblowfish128cbc\fR
Blowfish cipher, 128 bit key, mode CBC
.IP \fBblowfish128cfb\fR
Blowfish cipher, 128 bit key, mode CFB
.IP \fBblowfish128ofb\fR
Blowfish cipher, 128 bit key, mode OFB
.IP \fBblowfish256ecb\fR
Blowfish cipher, 256 bit key, mode ECB
.IP \fBblowfish256cbc\fR
Blowfish cipher, 256 bit key, mode CBC
.IP \fBblowfish256cfb\fR
Blowfish cipher, 256 bit key, mode CFB
.IP \fBblowfish256ofb\fR
Blowfish cipher, 256 bit key, mode OFB
.IP \fBaes128ecb\fR
.IP \fBoldblowfish128ecb\fR
Blowfish cipher, 128bit key, mode ECB 
 (for use with 2.6 clients only)
AES cipher, 128 bit key, mode ECB
.IP \fBaes128cbc\fR
AES cipher, 128 bit key, mode CBC
.IP \fBaes128cfb\fR
AES cipher, 128 bit key, mode CFB
.IP \fBaes128ofb\fR
AES cipher, 128 bit key, mode OFB
.IP \fBaes256ecb\fR
AES cipher, 256 bit key, mode ECB
.IP \fBaes256cbc\fR
AES cipher, 256 bit key, mode CBC
.IP \fBaes256cfb\fR
AES cipher, 256 bit key, mode CFB
.IP \fBaes256ofb\fR
AES cipher, 256 bit key, mode OFB
.IP \fBaes128gcm\fR
AES cipher, 128 bit key, mode GCM
.IP \fBaes256gcm\fR
AES cipher, 256 bit key, mode GCM
.IP \fBaes128gcmsiv\fR
AES cipher, 128 bit key, mode GCM-SIV
.IP \fBaes256gcmsiv\fR
AES cipher, 256 bit key, mode GCM-SIV
.IP \fBchacha20poly1305\fR
Chacha20 cipher (Aes256 for initialization), 256 bit key, poly1305 message authentication.
.RE
.IP
This option is ignored by the client.
.IP \fBrequires\ \fBclient\ \fBbidirauth\ \fBencryption\ \fBintegrity\ \fB"3.1"\fR
set requirements for the connection. This is specifically for the client where
you can set requirements for what configuration it will accept from the client.
Multiple requirements can be specified.
.RS
.IP \fBclient\fR
The configuration is for client only, will not be used in server mode.
.IP \fBbidirauth\fR
Client requires the server to authenticate as well as the client. Authentication in both directions.
.IP \fBencryption\fR
Requires the connection to be encrypted.
.IP \fBintegrity\fR
Requires the integrity of the data to be protected. Some encryption algorithms do this, like aes128gcm and aes256gcm.
.IP \fB"3.1"\fR
Version 3.1 modes. Alias for bidirauth.
.RE

.IP \fBaccept_encrypt\ \fB<encryption-algo>\fR
This accepts the same algorithms as the 'encrypt' keyword. This can be used
to set up an allowlist of encryption algorithms that the client will accept.
Multiple algorithms can be specified, also multiple accept_encrypt statements
is accepted.
.IP \fBkeepalive\ \fByes\fR|\fBno\fR|\fIinterval\fB:\fIcount\fR
enable or disable connection keep-alive. Time \fIinterval\fR is a period
between connection checks, in seconds, and \fIcount\fR is the maximum number
of retries (\fByes\fR = \fI30\fB:\fI4\fR).
This option is ignored by the server.
.IP \fBstat\ \fByes\fR|\fBno\fR
enable or disable statistics.  If enabled \fBvtund\fR(8) will log
statistic counters to /var/log/vtund/session_X every 5 minutes.
.IP \fBspeed\ \fIkbps\fR
specifies speed of the connection in kilobits/second.
Valid values for \fIkbps\fR are 8,16,32,64,128,256,etc.
0 (the default) means maximum possible speed without shaping.
You can specify speed in form \fIin\fB:\fIout\fR, where
\fIin\fR is speed to client, \fIout\fR - from the client.
Single number means the same speed for in and out.
This option ignored by the client.
.IP \fBsrcaddr\ \fIlist\fR
local (source) address. Used to force vtund to bind to the specific
address and port.  Format:
.nf
  \fBsrcaddr\fR {
   \fIoption \fIvalue\fR;
   \fIoption \fIvalue\fR;
   ..
  };
.fi
.IP
\fBsrcaddr\fR options:
.RS
.IP \fBiface\ \fIif_name\fR
use interface address \fIif_name\fR as the source address.
.IP \fBaddr\ \fIaddr\fR
source address.  Can be either IP address or host name.
.IP \fBport\ \fIportnumber\fR
source port.
.RE
.IP \fBmulti\ \fIvalue\fR
control multiple connections.  \fIvalue\fR can be
\fByes\fR or \fBallow\fR to allow multiple connections,
\fBno\fR or \fBdeny\fR to deny them or
\fBkillold\fR to allow new connection and kill old one.
Ignored by the client.

.IP \fBup\ \fIlist\fR
list of programs to run after connection has been established.
Used to initialize protocols, devices, routing and firewall.
This option looks like whole section inside of session section.
For now, it's impossible to run \fBup\fR commands on no-MMU systems, so the section is ignored there.
Format:
.nf
 \fBup\fR {
   \fIoption \fIvalue\fR;
   \fIoption \fIvalue\fR;
   ..
 };
.fi
.IP
Options inside \fBup\fR (and \fBdown\fR) blocks:
.RS
.IP \fBprogram\ \fIpath\ arguments\fR\ [\fBwait\fR]
run specified program.  \fIpath\fR is the full path to the program,
\fIarguments\fR is all arguments to pass to it (enclosed in double quotes).
If \fIwait\fR specified, \fBvtund\fR will wait program termination.
Special characters that can be used inside \fIarguments\fR parameter:
.IP
\fB\'\fR (single quotes) - group arguments
.br
\fB\\\fR (back slash) - escape character
.br
\fB%d\fR - TUN or TAP device or TTY port name 
.br
\fB%%\fR (double percent) - same as %d
.br
\fB%A\fR - Local IP address
.br
\fB%P\fR - Local TCP or UDP port
.br
\fB%a\fR - Remote IP address
.br
\fB%p\fR - Remote TCP or UDP port
.br
\fB%h\fR - Host profile name
.IP \fBppp\ \fIarguments\fR
run program specified by \fBppp\fR statement in \fBoptions\fR section.
All special character described above are valid in \fIarguments\fR here.
.IP \fBifconfig\ \fIarguments\fR
run program specified by \fBifconfig\fR statement in \fBoptions\fR section.
.IP \fBroute\ \fIarguments\fR
run program specified by \fBroute\fR statement in \fBoptions\fR section.
.IP \fBip\ \fIarguments\fR
run program specified by \fBip\fR statement in \fBoptions\fR section.
.IP \fBfirewall\ \fIarguments\fR
run program specified by \fBfirewall\fR statement in \fBoptions\fR section.
.RE
.IP \fBdown\ \fIlist\fR
list of programs to run after connection has been terminated.
It is similar to \fBup\fR parameter above.
Not available on no-MMU systems too.
Format:
.nf
 \fBdown\fR {
   \fIoption \fIvalue\fR;
   \fIoption \fIvalue\fR;
   ..
 };
.fi

.SH NOTES
Options ignored by the client are supplied by the server at the run
time or are used only on the server side.

.SH "SEE ALSO"
.BR vtund (8),
.BR inetd (8),
.BR ifconfig (8),
.BR route (8),
.BR pppd (8),
.BR syslog (3),
.BR zlib (3).

.SH AUTHOR
Vtund written by Maxim Krasnyansky <max_mk@yahoo.com>.
This manual page was derived from comments in config file by
Michael Tokarev <mjt@tls.msk.ru>