"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "edge.8" between
n2n-2.8.tar.gz and n2n-3.0.tar.gz

About: n2n is a layer-two peer-to-peer virtual private network (VPN) which allows bypassing intermediate firewalls.

[ To the main n2n source changes report ]

edge.8  (n2n-2.8):edge.8  (n2n-3.0)
edge(8) SUPERUSER COMMANDS edge(8) edge(8) SUPERUSER COMMANDS edge(8)
NAME NAME
edge - n2n edge node daemon edge - n2n edge node daemon
SYNOPSIS SYNOPSIS
edge [-d <tun device>] -a <tun IP address> -c <community> {-k <encrypt k edge <config file>
ey>|-K <keyfile>} [-s <netmask>] edge -c <community> -l <supernode host:port> [further options]...
-l <supernode host:port> [-L <reg_ttl>] [-p <local port>] [-u <UID>] [-g
<GID>] [-f] [-m <MAC address>]
[-r] [-v]
DESCRIPTION DESCRIPTION
N2N is a peer-to-peer VPN system. Edge is the edge node daemon for n2n which creates a TAP interface to 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 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. with the supernode so it can begin to find other nodes in the community.
OPTIONS The config file is similar to the command line, with one option per line
-d <name> . Lines starting with a "#" are
sets the TAP device name as seen in ifconfig. Only available on Li ignored. An equal sign ('=') should be used between key and value. Examp
nux. le: -p=7777
-a {<addr>|static:<addr>|dhcp:0.0.0.0}
sets the n2n virtual LAN IP address being claimed. This is a priv
ate IP address. All IP addresses
in an n2n community typical belong to the same /24 network (ie. on
ly the last octet of the IP
addresses varies). If DHCP is used to assign interface addresse
s then specify the address as -a
dhcp:0.0.0.0
-b cause edge to perform hostname resolution for the supernode addres
s each time the supernode is
periodically contacted. This can cause reliability problems bec
ause all packet processing stops
while the supernode address is resolved which might take 15 second
s.
-c <community>
sets the n2n community name. All edges within the same community a
ppear 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 fi
rst 16 bytes.
-h write usage then exit. OPTIONS FOR THE UNDERLYING NETWORK CONNECTION
-c <community>, --community=<community>
sets the n2n community name (see also N2N_COMMUNITY in ENVIRONMENT
). All edges within the same
community appear on the same LAN (layer 2 network segment). Commu
nity name is 16 bytes in length.
A name smaller than this is padded with 0x00 bytes and a name long
er than this is truncated to
take the first 16 bytes.
-l <host:port>, --supernode-list=<host:port>
sets the n2n supernode IP address and port to register to. Multipl
e supernodes can be specified.
-p [<local_ip_address>:]<local_port>
binds edge to the given UDP port. Useful for keeping the same ex
ternal socket across restarts of
edge. This allows peer edges which know the edge socket to continu
e p2p operation without going
back to the supernode. Also, home router's port forwarding featu
re can refer to that fixed port.
Optionally, the edge can bind to the provided local ip address o
nly. This is useful in case
restriction to a certain LAN or WiFi interface is desired. B
y default, the edge binds to any
interface.
-T <tos>
TOS for packets, e.g. 0x48 for SSH like priority
-D enable PMTU discovery, it can reduce fragmentation but causes conn
ections to stall if not properly
supported
-i <register_interval> -e <local_ip_address>
advertises the provided local IP address as preferred, useful if
multicast peer detection is not
available, e.g. disabled on routers. -e auto tries auto-detection
of local IP address.
-S1 ... -S2
do not connect p2p, always use the supernode, -S1 = via UDP, -S2 =
via TCP
-i <reg_interval>
Supernode registration interval. It specifies the interval in seco nds between consecutive REGIS- Supernode registration interval. It specifies the interval in seco nds between consecutive REGIS-
TER_SUPER packets and it's used to keep NAT hole open via the UDP NAT hole punching technique. TER_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 communicati on. This only works for asymmetric NATs and allows for P2P communicati on.
-k <keystring> -L <reg_ttl>
sets the twofish encryption key from ASCII text (see also N2N_KEY set the TTL for the hole punching packet. This is an advanced flag
in ENVIRONMENT). All edges com- to make sure that the registra-
municating must use the same key and community name. If neither -k tion packet is dropped immediately when it goes out of local nat
nor -K is used to specify a key so that it will not trigger some
source then edge uses cleartext mode (no encryption). The -k and - firewall behavior on target peer. Actually, the registration pack
K options are mutually exclu- et is only expected to make
sive. local nat UDP hole and is not expected to re
ach the target peer, see
-K <keyfile> https://tools.ietf.org/html/rfc5389. To achieve this, the flag sho
Reads a key-schedule file <keyfile> and populates the internal tr uld be set as nat level + 1. For
ansform operations with the data example, if we have 2 layer nat in local, we should set -L 3.
found there. This mechanism allows keys to roll at pre-determined Usually we know exactly how much
times for a group of hosts. nat layers in local. If we are not sure how much nat layers in lo
Accurate time synchronisation is not required as older keys ca cal, we can use traceroute on
n be decoded for some time after Linux to check. The following example shows a local single lay
expiry. If neither -k nor -K is used to specify a key source then er nat because on second jump it
edge uses cleartext mode (no shows a public ip address. In this case it should set -L 2.
encryption). The -k and -K options are mutually exclusive.
$ /usr/sbin/traceroute -w1 8.8.8.8
-l <addr>:<port> traceroute to 8.8.8.8 (8.8.8.8), 30 hops max, 60 byte packets
sets the n2n supernode IP address and port to register to. Up to 1 192.168.3.1 (192.168.3.1) 0.464 ms 0.587 ms 0.719 ms
2 supernodes can be specified by 2 112.65.17.217 (112.65.17.217) 5.269 ms 7.031 ms 8.666 ms
two invocations of -l <addr>:<port>. eg. edge -l 12.34.56.78:7654
-l 98.76.54.32:7654
-p <num>
binds edge to the given UDP port. Useful for keeping the same exte
rnal socket across restarts of
edge. This allows peer edges which know the edge socket to cont
inue p2p operation without going
back to the supernode.
-t <num> But this method does not always work due to various local network
binds the edge management system to the given UDP port. Default 56 device policy.
44. Use this if you need to run
multiple instance of edge; or something is bound to that port. -k <key>
encryption key (ASCII) - also N2N_KEY=<key> -k <keystring> sets th
e encryption key from ASCII text
(see also N2N_KEY in ENVIRONMENT). All edges communicating mus
t use the same key and community
name. If -k not specified then edge uses cleartext mode (no encryp
tion).
-u <uid> -A1 disable payload encryption, do not use with key, defaults to AES t
causes the edge process to drop to the given user ID when p hen
rivileges are no longer required
(UNIX).
-g <gid> -A2 ... -A5
causes the edge process to drop to the given group ID when privi choose a cipher for payload encryption, requires a key, -A2 = Twof
leges are no longer required ish, -A3 = AES (default if key
(UNIX). provided), -A4 = ChaCha20, -A5 = Speck-CTR
-f disables daemon mode (UNIX) and causes edge to run in the foregrou nd. -H use header encryption, supernode needs fixed community
-m <MAC> -z1 ... -z2
compress outgoing data packets, -z1 = lzo1x, disabled by default
--select-rtt
select supernode by round trip time if several to choose from (fed
eration), defaults to load-based
selection strategy if not provided.
TAP DEVICE AND OVERLAY NETWORK CONFIGURATION
-a [mode]<ip>[/n]
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
-m <mac>
start the TAP interface with the given MAC address. This is hi ghly recommended as it means the start the TAP interface with the given MAC address. This is hi ghly recommended as it means the
same address will be used if edge stops and restarts. If this is n ot done, the ARP caches of all same address will be used if edge stops and restarts. If this is n ot done, the ARP caches of all
peers will be wrong and packets will not flow to this edge until t peers will be wrong and packets will not flow to this edge until
he next ARP refresh. the next ARP refresh. e.g. '-m
10:20:30:40:50:60', by default a random MAC address is used.
-d <device>, --device=<device>
TAP device name
-M <MTU> -M <mtu>
set the MTU of the edge interface in bytes. MTU is the largest pa specify n2n MTU of TAP interface, default 1290
cket fragment size allowed to be
moved throught the interface. The default is 1400.
-s <netmask>
set the netmask of edge interface in IPv4 dotted decimal notation.
The default is 255.255.255.0
(ie. /24).
-r enable IP packet forwarding/routing through the n2n virtual LAN. -r enable IP packet forwarding/routing through the n2n virtual LAN. W
Without this option, IP packets ithout this option, IP packets
arriving over n2n are dropped if not for the -a <addr> (or DHCP as arriving over n2n are dropped if not for the -a <addr> (or DHCP
signed) IP address of the edge assigned) IP address of the edge
interface. interface.
-E accept packets destined for multicast ethernet MAC addresses. Th -E accept packets destined for multicast ethernet MAC addresses. Thes
ese addresses are used in multi- e addresses are used in multi-
cast ethernet and IPv6 neighbour discovery. If this option is not cast ethernet and IPv6 neighbour discovery. If this option is not
present these multicast packets present these multicast packets
are discarded as most users do not need or understand them. are discarded as most users do not need or understand them.
-L set the TTL for the hole punching packet. This is an advanced flag -I <description>
to make sure that the registra- annotate the edge's description used for easier identification in
tion packet is dropped immediately when it goes out of local nat s management port output or user-
o that it will not trigger some name
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 sho
uld be set as nat level + 1. For
example, if we have 2 layer nat in local, we should set -L 3. Usu
ally 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 n
at 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) -J <password>
, 30 hops max, 60 byte packets password for user-password edge authentication (see also N2N_PASSW
1 192.168.3.1 (192.168.3.1) 0.464 ms 0.587 ms 0.719 ms ORD in ENVIRONMENT)
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 -P <public key>
device policy. federation public key for user-password authentication
-R <rule_str>
Add rule to drop or accept specific packet transmit over edge net
work interface. -R rule_str can
be used multiple times to add multiple rules. Each -R rule_str add
one rule.
rule_str format:"src_ip/len:[b_port,e_port],dst_ip/len:[s_port,e_p
ort],TCP+/-,UDP+/-,ICMP+/-".
ip/len indicate a cidr block, len can be ignore, means single ip(n
ot cidr block) will be use in
filter rule.
+,- after TCP,UDP,ICMP proto type indicate allow or drop packet
of that proto. if any of above
three proto missed, the rule will not take effect for that proto.
-v more verbose logging (may be specified several times for more verb Ports range [s_port,e_port] can be instead by single port number.
osity). If not specify, [0,65535] will
be used. Ports range include start_port and end_port. If multiple
rules matching packet's ips and
ports, the rule with smaller cidr block(smaller address space) wil
l be selected. That means rules
with larger len value has higher priority.
Packets that cannot match any rule will be accepted by default. Us
ers can add rules to block traf-
fics. This behavior can be change by add the rule :
`0.0.0.0/0:[0,65535],0.0.0.0/0:
[0,65535],TCP-,UDP-,ICMP-`. Then all traffic will be dropped, use
rs need add rules to allow traf-
fics.
for example : `-R 0.0.0.0/0,0.0.0.0/0,TCP-,UDP-,ICMP- -R 192.168.1
00.0/24,192.168.100.0/24,ICMP+`,
-x <metric>
set TAP interface metric, defaults to 0 (auto), e.g. set to 1 for
better multiplayer game detec-
tion.
(Windows only)
LOCAL OPTIONS
-f do not fork and run as a daemon, rather run in foreground
-t <port>
binds the edge management system to the given UDP port. Default 5
644. Use this if you need to run
multiple instance of edge; or something is bound to that port.
--management-password <password>
sets the password for access to JSON API at the management port, d
efaults to 'n2n'. The password
has to be provided when using 'scripts/n2n-ctl', 'scripts/n2n-
httpd' or for any other relevant
access to JSON API at the management port.
-v, --verbose
make more verbose, repeat as required
-n <cidr:gateway>
route an IPv4 network via the gateway, use 0.0.0.0/0 for the defau
lt gateway, can be set multiple
times
-u <UID>, --euid=<UID>
numeric user ID to use when privileges are dropped
-g <GID>, --egid=<GID>
numeric group ID to use when privileges are dropped
-h write usage then exit.
--help shows detailed parameter description
ENVIRONMENT ENVIRONMENT
N2N_KEY N2N_KEY
set the encryption key so it is not visible on the command line set the encryption key so it is not visible at the command line
N2N_COMMUNITY
set the community name so it is not visible at the command line
N2N_PASSWORD
set the password for user-password authentication so it is not vis
ible at the command line
EXAMPLES EXAMPLES
edge -d n2n0 -c mynetwork -k encryptme -u 99 -g 99 -m DE:AD:BE:EF:01 :23 -a 192.168.254.7 -p 50001 -l edge -d n2n0 -c mynetwork -k encryptme -u 99 -g 99 -m DE:AD:BE:EF:01 :23 -a 192.168.254.7 -p 50001 -l
123.121.120.119:7654 123.121.120.119:7654
Start edge with TAP device n2n0 on community "mynetwork" with community supernode at Start edge with TAP device n2n0 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 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:B E:EF:01:23 to the n2n interface single permanent shared encryption key. Assign MAC address DE:AD:B E:EF:01:23 to the n2n interface
and drop to user=99 and group=99 after the TAP device is successfu ll configured. and drop to user=99 and group=99 after the TAP device is successfu lly configured.
Add the -f option to stop edge running as a daemon. Add the -f option to stop edge running as a daemon.
Somewhere else setup another edge with similar parameters, eg. Somewhere else setup another edge with similar parameters, eg.
edge -d n2n0 -c mynetwork -k encryptme -u 99 -g 99 -m DE:AD:BE:EF:01 :21 -a 192.168.254.5 -p 50001 -l edge -d n2n0 -c mynetwork -k encryptme -u 99 -g 99 -m DE:AD:BE:EF:01 :21 -a 192.168.254.5 -p 50001 -l
123.121.120.119:7654 123.121.120.119:7654
Now you can ping from 192.168.254.5 to 192.168.254.7. 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 dif ferent on all edges in the same The MAC address (-m <MAC>) and virtual IP address (-a <addr>) must be dif ferent on all edges in the same
community. community.
KEY SCHEDULE FILES
(See n2n_v2(7) for more details).
The -K <keyfile> option reads a key schedule file.
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
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. Th
e 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:
<from> <until> <transform> <data>
<from> and <until> are ASCII decimal values of the UNIX times during whi
ch the key is valid. <transform>
is the index of the transform that <data> applies to. <data> is some text
which is parsed by the trans-
form module to derive the key for that line.
Supported <transform> values are:
2 = TwoFish
<data> has the form <SA>_<hex_key>. eg.
1252327945 1252328305 2 602_3d7c7769b34b2a4812f8c0e9d87ce9
This specifies security association number 602 and a 1
6-octet key of numeric value
0x3d7c7769b34b2a4812f8c0e9d87ce9. <SA> is a 32-bit unsigned intege
r which is used to identify the
encryption key to the receiver. The SA number is sent unencryp
ted so the receiver may find the
correct key from the key schedule. <hex_key> is up to 16 octets al
though shorter keys are allowed.
3 = AES-CBC
<data> has the form <SA>_<hex_key>. Same rules as TwoFish.
CLEARTEXT MODE CLEARTEXT MODE
If neither -k nor -K is specified then edge uses cleartext mode. In clear If -k is not specified then edge uses cleartext mode. In cleartext m
text mode there is no transform ode there is no transform of the
of the packet data it is simply encrypted. This is useful for debuggi packet data it is simply encrypted. This is useful for debugging n2n as
ng n2n as packet contents can be packet contents can be seen
seen clearly. clearly.
To prevent accidental exposure of data, edge only enters cleartext mode w To prevent accidental exposure of data, edge only enters cleartext mo
hen no keying parameters are de when no keying parameters are
specified. In the case where keying parameters are specified but no va specified. In the case where keying parameters are specified but no valid
lid keys can be determined, edge keys can be determined, edge
exits with an error at startup. If all keys become invalid while running, exits with an error at startup. If all keys become invalid while running
edge continues to encode using , edge continues to encode using
the last key that was valid. the last key that was valid.
MANAGEMENT INTERFACE MANAGEMENT INTERFACE
Edge provides a very simple management system on UDP port 5644. Send a Edge provides a very simple management system on UDP port 5644. Send a ne
newline to receive a status out- wline to receive a status out-
put. Send 'reload' to cause re-read of the keyfile. Send 'stop' to cause put. Send 'stop' to cause edge to exit cleanly.
edge to exit cleanly.
echo | nc -w1 -u 127.0.0.1 5644
Shows the current statistics of a running edge.
EXIT STATUS EXIT STATUS
edge is a daemon and any exit is an error. edge is a daemon and any exit is an error.
AUTHORS AUTHORS
Richard Andrews Richard Andrews
andrews (at) ntop.org - n2n-1 maintainer and main author of n2n-2 andrews (at) ntop.org - n2n-1 maintainer and main author of n2n-2
Luca Deri Luca Deri
deri (at) ntop.org - original author of n2n deri (at) ntop.org - original author of n2n
Don Bindner Don Bindner
(--) - significant contributions to n2n-1 (--) - significant contributions to n2n-1
SEE ALSO SEE ALSO
ifconfig(8) supernode(1) tunctl(8) n2n_v2(7) ifconfig(8) supernode(1) tunctl(8) n2n(7)
the documentation contained in the source code
the extensive documentation found in n2n's doc/ folder
n2n-2.1 17 Mar 2010 edge(8) version 3 18 Jul 2021 edge(8)
 End of changes. 25 change blocks. 
188 lines changed or deleted 235 lines changed or added
To the Man Pages (all 2): section of the n2n source changes report or the top of this page
Mainly generated by pkgdiff using rfcdiff
Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)