n3n-edge.8

.TH n3n-edge 8  "5 Jan 2024" "version 3" "SUPERUSER COMMANDS"
.SH NAME
n3n-edge \- VPN edge node daemon
.SH SYNOPSIS
.B edge
[\fIoptions..\fR] [command] [\fIcommand args\fR]
.br
.B n3n-edge start
[\fIsessionname\fR] [\fB\-c \fR<\fIcommunity\fR>] [\fB\-l \fR<\fIsupernode host:port\fR>]
.br
.B n3n-edge --help
.SH DESCRIPTION
n3n is a peer-to-peer VPN system - it is the LAN you have when you have noLAN.

.B n3n-edge
is a daemon for n3n which creates a TAP interface to expose
the n3n virtual LAN, providing an "edge node".

On startup
.B n3n-edge
will load any config file, then any environment variables and
then load the settings from the command line.  Once it has the full config
loaded, it will register with the supernode and create and setup the TAP
interface so it can begin to find other nodes in the community.

See the CONFIG and EXAMPLE sections for the use of the config file.

.SH OPTIONS
Some of the most common options also have a shortcut version and you can see
all of them with:

.RS
.B n3n-edge help options
.RE
.TP
.SH Generic Options
.TP
\fB\-O \fR<\fIsection\fR>.<\fIoption\fR>=<\fIvalue\fR>
Sets any config option value.
.TP
\fB\-h\fR, \fB\--help\fR
Show some quick usage notes.
.TP
.SH
Options related to the network community being joined.
.TP
\fB\-c \fR<\fIcommunity\fR>, \fB\-\-community\fR=<\fIcommunity\fR>
sets the n3n community name (see also the ENVIRONMENT section). All edges
within the same community appear on the same LAN (layer 2 network segment).
Community name is 16 bytes in length. A name smaller than this is padded with
0x00 bytes and a name longer than this is truncated to take the first 16 bytes.
.TP
\fB\-l \fR<\fIhost:port\fR>, \fB\-\-supernode-list\fR=<\fIhost:port\fR>
sets the n3n supernode IP address and port to register to. Multiple supernodes
can be specified.
.TP
\fB\-k \fR<\fIkey\fR>
sets the encryption key from ASCII text (see also the ENVIRONMENT section). All
edges communicating must use the same key and community name. If a key is not
specified then edge uses cleartext mode (no encryption).
.TP
.SH TUNTAP Options
.TP
\fB\-a \fR[\fImode\fR]<\fIip\fR>[\fI/n\fR]
interface address and optional CIDR subnet, default '/24',
mode = [auto|static|dhcp]:, for DHCP use '\-r -a dhcp:0.0.0.0',
edge draws IP address from supernode if no '\-a ...' given
.TP
.SH FILTER Options
.TP
\fB\-r\fR
enable IP packet forwarding/routing through the n3n virtual LAN. Without this
option, IP packets arriving over n3n are dropped if not for the -a <addr> (or
DHCP assigned) IP address of the edge interface. This option is also required
to allow n3n device being used in network bridging, e.g. with brctl.
.TP
.SH DAEMON Options
.TP
\fB\-d\fR, \fB\-\-daemon\fR
Fork and run as a daemon, instead of the default of running in foreground.
This is ignored on windows.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
make more verbose, repeat as required
.SH CONFIG FILE
When running the \fBstart\fR command, the edge will use the given sessionname
(Or "edge" if none is given) to search for a config file:

.RS
/etc/n3n/\fB<sessionname>\fR.conf

\fI%USERPROFILE%\fR\\n3n\\\fB<sessionname>\fR.conf (On Windows)
.RE

This file is an INI style file and a full description of the options is
available with the commandline:

.RS
.B n3n-edge help config
.RE
.SH ENVIRONMENT
After loading any config file, some settings are loaded from the environment.
(They can still be replaced by additional options from the commandline)

The environment variables are used so that the value is not not visible at the
command line.  It is expected that a config file will be better for most users.
.TP
.B N3N_KEY
set the encryption key (Equivalent to community.key, or -k)
.TP
.B N3N_COMMUNITY
set the community name (Equivalent to community.name, or -c)
.TP
.B N3N_PASSWORD
set the password for user-password authentication (Equivalent to auth.password)
.SH EXAMPLES
.TP
.SH Simplest example
.RE

