n3n-edge(8)

NAME
n3n-edge - VPN edge node daemon

SYNOPSIS
edge [options..] [command] [command args]
n3n-edge start [sessionname] [-c <community>] [-l <supernode host:port>]
n3n-edge --help

DESCRIPTION
n3n is a peer-to-peer VPN system - it is the LAN you have when you have noLAN. n3n-edge is a daemon for n3n which creates a TAP interface to expose the n3n virtual LAN, providing an "edge node". On startup 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.

OPTIONS
Some of the most common options also have a shortcut version and you can see all of them with:
    n3n-edge help options

Generic Options

-O <section>.<option>=<value>
    Sets any config option value.

-h, --help
    Show some quick usage notes.

Options related to the network community being joined.

-c <community>, --community=<community>
    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.

-l <host:port>, --supernode-list=<host:port>
    sets the n3n supernode IP address and port to register to. Multiple supernodes can be specified.

-k <key>
    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).

TUNTAP Options

-a [mode]<ip>[/n]
    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

FILTER Options

-r  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.

DAEMON Options

-d, --daemon
    Fork and run as a daemon, instead of the default of running in foreground. This is ignored on windows.

-v, --verbose
    make more verbose, repeat as required

CONFIG FILE
When running the start command, the edge will use the given sessionname (Or "edge" if none is given) to search for a config file:
    /etc/n3n/<sessionname>.conf %USERPROFILE%\n3n\<sessionname>.conf (On Windows)
This file is an INI style file and a full description of the options is available with the commandline:
    n3n-edge help config

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.

N3N_KEY
    set the encryption key (Equivalent to community.key, or -k)

N3N_COMMUNITY
    set the community name (Equivalent to community.name, or -c)

N3N_PASSWORD
    set the password for user-password authentication (Equivalent to auth.password)

EXAMPLES

Simplest example
For the simplest testing, without any encryption:
    n3n-edge start -c mynetwork -l supernode.ntop.org:7777

Config file example
Showing the same configuration as the above simple example.
    Create a file /etc/n3n/mynetwork.conf with these contents:
    [community]
    name=mynetwork
    key=mypassword
    supernode=supernode.ntop.org:7777
Then start the daemon in the foreground:
    n3n-edge start mynetwork

Complex example with a config file
Create a config file /etc/n3n/mynetwork.conf with these contents:
    [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
Then start the daemon with:
    n3n-edge start mynetwork
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.

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.
    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
    (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:
    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
    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,

CLEARTEXT MODE
If -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.

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/internals/ManagementAPI.md for details.

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.

AUTHORS

Hamish Coleman
    hamish (at) zot.org - n3n maintainer

Richard Andrews
    andrews (at) ntop.org - n2n-1 maintainer and main author of n2n-2

Luca Deri
    deri (at) ntop.org - original author of n2n

Don Bindner
    (--) - significant contributions to n2n-1

SEE ALSO
ifconfig(8) supernode(8) tunctl(8) n3n(7)
the documentation contained in the source code
the extensive documentation found in n3n's doc/ folder