.Dd January 25, 2012
.Dt CLOUD 8
.Os NetBSD 1.4T
.Sh NAME
.Nm cloud
.Nd cloud-style VPN
.Sh SYNOPSIS
.Nm
.Op Fl config Ar file
.Op Fl C Ar configline
.Op Fl v Ar arg
.Op Fl bg
.Sh DESCRIPTION
.Nm
maintains a VPN among multiple peers.  Unlike a traditional VPN, which
has a clear distinction between a
.Sq server
endpoint and various
.Sq client
endpoints,
.Nm
is designed around a much more peer-to-peer model (though, with
suitable configuration, it can be used to construct such traditional
setups).
.Pp
Configuration normally comes from a config file, named as argument to the
.Fl config
option.  Multiple config files may be given; they are read in order,
with the resulting configuration lines processed as if they were read
from a single file (except for error reporting).  Also,
.Fl C
may be used to specify a single config-file line right on the command
line; it is processed as if a single-line config file containing that
line had been given to
.Fl config
at that point on the command line.  It is even possible to specify the
entire configuration with
.Fl C
options (though not usually done).
.Pp
There are two options which can be given on the command line but cannot
be specified in the config file:
.Fl v
and
.Fl bg .
.Fl v
turns on verbosity.  The argument is of the form
.Sq type1,type2,type3 Op \&= Ns Ar file ,
which turns on type1, type2, and type3 verbosity, and, if the optional
.Pf \&= Ar file
is given, sends the output to
.Ar file .
The argument to
.Fl v
can also be a single question mark (which will usually need to be
quoted to protect it from the shell), which will cause
.Nm
to print out all of the verbosity types it understands and then not
start.  Finally,
.Fl bg
specifies that
.Nm
is to background itself at startup, as soon as all startup
error-checking has been done, listening points established,
.Xr tun 4
instance opened, etc.
.Pp
Each VPN member listens on zero or more listening points and also has
zero or more peer addresses.  It tries to maintain a connection to each
of the peer addresses; it also accepts connections from peers on the
listening points.  Once a connection is established, which end
initiated it matters little (only for the initial cryptographic
exchange, for which the connection acceptor challenges the connection
initiator to demonstrate that it is a member of the VPN); packets can
flow either way.  One of the major features
.Nm
offers is what might be called endpoint learning: when a host manages
to connect to any member of the VPN, it learns about all the members
which are prepared to accept connections and tries to establish
connections to them as well (if configured to do so; a host may be
configured to not try to do this).
.Pp
Each VPN member also has an ID.  This operates somewhat like a
link-layer address within the VPN; each VPN member must have a
distinct ID, and they must all be in the range 0 through 255.  (The
protocols do not support more than 256 members in a VPN.)
.Pp
Each VPN member also has one or more IP addresses.  The VPN is
basically an IP transport, so VPN members need to have IP addresses.
Each member will normally have only one, but may have more; the
protocols get inefficient if VPN members have too many addresses.
.Pp
All communication is encrypted, and host membership in the VPN is
verified by leveraging a shared secret, called a
.Dq key
below.
.Sh CONFIG FILE
The configuration language consists of a series of lines, read from
config files or
.Fl C
options.  Each line is processed in turn.  If the line contains nothing
but whitespace, or if the first non-whitespace character is a
.Sq # ,
the line is a comment and is ignored.  Otherwise, the first
whitespace-delimited string is taken as a keyword:
.Bl -tag -width indent
.It \&@ Ar FILE
.Ar FILE
is read at this point and the lines from it are, effectively, inserted
in place of the \&@ line.
.It key Ar KEY
The VPN key is
.Ar KEY .
The key starts with the first non-whitespace character after the
.Sq key
keywords and continues to the end of the line.  There is no way to get
a NUL or a newline in the key when specifying the key this way.  It
also means that the config file must usually be protected fairly
stringently, since anyone who can read it can then join the VPN.
.It keyfile Ar FILE
.Ar FILE
is read and its contents constitute the VPN key.  If the file is larger
than 65536 bytes, a warning is printed to stderr and only the first
65536 bytes are used.  Any bytes may be present in the key in this
case; it is raw binary data.  Note that there is a subtle danger here;
a key specified with
.Sq key
normally will not have a trailing newline, but, unless special care is
taken to avoid it, a text string in a file generally will, and of
course a key with a trailing newline is as different from one without
as any two distinct strings are.
.It id Ar N
Specifies this member's VPN ID.  This may be any number in the range 0
through 255, and must be distinct from every other VPN member's ID
number.
.It ip Ar ADDR
.Ar ADDR
is one of this member's IP addresses.  More
.Sq ip
lines may be given to give the member more addresses.
.It type Ar T
T may be
.Sq public
or
.Sq private .
This configures this VPN member to pay attention to advertisements of
other members' listening points and to try to maintain connections to
them
.Pf ( Sq public )
or to ignore such advertisements and maintain connections only to
declared peer addresses
.Pf ( Sq private ) .
.It Xo listen
.Ar ADDR Ns / Ns Ar PORT
.Op Ar OPTIONS ...
.Xc
Configures this VPN member to listen on address
.Ar ADDR
port
.Ar PORT
for connections from other members.  The
.Ar ADDR
string may also be
.Sq \&* ,
.Sq \&*4 ,
or
.Sq \&*6 ,
to indicate
.Sq all local addresses ,
.Sq all local IPv4 addresses ,
or
.Sq all local IPv6 addresses ,
respectively.  Multiple
.Sq listen
lines may be given if a member is to listen on multiple addresses.  The
.Ar OPTIONS
are zero or more keywords specifying optional behaviour.  The keywords
can be:
.Bl -tag -width indent
.It retry
Normally, failure from
.Xr bind 2
when setting up the listening point at startup time is fatal.  If
.Sq retry
is given, such failure at startup is nonfatal;
.Nm
retries periodically until it succeeds.  Note that resolving the string
given to a list of addresses is not retried, only the
.Xr socket 2
and
.Xr bind 2
calls.
.It public
This listening point is to be advertised to other VPN members.
.It private
This listening point is not to be advertised to other VPN members.
.El
.Pp
If
.Sq public
and
.Sq private
are both given, whichever one is given last wins; if neither is given,
the default is
.Sq private
for RFC-1918 private addresses (for IPv4) and site-local and link-local
addresses (for IPv6),
.Sq public
otherwise \- but note that listening points which are wildcarded with
the
.Sq \&* ,
.Sq \&*4 ,
or
.Sq \&*6
strings cannot be advertised under any circumstances.
.It peer Ar ADDR Ns / Ns Ar PORT
This provides an initial entry point into the VPN.
.Ar ADDR
and
.Ar PORT
must give an address and port where some other VPN member is listening
for connections.  This member will try to keep a connection up to this
address and port; if this peer is of type public (see the
.Sq type
line, above), this is in addition to any it may hear advertised.  There
is no requirement that any peer lines be specified, though in most
applications each host will have at least one.  (A host that doesn't
have any will initiate connections only after someone else connects to
it and it learns of others' listening points that way.  A host
configured with no peers and type private will never initiate any
connections at all, acting much like a traditional pure-server VPN
endpoint.)
.It tun Ar ARG Op Ar TYPE
This specifies which
.Xr tun 4
interface to use and, optionally, its mode.
.Ar ARG
can be a simple number
.Ar N ,
as defined by
.Xr strtol 3 ,
such as
.Sq 4
or
.Sq 12 ,
in which case the usual path for that
.Xr tun 4
unit number is used
.Pf ( Pa /dev/tun Ns Ar N ) ,
or it can be a path to the
.Xr tun 4
control device, in case something unconventional is called for.  (If
you want to use a pathname consisting of only digits, prefix it with a
path, even if only
.Pa ./ . )
The
.Ar TYPE
can be
.Sq broadcast
or
.Sq pointopoint ;
if specified,
.Nm
tries to change the
.Xr tun 4
device's type to the one specified.  If unspecified,
.Nm
does not try to change the type.
.It control Ar NAME
.Ar NAME
can be an IP
.Ar ADDR Ns / Ns Ar PORT ,
or it can be
.Ar PATH Op Ar MODE ,
a local pathname with an optional mode (the
.Ar PATH
must begin with a slash; this is how
.Nm
determines which alternative it's dealing with).  This specifies that
the process is to listen for control connections on the given IP
endpoint or the given
.Dv AF_LOCAL
socket.  In the latter case,
.Ar MODE ,
if given, specifies the mode bits for the socket; if not given the
default is 0777 modified by the current umask (see
.Xr umask 2 ) .
(There is no quoting convention; there is no support for
.Ar PATH Ns No s
containing whitespace.)  The command language is not documented here;
use
.Sq \&?
to get help.
.Pp
Multiple
.Sq control
lines may be given to listen for control connections at multiple
places.
.El
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents-montreal.org .