edge(8)

📦
version 3.1.1 · 5 versions
, in alpine 3.24, arch rolling, fedora 44, nixpkgs unstable

💖 edge(8) — SUPERUSER COMMANDS 💖

okay bestie, gather round, because today we're talking about edge, the n2n edge node daemon. yes, that's the manual section 8, the superuser-commands one, and no, we're not scared of it. we're gonna read this whole thing together and by the end you're gonna be the main character of your own VPN. ✨

✨ NAME ✨

edge — the n2n edge node daemon, aka the little guy that makes your virtual LAN happen 💅

✨ SYNOPSIS ✨

edge <config file>
edge -c <community> -l <supernode host:port> [further options]...

like, two whole ways to start her up. either you hand her a config file, or you go raw on the command line with a community and a supernode. choose your fighter 🎀

✨ DESCRIPTION ✨

so N2N is a peer-to-peer VPN system, right? and edge is the edge node daemon for n2n — she creates a TAP interface to expose the n2n virtual LAN. on startup, n2n creates that TAP interface, configures it, and then registers with the supernode so she can start finding all the other nodes in the community. it's giving "networking but make it social" 🦋

the config file is basically the command line but in a file, with one option per line. any line starting with a "#" gets ignored (comments, we love her). and you should put an equal sign (=) between the key and the value. example: -p=7777

🌈 OPTIONS FOR THE UNDERLYING NETWORK CONNECTION 🌈

