billchenchina/n2n
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

New upstream version 3.1.1

Browse source
This commit is contained in:
billchenchina 2022-11-15 08:50:35 +08:00
parent 4e9934e5ec
commit e7b41df57b
229 changed files with 57000 additions and 12055 deletions
Download patch file Download diff file Expand all files Collapse all files

310
edge.8
View file

@ -1,100 +1,244 @@
.TH edge 1 "Jan 3, 2009" "revision 3679" "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> \-l <supernode host:port>
[\-p <local port>] [\-u <UID>] [\-g <GID>] [-f] [\-m <MAC address>] [\-t] [\-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
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
\-d <name>
sets the TAP device name as seen in ifconfig.
\fB\-c \fR<\fIcommunity\fR>, \fB\-\-community\fR=<\fIcommunity\fR>
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).
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
\-a <addr>
sets the n2n virtual LAN IP address being claimed. This is a private IP
address. All IP addresses in an n2n community should belong to the same /24
network (ie. only the last segment of the IP addresses varies).
\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
\-b
cause edge to perform hostname resolution for the supernode address each time
the supernode is periodically contacted.
.TP
\-c <community>
sets the n2n community name. All edges within the same community look to be on
the same LAN (layer 2 network segment). All edges communicating must use the
same key and community name.
.TP
\-h
write usage to tty then exit.
.TP
\-k <keystring>
sets the twofish encryption key from ASCII text (see also N2N_KEY in
ENVIRONMENT). All edges communicating must use the same key and community name.
.TP
\-l <addr>:<port>
sets the n2n supernode IP address and port to register to.
.TP
\-p <num>
\fB\-p \fR[<\fIlocal_ip_address\fR>:]<\fIlocal_port\fR>
binds edge to the given UDP port. Useful for keeping the same external socket
across restarts of edge.
across restarts of edge. This allows peer edges which know the edge socket to
continue p2p operation without going back to the supernode. Also, home router's
port forwarding feature can refer to that fixed port.
Optionally, the edge can bind to the provided local ip address only. This is
useful in case restriction to a certain LAN or WiFi interface is desired.
By default, the edge binds to any interface.
.TP
\-u <uid>
causes the edge process to drop to the given user ID when privileges are no
longer required.
\fB\-T \fR<\fItos\fR>
TOS for packets, e.g. 0x48 for SSH like priority
.TP
\-g <gid>
causes the edge process to drop to the given group ID when privileges are no
longer required.
\fB\-D\fR
enable PMTU discovery, it can reduce fragmentation but
causes connections to stall if not properly supported
.TP
\-f
causes the edge process to fork and run as a daemon, closing stdin, stdout,
stderr and becoming a process group leader.
\fB\-e \fR<\fIlocal_ip_address\fR>
advertises the provided local IP address as preferred,
useful if multicast peer detection is not available, e.g.
disabled on routers. \fB\-e auto\fR tries auto-detection of
local IP address.
.TP
\-m <MAC>
\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 encryption key from ASCII text (see also N2N_KEY in
ENVIRONMENT). All edges communicating must use the same key and community
name. If -k not specified then edge uses cleartext mode (no encryption).
.TP
\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
\fB\-H\fR
use header encryption, supernode needs fixed community
.TP
\fB\-z1\fR ... \fB\-z2\fR
compress outgoing data packets, -z1 = lzo1x, disabled by default
.TP
\fB\-\-select-rtt\fR
select supernode by round trip time if several to choose from (federation),
defaults to load-based selection strategy if not provided.
.TP
\fB\-\-select-mac\fR
select supernode by MAC address if several to choose from (federation),
lowest MAC address first.
.TP
\fB\-\-no-port-forwarding\fR
disables the default behavior of trying to have the edge's port forwarded
through a router eventually supporting it (only if compiled with miniupnp
and/or natpmp library support).
.SH TAP DEVICE AND OVERLAY NETWORK CONFIGURATION
.TP
\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
\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
\-t
use HTTP tunneling instead of the normal UDP mechanism (experimental).
\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
\-r
enable packet forwarding/routing through the n2n virtual LAN. Without this
option, packets arriving over n2n which are not for the -a <addr> IP address are
dropped.
\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
\-v
use verbose logging.
\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 (see also N2N_PASSWORD in ENVIRONMENT)
.TP
\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.
rule_str format:"src_ip/len:[b_port,e_port],dst_ip/len:[s_port,e_port],TCP+/-,UDP+/-,ICMP+/-".
ip/len indicate a cidr block, len can be ignore, means single ip(not 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.
Ports range [s_port,e_port] can be instead by single port number. 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) will be selected. That
means rules with larger len value has higher priority.
Packets that cannot match any rule will be accepted by default. Users can add rules to
block traffics. 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, users need add rules to allow
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+`,
.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\-\-management-password \fR<\fIpassword\fR>
sets the password for access to JSON API at the management port, defaults 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.
.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
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
.TP
.B N2N_COMMUNITY
set the community name so it is not visible at the command line
.TP
.B N2N_PASSWORD
set the password for user-password authentication so it is not visible at the command line
.SH EXAMPLES
.TP
.B 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
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 shared encryption key. Assign MAC address
DE:AD:BE:EF:01:23 to the n2n interface and drop to user=99 and group=99 after
the TAP device is successfull configured.
50001. Use "encryptme" as the single permanent shared encryption key. Assign MAC
address DE:AD:BE:EF:01:23 to the n2n interface and drop to user=99 and group=99
after the TAP device is successfully configured.
.PP
Add the -f option to make edge run as a daemon.
Add the -f option to stop edge running as a daemon.
.PP
Somewhere else setup another edge with similar parameters, eg.
@ -102,15 +246,45 @@ Somewhere else setup another edge with similar parameters, eg.
.PP
Now you can ping from 192.168.254.5 to 192.168.254.7.
.PP
The MAC address (-m <MAC>) and virtual IP address (-a <addr>) must be different on all edges in the same community.
The MAC address (-m <MAC>) and virtual IP address (-a <addr>) 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 n2n 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 provides a very simple management system on UDP port 5644. Send a newline
to receive a status output. Send 'stop' to cause edge to exit cleanly.
.TP
.B echo | nc -w1 -u 127.0.0.1 5644
Shows the current statistics of a running edge.
.SH CONFIGURATION
All configuration for edge is from the command line and environment
variables. If you wish to reconfigure edge you should kill the process and
restart with the desired options.
.SH EXIT STATUS
edge is a daemon and any exit is an error.
.SH AUTHOR
Luca Deri ( deri (at) ntop.org ), Richard Andrews ( andrews (at) ntop.org ), Don Bindner
.SH AUTHORS
.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(1) tunctl(8)
ifconfig(8) supernode(1) tunctl(8) n2n(7)
.br
the documentation contained in the source code
.br
the extensive documentation found in n2n's \fBdoc/\fR folder