For the simplest testing, without any encryption:

.RS
.B n3n-edge start -c mynetwork -l supernode.ntop.org:7777
.RE
.TP
.SH Config file example
.RE

Showing the same configuration as the above simple example.
Create a file \fB/etc/n3n/mynetwork.conf\fR with these contents:

.nf
.RS
[community]
name=mynetwork
key=mypassword
supernode=supernode.ntop.org:7777
.RE
.fi

Then start the daemon in the foreground:

.RS
.B n3n-edge start mynetwork
.RE

.TP
.SH Complex example with a config file
.RE

Create a config file \fB/etc/n3n/mynetwork.conf\fR with these contents:

.nf
.RS
[tuntap]
name = n3n0
macaddr = DE:AD:BE:EF:01:23
address = 192.168.254.7
[community]
name = mynetwork
key = encryptme
supernode = 123.121.120.119:7654
[daemon]
userid = 99
groupid = 99
backgroun = true
[connection]
bind = 50001
.RE
.fi

Then start the daemon with:

.RS
.B n3n-edge start mynetwork
.RE

Will start the edge with TAP device n3n0 on community "mynetwork" with
community supernode at 123.121.120.119 UDP port 7654 and bind the locally used
UDP port to 50001. Use "encryptme" as the single permanent shared encryption
key. Assign MAC address DE:AD:BE:EF:01:23 to the n3n interface and drop to
user=99 and group=99 after the TAP device is successfully configured.

.TP
.SH Complex example with no config file

This will configure the edge with the same settings as the above config file
but do it entirely from the commandline.

.nf
.B n3n-edge start \\\\
    \--daemon \\
    \-O tuntap.name=n3n0 \\
    \-c mynetwork \\
    \-k encryptme \\
    \-O daemon.userid=99 \\
    \-O daemon.groupid=99 \\
    \-O tuntap.macaddr=DE:AD:BE:EF:01:23 \\
    \-a 192.168.254.7 \\
    \-O connection.bind=50001 \\
    \-l 123.121.120.119:7654
.fi

(Remove the \-\-daemon option to stop edge running as a daemon)


To build a simple network, on a second computer setup another edge with
similar parameters, eg:

.nf
.B n3n-edge start \\\\
    \-O tuntap.name=n3n0 \\
    \-c mynetwork \\
    \-k encryptme \\
    \-O daemon.userid=99 \\
    \-O daemon.groupid=99 \\
    \-O tuntap.macaddr=DE:AD:BE:EF:01:21 \\
    \-a 192.168.254.5 \\
    \-O connection.bind=50001 \\
    \-l 123.121.120.119:7654
.fi

Now you can ping from 192.168.254.5 to 192.168.254.7.

It is not required to specify a MAC address as a random address will be chosen
by the edge.  If no IP address is specified, the edge will request a suitable
address to be allocated from the supernode.

The MAC address (tuntap.macaddr) and virtual IP address (tuntap.address) must
be different on all edges in the same community,

.SH CLEARTEXT MODE
If
.B -k
is not specified then edge uses cleartext mode. In cleartext mode there is no
transform of the packet data it is simply encrypted. This is useful for
debugging n3n as packet contents can be seen clearly.

To prevent accidental exposure of data, edge only enters cleartext mode when no
keying parameters are specified. In the case where keying parameters are
specified but no valid keys can be determined, edge exits with an error at
startup. If all keys become invalid while running, edge continues to encode
using the last key that was valid.

.SH MANAGEMENT INTERFACE
Edge always provides JsonAPI listening on a Unix Domain socket in /run/n3n and
optionally a TCP port (if configured with the management.port option)
See the docs/ManagementAPI.md for details.

.SH EXIT STATUS
When edge is run as a daemon, any exit is an error.  In other cases, the exit
status will be 0 for no issues found.
.SH AUTHORS
.TP
Hamish Coleman
hamish (at) zot.org - n3n maintainer
.TP
Richard Andrews
andrews (at) ntop.org - n2n-1 maintainer and main author of n2n-2
.TP
Luca Deri
deri (at) ntop.org - original author of n2n
.TP
Don Bindner
(--) - significant contributions to n2n-1
.SH SEE ALSO
ifconfig(8) supernode(8) tunctl(8) n3n(7)
.br
the documentation contained in the source code
.br
the extensive documentation found in n3n's \fBdoc/\fR folder