|
|
@ -1,137 +1,138 @@ |
|
|
|
.TH edge 8 "17 Mar 2010" "n2n-2.1" "SUPERUSER COMMANDS" |
|
|
|
.TH edge 8 "18 Jul 2021" "version 3" "SUPERUSER COMMANDS" |
|
|
|
.SH NAME |
|
|
|
edge \- n2n edge node daemon |
|
|
|
.SH SYNOPSIS |
|
|
|
.B edge |
|
|
|
[\-d <tun device>] \-a <tun IP address> \-c <community> {\-k <encrypt key>|\-K <keyfile>} |
|
|
|
[\-s <netmask>] \-l <supernode host:port> [\-L <reg_ttl>] |
|
|
|
[\-p <local port>] [\-u <UID>] [\-g <GID>] [-f] [\-m <MAC address>] [\-r] [\-v] |
|
|
|
<config file> |
|
|
|
.br |
|
|
|
.B edge |
|
|
|
\-c <community> \-l <supernode host:port> [further options]... |
|
|
|
.SH DESCRIPTION |
|
|
|
N2N is a peer-to-peer VPN system. Edge is the edge node daemon for n2n which |
|
|
|
creates a TAP interface to expose the n2n virtual LAN. On startup n2n creates |
|
|
|
the TAP interface and configures it then registers with the supernode so it can |
|
|
|
begin to find other nodes in the community. |
|
|
|
.PP |
|
|
|
.SH OPTIONS |
|
|
|
.TP |
|
|
|
\-d <name> |
|
|
|
sets the TAP device name as seen in ifconfig. Only available on Linux. |
|
|
|
.TP |
|
|
|
\-a {<addr>|static:<addr>|dhcp:0.0.0.0} |
|
|
|
sets the n2n virtual LAN IP address being claimed. This is a private IP |
|
|
|
address. All IP addresses in an n2n community typical belong to the same /24 |
|
|
|
network (ie. only the last octet of the IP addresses varies). If DHCP is used to |
|
|
|
assign interface addresses then specify the address as |
|
|
|
.B -a dhcp:0.0.0.0 |
|
|
|
The config file is similar to the command line, with one option per line. |
|
|
|
Lines starting with a "#" are ignored. |
|
|
|
An equal sign ('=') should be used between key and value. Example: -p=7777 |
|
|
|
.SH OPTIONS FOR THE UNDERLYING NETWORK CONNECTION |
|
|
|
.TP |
|
|
|
\-b |
|
|
|
cause edge to perform hostname resolution for the supernode address each time |
|
|
|
the supernode is periodically contacted. This can cause reliability problems |
|
|
|
because all packet processing stops while the supernode address is resolved |
|
|
|
which might take 15 seconds. |
|
|
|
.TP |
|
|
|
\-c <community> |
|
|
|
\fB\-c \fR<\fIcommunity\fR>, \fB\-\-community\fR=<\fIcommunity\fR> |
|
|
|
sets the n2n community name. 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 |
|
|
|
\-h |
|
|
|
write usage then exit. |
|
|
|
\fB\-l \fR<\fIhost:port\fR>, \fB\-\-supernode-list\fR=<\fIhost:port\fR> |
|
|
|
sets the n2n supernode IP address and port to register to. Multiple supernodes |
|
|
|
can be specified. |
|
|
|
.TP |
|
|
|
\fB\-p \fR<\fIlocal port\fR> |
|
|
|
binds edge to the given UDP port. Useful for keeping the same external socket |
|
|
|
across restarts of edge. This allows peer edges which know the edge socket to |
|
|
|
continue p2p operation without going back to the supernode. |
|
|
|
.TP |
|
|
|
\fB\-T \fR<\fItos\fR> |
|
|
|
TOS for packets, e.g. 0x48 for SSH like priority |
|
|
|
.TP |
|
|
|
\fB\-D\fR |
|
|
|
enable PMTU discovery, it can reduce fragmentation but |
|
|
|
causes connections to stall if not properly supported |
|
|
|
.TP |
|
|
|
\-i <register_interval> |
|
|
|
\fB\-S1\fR ... \fB\-S2\fR |
|
|
|
do not connect p2p, always use the supernode, |
|
|
|
\-S1 = via UDP, \-S2 = via TCP |
|
|
|
.TP |
|
|
|
\fB\-i \fR<\fIreg_interval\fR> |
|
|
|
Supernode registration interval. It specifies the interval in seconds |
|
|
|
between consecutive REGISTER_SUPER packets and it's used to keep NAT hole |
|
|
|
open via the UDP NAT hole punching technique. This only works for asymmetric |
|
|
|
NATs and allows for P2P communication. |
|
|
|
.TP |
|
|
|
\fB\-L \fR<\fIreg_ttl\fR> |
|
|
|
set the TTL for the hole punching packet. This is an advanced flag to make |
|
|
|
sure that the registration packet is dropped immediately when it goes out of |
|
|
|
local nat so that it will not trigger some firewall behavior on target peer. |
|
|
|
Actually, the registration packet is only expected to make local nat UDP hole |
|
|
|
and is not expected to reach the target peer, see |
|
|
|
https://tools.ietf.org/html/rfc5389. To achieve this, the flag should be set as |
|
|
|
nat level + 1. For example, if we have 2 layer nat in local, we should set -L 3. |
|
|
|
Usually we know exactly how much nat layers in local. |
|
|
|
If we are not sure how much nat layers in local, we can use traceroute on |
|
|
|
Linux to check. The following example shows a local single layer nat because on |
|
|
|
second jump it shows a public ip address. In this case it should set -L 2. |
|
|
|
|
|
|
|
$ /usr/sbin/traceroute -w1 8.8.8.8 |
|
|
|
.br |
|
|
|
traceroute to 8.8.8.8 (8.8.8.8), 30 hops max, 60 byte packets |
|
|
|
1 192.168.3.1 (192.168.3.1) 0.464 ms 0.587 ms 0.719 ms |
|
|
|
2 112.65.17.217 (112.65.17.217) 5.269 ms 7.031 ms 8.666 ms |
|
|
|
|
|
|
|
But this method does not always work due to various local network device policy. |
|
|
|
.TP |
|
|
|
\fB\-k \fR<\fIkey\fR> |
|
|
|
encryption key (ASCII) - also N2N_KEY=<key> |
|
|
|
\-k <keystring> |
|
|
|
sets the twofish encryption key from ASCII text (see also N2N_KEY in |
|
|
|
sets the encryption key from ASCII text (see also N2N_KEY in |
|
|
|
ENVIRONMENT). All edges communicating must use the same key and community |
|
|
|
name. If neither -k nor -K is used to specify a key source then edge uses |
|
|
|
cleartext mode (no encryption). The -k and -K options are mutually exclusive. |
|
|
|
.TP |
|
|
|
\-K <keyfile> |
|
|
|
Reads a key-schedule file <keyfile> and populates the internal transform |
|
|
|
operations with the data found there. This mechanism allows keys to roll at |
|
|
|
pre-determined times for a group of hosts. Accurate time synchronisation is not |
|
|
|
required as older keys can be decoded for some time after expiry. If neither -k |
|
|
|
nor -K is used to specify a key source then edge uses cleartext mode (no |
|
|
|
encryption). The -k and -K options are mutually exclusive. |
|
|
|
.TP |
|
|
|
\-l <addr>:<port> |
|
|
|
sets the n2n supernode IP address and port to register to. Up to 2 supernodes |
|
|
|
can be specified by two invocations of -l <addr>:<port>. eg. |
|
|
|
.B edge -l 12.34.56.78:7654 -l 98.76.54.32:7654 |
|
|
|
. |
|
|
|
.TP |
|
|
|
\-p <num> |
|
|
|
binds edge to the given UDP port. Useful for keeping the same external socket |
|
|
|
across restarts of edge. This allows peer edges which know the edge socket to |
|
|
|
continue p2p operation without going back to the supernode. |
|
|
|
name. If -k not specified then edge uses cleartext mode (no encryption). |
|
|
|
.TP |
|
|
|
\-t <num> |
|
|
|
binds the edge management system to the given UDP port. Default 5644. Use this |
|
|
|
if you need to run multiple instance of edge; or something is bound to that |
|
|
|
port. |
|
|
|
\fB\-A1\fR |
|
|
|
disable payload encryption, do not use with key, defaults to AES then |
|
|
|
.TP |
|
|
|
\fB\-A2\fR ... \fB\-A5\fR |
|
|
|
choose a cipher for payload encryption, requires a key, |
|
|
|
\-A2 = Twofish, \-A3 = AES (default if key provided), |
|
|
|
\-A4 = ChaCha20, \-A5 = Speck-CTR |
|
|
|
.TP |
|
|
|
\-u <uid> |
|
|
|
causes the edge process to drop to the given user ID when privileges are no |
|
|
|
longer required (UNIX). |
|
|
|
\fB\-H\fR |
|
|
|
use header encryption, supernode needs fixed community |
|
|
|
.TP |
|
|
|
\-g <gid> |
|
|
|
causes the edge process to drop to the given group ID when privileges are no |
|
|
|
longer required (UNIX). |
|
|
|
\fB\-z1\fR ... \fB\-z2\fR |
|
|
|
compress outgoing data packets, -z1 = lzo1x, disabled by default |
|
|
|
.SH TAP DEVICE AND OVERLAY NETWORK CONFIGURATION |
|
|
|
.TP |
|
|
|
\-f |
|
|
|
disables daemon mode (UNIX) and causes edge to run in the foreground. |
|
|
|
\fB\-a \fR[\fImode\fR]<\fIip\fR>[\fI/n\fR] |
|
|
|
interface address and optional CIDR subnet, default '/24', |
|
|
|
mode = [static|dhcp]:, for DHCP use '\-r -a dhcp:0.0.0.0', |
|
|
|
edge draws IP address from supernode if no '\-a ...' given |
|
|
|
.TP |
|
|
|
\-m <MAC> |
|
|
|
\fB\-m \fR<\fImac\fR> |
|
|
|
start the TAP interface with the given MAC address. This is highly recommended |
|
|
|
as it means the same address will be used if edge stops and restarts. If this is |
|
|
|
not done, the ARP caches of all peers will be wrong and packets will not flow to |
|
|
|
this edge until the next ARP refresh. |
|
|
|
e.g. '\-m 10:20:30:40:50:60', by default a random MAC address is used. |
|
|
|
.TP |
|
|
|
\-M <MTU> |
|
|
|
set the MTU of the edge interface in bytes. MTU is the largest packet fragment |
|
|
|
size allowed to be moved throught the interface. The default is 1400. |
|
|
|
\fB\-d \fR<\fIdevice\fR>, \fB\-\-device\fR=<\fIdevice\fR> |
|
|
|
TAP device name |
|
|
|
.TP |
|
|
|
\-s <netmask> |
|
|
|
set the netmask of edge interface in IPv4 dotted decimal notation. The default |
|
|
|
is 255.255.255.0 (ie. /24). |
|
|
|
\fB\-M \fR<\fImtu\fR> |
|
|
|
specify n2n MTU of TAP interface, default 1290 |
|
|
|
.TP |
|
|
|
\-r |
|
|
|
\fB\-r\fR |
|
|
|
enable IP packet forwarding/routing through the n2n virtual LAN. Without this |
|
|
|
option, IP packets arriving over n2n are dropped if not for the -a <addr> (or |
|
|
|
DHCP assigned) IP address of the edge interface. |
|
|
|
.TP |
|
|
|
\-E |
|
|
|
\fB\-E\fR |
|
|
|
accept packets destined for multicast ethernet MAC addresses. These addresses |
|
|
|
are used in multicast ethernet and IPv6 neighbour discovery. If this option is |
|
|
|
not present these multicast packets are discarded as most users do not need or |
|
|
|
understand them. |
|
|
|
.TP |
|
|
|
\-L |
|
|
|
set the TTL for the hole punching packet. This is an advanced flag to make |
|
|
|
sure that the registration packet is dropped immediately when it goes out of |
|
|
|
local nat so that it will not trigger some firewall behavior on target peer. |
|
|
|
Actually, the registration packet is only expected to make local nat UDP hole |
|
|
|
and is not expected to reach the target peer, see |
|
|
|
https://tools.ietf.org/html/rfc5389. To achieve this, the flag should be set as |
|
|
|
nat level + 1. For example, if we have 2 layer nat in local, we should set -L 3. |
|
|
|
Usually we know exactly how much nat layers in local. |
|
|
|
If we are not sure how much nat layers in local, we can use traceroute on |
|
|
|
Linux to check. The following example shows a local single layer nat because on |
|
|
|
second jump it shows a public ip address. In this case it should set -L 2. |
|
|
|
|
|
|
|
$ /usr/sbin/traceroute -w1 8.8.8.8 |
|
|
|
traceroute to 8.8.8.8 (8.8.8.8), 30 hops max, 60 byte packets |
|
|
|
1 192.168.3.1 (192.168.3.1) 0.464 ms 0.587 ms 0.719 ms |
|
|
|
2 112.65.17.217 (112.65.17.217) 5.269 ms 7.031 ms 8.666 ms |
|
|
|
|
|
|
|
But this method does not always work due to various local network device policy. |
|
|
|
\fB\-I \fR<\fIdescription\fR> |
|
|
|
annotate the edge's description used for easier |
|
|
|
identification in management port output or username |
|
|
|
.TP |
|
|
|
\fB\-J \fR<\fIpassword\fR> |
|
|
|
password for user-password edge authentication |
|
|
|
.TP |
|
|
|
\-R <rule_str> |
|
|
|
\fB\-P \fR<\fIpublic key\fR> |
|
|
|
federation public key for user-password authentication |
|
|
|
.TP |
|
|
|
\fB\-R \fR<\fIrule_str\fR> |
|
|
|
Add rule to drop or accept specific packet transmit over edge network interface. |
|
|
|
-R rule_str can be used multiple times to add multiple rules. Each -R rule_str add |
|
|
|
one rule. |
|
|
@ -155,9 +156,40 @@ block traffics. This behavior can be change by add the rule : `0.0.0.0/0:[0,6553 |
|
|
|
traffics. |
|
|
|
|
|
|
|
for example : `-R 0.0.0.0/0,0.0.0.0/0,TCP-,UDP-,ICMP- -R 192.168.100.0/24,192.168.100.0/24,ICMP+`, |
|
|
|
|
|
|
|
\-v |
|
|
|
more verbose logging (may be specified several times for more verbosity). |
|
|
|
.TP |
|
|
|
\fB\-x \fR<\fImetric\fR> |
|
|
|
set TAP interface metric, defaults to 0 (auto), |
|
|
|
e.g. set to 1 for better multiplayer game detection. |
|
|
|
.br |
|
|
|
(Windows only) |
|
|
|
.SH LOCAL OPTIONS |
|
|
|
.TP |
|
|
|
\fB\-f\fR |
|
|
|
do not fork and run as a daemon, rather run in foreground |
|
|
|
.TP |
|
|
|
\fB\-t \fR<\fIport\fR> |
|
|
|
binds the edge management system to the given UDP port. Default 5644. Use this |
|
|
|
if you need to run multiple instance of edge; or something is bound to that |
|
|
|
port. |
|
|
|
.TP |
|
|
|
\fB\-v\fR, \fB\-\-verbose\fR |
|
|
|
make more verbose, repeat as required |
|
|
|
.TP |
|
|
|
\fB\-n \fR<\fIcidr:gateway\fR> |
|
|
|
route an IPv4 network via the gateway, use 0.0.0.0/0 for |
|
|
|
the default gateway, can be set multiple times |
|
|
|
.TP |
|
|
|
\fB\-u \fR<\fIUID\fR>, \fB\-\-euid\fR=<\fIUID\fR> |
|
|
|
numeric user ID to use when privileges are dropped |
|
|
|
.TP |
|
|
|
\fB\-g \fR<\fIGID\fR>, \fB\-\-egid\fR=<\fIGID\fR> |
|
|
|
numeric group ID to use when privileges are dropped |
|
|
|
.TP |
|
|
|
\fb\-h\fr |
|
|
|
write usage then exit. |
|
|
|
.TP |
|
|
|
\fb\--help\fr |
|
|
|
shows detailed parameter description |
|
|
|
.SH ENVIRONMENT |
|
|
|
.TP |
|
|
|
.B N2N_KEY |
|
|
@ -183,52 +215,10 @@ Now you can ping from 192.168.254.5 to 192.168.254.7. |
|
|
|
The MAC address (-m <MAC>) and virtual IP address (-a <addr>) must be different |
|
|
|
on all edges in the same community. |
|
|
|
|
|
|
|
.SH KEY SCHEDULE FILES |
|
|
|
(See |
|
|
|
.B n2n_v2(7) |
|
|
|
for more details). |
|
|
|
|
|
|
|
The -K <keyfile> option reads a key schedule file. |
|
|
|
|
|
|
|
.B edge \-d n2n0 \-c mynetwork \-K /path/to/file \-u 99 \-g 99 \-m DE:AD:BE:EF:01:21 \-a 192.168.254.5 \-p 50001 \-l 123.121.120.119:7654 |
|
|
|
.PP |
|
|
|
|
|
|
|
The key schedule file consists of line, one per key in the schedule. The purpose |
|
|
|
of key schedules is to encourage regular changing of the encryption keys used by |
|
|
|
a community. The file structure also allows for full binary keys to be specified |
|
|
|
as compared to the ASCII keys allowed by the single key injection. Each key line |
|
|
|
consists of the following: |
|
|
|
|
|
|
|
.B <from> <until> <transform> <data> |
|
|
|
|
|
|
|
<from> and <until> are ASCII decimal values of the UNIX times during which the |
|
|
|
key is valid. <transform> is the index of the transform that <data> applies |
|
|
|
to. <data> is some text which is parsed by the transform module to derive the |
|
|
|
key for that line. |
|
|
|
|
|
|
|
Supported <transform> values are: |
|
|
|
.TP |
|
|
|
2 = TwoFish |
|
|
|
<data> has the form <SA>_<hex_key>. eg. |
|
|
|
|
|
|
|
.B 1252327945 1252328305 2 602_3d7c7769b34b2a4812f8c0e9d87ce9 |
|
|
|
|
|
|
|
This specifies security association number 602 and a 16-octet key of numeric |
|
|
|
value 0x3d7c7769b34b2a4812f8c0e9d87ce9. <SA> is a 32-bit unsigned integer which |
|
|
|
is used to identify the encryption key to the receiver. The SA number is sent |
|
|
|
unencrypted so the receiver may find the correct key from the key |
|
|
|
schedule. <hex_key> is up to 16 octets although shorter keys are allowed. |
|
|
|
|
|
|
|
.TP |
|
|
|
3 = AES-CBC |
|
|
|
<data> has the form <SA>_<hex_key>. Same rules as TwoFish. |
|
|
|
|
|
|
|
.SH CLEARTEXT MODE |
|
|
|
If neither |
|
|
|
If |
|
|
|
.B -k |
|
|
|
nor |
|
|
|
.B -K |
|
|
|
is specified then edge uses cleartext mode. In cleartext mode there is no |
|
|
|
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 n2n as packet contents can be seen clearly. |
|
|
|
|
|
|
@ -240,8 +230,7 @@ using the last key that was valid. |
|
|
|
|
|
|
|
.SH MANAGEMENT INTERFACE |
|
|
|
Edge provides a very simple management system on UDP port 5644. Send a newline |
|
|
|
to receive a status output. Send 'reload' to cause re-read of the |
|
|
|
keyfile. Send 'stop' to cause edge to exit cleanly. |
|
|
|
to receive a status output. Send 'stop' to cause edge to exit cleanly. |
|
|
|
|
|
|
|
.SH EXIT STATUS |
|
|
|
edge is a daemon and any exit is an error. |
|
|
@ -256,4 +245,4 @@ deri (at) ntop.org - original author of n2n |
|
|
|
Don Bindner |
|
|
|
(--) - significant contributions to n2n-1 |
|
|
|
.SH SEE ALSO |
|
|
|
ifconfig(8) supernode(1) tunctl(8) n2n_v2(7) |
|
|
|
ifconfig(8) supernode(1) tunctl(8) n2n(7) |
|
|
|