this whole section is about how edge talks to the outside world. buckle up, there's a lot, but every single one matters, no cap.

  • -c <community>, --community=<community> — sets the n2n community name (peep N2N_COMMUNITY in ENVIRONMENT too 👀). every edge in the same community shows up on the same LAN (that's a layer 2 network segment, bestie). the community name is 16 bytes long. shorter names get padded with 0x00 bytes, longer names get truncated down to the first 16 bytes. she's strict like that 💅
  • -l <host:port>, --supernode-list=<host:port> — sets the n2n supernode IP address and port to register to. and yes, you can specify multiple supernodes. go off queen 👑
  • -p [<local_ip_address>:]<local_port> — binds edge to the given UDP port. super useful for keeping the same external socket across restarts of edge, which means peer edges that already know the edge socket can keep doing p2p operation without running back to the supernode. also, your home router's port forwarding feature can point at that fixed port. optionally you can bind to just the provided local ip address — handy when you wanna restrict her to a certain LAN or WiFi interface. by default, edge binds to any interface. she's flexible ✨
  • -T <tos> — TOS for packets, e.g. 0x48 for that SSH-like priority 🏃♀️
  • -D — enable PMTU discovery. it can reduce fragmentation, but heads up: it causes connections to stall if it's not properly supported. risky but cute
  • -e <local_ip_address> — advertises the provided local IP address as preferred. useful when multicast peer detection isn't available, like when it's disabled on routers. and -e auto tries auto-detection of the local IP address. self-care 🫶
  • -S1 ... -S2 — do not connect p2p, always use the supernode. -S1 = via UDP, -S2 = via TCP. sometimes you just want the reliable one, and that's valid
  • -i <reg_interval> — Supernode registration interval. it sets the interval in seconds between consecutive REGISTER_SUPER packets, and it's used to keep the NAT hole open via the UDP NAT hole punching technique. this only works for asymmetric NATs and allows for P2P communication. it's giving "holding the door open for your friends" 🚪
  • -L <reg_ttl> — set the TTL for the hole punching packet. this is an advanced flag to make sure the registration packet is dropped immediately when it goes out of local nat, so it won't trigger some firewall behavior on the target peer. actually, the registration packet is only expected to make the 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 many nat layers are in local. if we're not sure, we can use traceroute on Linux to check. the example below shows a local single layer nat because on the 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 bestie, this method does not always work, due to various local network device policy 😭
  • -k <key> — encryption key (ASCII) — also N2N_KEY=<key> — -k <keystring> sets the encryption key from ASCII text (see N2N_KEY in ENVIRONMENT too). every edge that's communicating must use the same key and the same community name. if -k is not specified then edge uses cleartext mode (no encryption). protect yourself, babes 🔐
  • -A1 — disable payload encryption. do not use with key, it defaults to AES then. pick a lane 💀
  • -A2 ... -A5 — choose a cipher for payload encryption. requires a key. -A2 = Twofish, -A3 = AES (default if key provided), -A4 = ChaCha20, -A5 = Speck-CTR. cipher menu, pick your fave 🎀
  • -H — use header encryption. supernode needs a fixed community. no takebacks
  • -z1 ... -z2 — compress outgoing data packets. -z1 = lzo1x, disabled by default. squeeze that data, she's on a diet ✨
  • --select-rtt — select supernode by round trip time if there's several to choose from (federation). defaults to a load-based selection strategy if this isn't provided.
  • --select-mac — select supernode by MAC address if there's several to choose from (federation). lowest MAC address first. alphabetical but make it MAC 🦋
  • --no-port-forwarding — disables the default behavior of trying to have the edge's port forwarded through a router that eventually supports it (only if compiled with miniupnp and/or natpmp library support). sometimes you just don't want the router in your business 🙈

🌸 TAP DEVICE AND OVERLAY NETWORK CONFIGURATION 🌸

okay this is the part where we set up the actual interface — the vibes of your virtual network, if you will 💜

  • -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 the IP address from the supernode if no -a ... is given. she'll find herself, don't worry 🧚
  • -m <mac> — start the TAP interface with the given MAC address. this is highly recommended because it means the same address will be used if edge stops and restarts. if you don't do this, 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, and by default a random MAC address is used. bestie please set your MAC, it's giving stability 💅
  • -d <device>, --device=<device> — TAP device name
  • -M <mtu> — specify n2n MTU of TAP interface, default 1290
  • -r — enable IP packet forwarding/routing through the n2n virtual LAN. without this option, IP packets arriving over n2n are dropped if they're not for the -a <addr> (or DHCP assigned) IP address of the edge interface. turn it on if you want her to route, periodt
  • -E — 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, because most users do not need or understand them. ngl if you know, you know 😌
  • -I <description> — annotate the edge's description, used for easier identification in management port output or username. name your child 🎀
  • -J <password> — password for user-password edge authentication (see N2N_PASSWORD in ENVIRONMENT too)
  • -P <public key> — federation public key for user-password authentication 🔑
  • -R <rule_str> — add a rule to drop or accept specific packet transmit over the edge network interface. -R rule_str can be used multiple times to add multiple rules. each -R rule_str adds one rule. okay this one's a whole thing, so let's break it down:
    • rule_str format: "src_ip/len:[b_port,e_port],dst_ip/len:[s_port,e_port],TCP+/-,UDP+/-,ICMP+/-"
    • ip/len indicates a cidr block. len can be ignored, which means a single ip (not a cidr block) will be used in the filter rule.
    • the +/- after the TCP, UDP, ICMP proto type indicates allow or drop packets of that proto. if any of the above three protos is missing, the rule will not take effect for that proto.
    • ports range [s_port,e_port] can be replaced by a single port number. if not specified, [0,65535] will be used. the ports range includes start_port and end_port. if multiple rules match a packet's ips and ports, the rule with the smaller cidr block (smaller address space) will be selected. that means rules with a larger len value have higher priority.
    • packets that cannot match any rule will be accepted by default. users can add rules to block traffic. this behavior can be changed by adding 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, and users need to add rules to allow traffic.
    • 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+
  • -x <metric> — set TAP interface metric, defaults to 0 (auto), e.g. set to 1 for better multiplayer game detection. (Windows only) — gamer girl option fr fr 🎮

✨ LOCAL OPTIONS ✨

the "how edge runs on this machine" section. housekeeping but make it cute 🧹

  • -f — do not fork and run as a daemon, rather run in foreground. she stays right there with you 🫶
  • -t <port> — binds the edge management system to the given UDP port. default 5644. use this if you need to run multiple instances of edge, or if something else is already bound to that port. port drama, we've all been there 💀
  • --management-password <password> — sets the password for access to the 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 the JSON API at the management port. change the default bestie, i'm begging 🙈
  • -v, --verbose — make more verbose. repeat as required. the more -vs, the more she tells you 👀
  • -n <cidr:gateway> — route an IPv4 network via the gateway, use 0.0.0.0/0 for the default gateway. can be set multiple times. routing but make it repeatable 🦋
  • -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. short and sweet ✨
  • --help — shows detailed parameter description. she's thorough

🌈 ENVIRONMENT 🌈

all the ways to keep your secrets off the command line, because your shell history is not a diary 💅

  • N2N_KEY — 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 visible at the command line
part 1 done bestie, but we're not finished — more parts are coming, so stay tuned 💖

🌸 EXAMPLES 🌸

okay bestie here's the whole thing in action, a real full command, look at her go 💅

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

so what is actually happening here: you're starting edge with the TAP device n2n0 on community "mynetwork", pointing at the community supernode at 123.121.120.119 on UDP port 7654, and binding the locally used UDP port to 50001. you're using "encryptme" as the single permanent shared encryption key. you assign the MAC address DE:AD:BE:EF:01:23 to the n2n interface, and then you drop to user=99 and group=99 after the TAP device is successfully configured. slay, privilege drop, iconic behavior 👑

now, add the -f option to stop edge running as a daemon. no cap, that's the whole tip.

somewhere else, set up another edge with similar parameters, like this:

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

and now? you can ping from 192.168.254.5 to 192.168.254.7. literally that's it, that's the friendship 🫶

⚠️ bestie PLEASE — the MAC address (-m <MAC>) and the virtual IP address (-a <addr>) must be different on all edges in the same community. no two edges can be twinsies here. don't do it. it's giving identity crisis and it will not end well 💀

🌈 CLEARTEXT MODE 🌈

so 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 n2n, because you can see the packet contents 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. and if all keys become invalid while running, edge continues to encode using the last key that was valid. she remembers, she persists, main character energy fr fr 💜

🎀 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. yes, that's the whole API. minimal. chic. obsessed. 💅

echo | nc -w1 -u 127.0.0.1 5644

shows the current statistics of a running edge. that's it, that's the flex 📊✨

⭐ EXIT STATUS ⭐

edge is a daemon and any exit is an error. so if she leaves the chat, something went wrong. no gentle goodbyes here, bestie 😭

👑 AUTHORS 👑

  • 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

legend behavior from all three, respectfully 🙌

🦋 SEE ALSO 🦋

go read them, iykyk 📚💖

and that's the whole page bestie!! this was version 3, dated 18 Jul 2021, and it lives at edge(8) 🎀✨ go forth and tunnel responsibly, you absolute icon 🫶🌈

📦 where this page comes from