ANYTUN(8)

👑 anytun(8) — the manual page, but make it cute 💖

okay bestie, sit down, hydrate, because we're about to get into anytun(8) and it's honestly kind of a big deal. no cap.

---

✨ NAME ✨

anytun — the anycast tunneling daemon 🦋

like, it's a daemon. it tunnels. it does it via anycast. that's the whole vibe. periodt.

---

🌸 SYNOPSIS 🌸

anytun
  [ -h|--help ]
  [ -D|--nodaemonize ]
  [ -u|--username <username> ]
  [ -g|--groupname <groupname> ]
  [ -C|--chroot <path> ]
  [ -P|--write-pid <filename> ]
  [ -L|--log <target>:<level>[,<param1>[,<param2>[..]]] ]
  [ -U|--debug ]
  [ -i|--interface <ip-address> ]
  [ -p|--port <port> ]
  [ -r|--remote-host <hostname|ip> ]
  [ -o|--remote-port <port> ]
  [ -4|--ipv4-only ]
  [ -6|--ipv6-only ]
  [ -I|--sync-interface <ip-address> ]
  [ -S|--sync-port port> ]
  [ -M|--sync-hosts <hostname|ip>[:<port>][,<hostname|ip>[:<port>][...]] ]
  [ -X|--control-host <hostname|ip>[:<port>]
  [ -d|--dev <name> ]
  [ -t|--type <tun|tap> ]
  [ -n|--ifconfig <local>/<prefix> ]
  [ -x|--post-up-script <script> ]
  [ -R|--route <net>/<prefix length> ]
  [ -m|--mux <mux-id> ]
  [ -s|--sender-id <sender id> ]
  [ -w|--window-size <window size> ]
  [ -k|--kd-prf <kd-prf type> ]
  [ -e|--role <role> ]
  [ -E|--passphrase <pass phrase> ]
  [ -K|--key <master key> ]
  [ -A|--salt <master salt> ]
  [ -c|--cipher <cipher type> ]
  [ -a|--auth-algo <algo type> ]
  [ -b|--auth-tag-length <length> ]

like, that's a lot of brackets, and yes, every single one of them matters. don't skip any. 💅

---

🎀 DESCRIPTION 🎀

okay so, Anytun is an implementation of the Secure Anycast Tunneling Protocol (SATP). it's giving "I built a whole VPN" energy.

it provides a complete VPN solution similar to OpenVPN or IPsec in tunnel mode. same league, different flavor. 🧚

but here's the thing that makes it iconic — the main difference is that anycast allows a setup of tunnels between an arbitrary combination of anycast, unicast and multicast hosts. like. any mix. any combo. that's the whole point. that's the main character energy right there. 👑

---

okay bestie, that's part 1 down. there's more coming, don't go anywhere 💜

✨ OPTIONS ✨

okay so bestie, here's the tea: Anytun was built as a peer to peer application, so there's literally no difference between client and server. it's giving egalitarian. 💅 The following options can be passed to the daemon:

---

• -D, --nodaemonize — this one tells Anytun to run in the foreground instead of becoming a daemon (which is, btw, the default). great for when you wanna actually see what's happening. 👀
• -u, --username <username> — run as this user. if you don't also give a group with -g, the default group of that user gets used. the default is to not drop privileges at all.
• -g, --groupname <groupname> — run as this group. heads up: if you don't pass a username with -u too, this one just gets ignored. 😭 the default is, again, to not drop privileges.
• -C, --chroot <path> — tell Anytun to run inside a chroot jail. default: no chroot, we're free-range. 🐓
• -P, --write-pid <filename> — makes Anytun write its pid into this file. default: no pid file gets created.
• -L, --log <target>:<level>[,<param1>[,<param2>[..]]] — adds a log target to the logging system. you can hit this one multiple times to log to different targets at the same time, iconic behavior. every target has its own log level, a number between 0 and 5, where 0 means logging is disabled and 5 means debug messages are enabled.

the file target can be used more than once with different levels. if you don't provide a target on the command line, a single target with the config syslog:3,anytun,daemon gets added. ✨

these are the supported targets:

• syslog — log to the syslog daemon, parameters are <level>[,<logname>[,<facility>]]
• file — log to a file, parameters are <level>[,<path>]
• stdout — log to standard output, parameters are <level>
• stderr — log to standard error, parameters are <level>

• -U, --debug — runs Anytun in debug mode. it implies -D (aka don't daemonize, bestie) and adds a log target configured as stdout:5 (logging at maximum level, we love to see it). in future releases there might be additional output when you pass this option. 🔮
• -i, --interface <ip address> — this IP address is used as the sender address for outgoing packets. for anycast tunnel endpoints you have to use the anycast IP. for unicast endpoints the address is usually derived correctly from the routing table anyway. default is to not use a special interface and just bind on all interfaces. 🫶
• -p, --port <port> — the local UDP port used to send and receive the payload data. the two tunnel endpoints can totally use different ports. BUT — if a tunnel endpoint is made of multiple anycast hosts, all hosts have to use the same port. default: 4444
• -r, --remote-host <hostname|ip> — specify the remote tunnel endpoint. for anycast tunnel endpoints you have to use the anycast IP address. if you don't specify an address, it gets automatically determined after receiving the first data packet. magic, honestly. ✨
• -o, --remote-port <port> — the UDP port used for payload data by the remote host (aka the one you set with -p on the remote host). if you don't specify it, it's automatically determined after receiving the first data packet. same vibe as above. 💫
• -4, --ipv4-only — resolve to IPv4 addresses only. default is to resolve both IPv4 and IPv6.
• -6, --ipv6-only — resolve to IPv6 addresses only. default is to resolve both IPv4 and IPv6.
• -I, --sync-interface <ip-address> — local unicast(sync) ip address to bind to.

this option is only needed for tunnel endpoints made of multiple anycast hosts. you can put the unicast IP address of the anycast host here. it's needed for communication with the other anycast hosts. default is to not use a special interface and just bind on all interfaces — but note that's only the case if synchronisation is active, see --sync-port.

• -S, --sync-port <port> — local unicast(sync) port to bind to.

again, only needed for tunnel endpoints consisting of multiple anycast hosts. this port is how anycast hosts synchronize information about tunnel endpoints. no payload data travels through this port. by default synchronisation is disabled, so the port stays empty.

bestie listen up 💀 you can get a list of active connections by telnetting into this port. this port is read-only and unprotected by default. it is advised to protect it using firewall rules and, eventually, IPsec. do not leave this hanging out in the open, i am begging.

• -M, --sync-hosts <hostname|ip>[:<port>],[<hostname|ip>[:<port>][...]] — remote hosts to sync with.

only needed for tunnel endpoints consisting of multiple anycast hosts. here you have to list all the unicast IP addresses of all the other anycast hosts that make up the anycast tunnel endpoint. by default synchronisation is disabled, so this is empty. mind that the port can be omitted, in which case port 2323 is used. if you want to specify an ipv6 address and a port you have to use [ and ] to separate the address from the port, e.g.: [::1]:1234. if you want to use the default port, [ and ] can be omitted.

• -X, --control-host <hostname|ip>[:<port>] — fetch the config from this host. default is not to use a control host, so this is empty. mind that the port can be omitted, in which case port 2323 is used. if you want to specify an ipv6 address and a port you have to use [ and ] to separate the address from the port, e.g.: [::1]:1234. if you want to use the default port, [ and ] can be omitted. 🎀
• -d, --dev <name> — device name.

by default, tapN is used for Ethernet tunnel interfaces and tunN for IP tunnels. this option lets you manually override those defaults.

• -t, --type <tun|tap> — device type.

the type of tunnels to create. use tap for Ethernet tunnels, tun for IP tunnels. 🦋

• -n, --ifconfig <local>/<prefix> — the local IP address and prefix length. the remote tunnel endpoint has to use a different IP address in the same subnet.
  • <local> — the local IP address for the tun/tap device
  • <prefix> — the prefix length of the network
• -x, --post-up-script <script> — tells Anytun to run this script after the interface is created. by default no script is executed.
• -R, --route <net>/<prefix length> — add a route to the connection. this can be invoked several times. slay.
• -m, --mux <mux-id> — the multiplex id to use. default: 0
• -s, --sender-id <sender id> — each anycast tunnel endpoint needs a unique sender id (1, 2, 3, ...). it's needed to distinguish the senders in case of replay attacks. this option can be ignored on unicast endpoints. default: 0
• -w, --window-size <window size> — sequence window size.

sometimes packets arrive out of order on the receiver side, it happens. this option defines the size of a list of received packets' sequence numbers. if, according to this list, a received packet has previously been received or was transmitted in the past and is therefore not in the list anymore, that's interpreted as a replay attack and the packet is dropped. a value of 0 deactivates this list and, as a consequence, the replay protection that comes from filtering packets by their sequence number. by default the sequence window is disabled, so a window size of 0 is used.

• -k, --kd—prf <kd-prf type> — key derivation pseudo random function.

the pseudo random function used for calculating the session keys and session salt.

possible values:

• null — no random function, keys and salt are set to 0..00
• aes-ctr — AES in counter mode with 128 Bits, default value
• aes-ctr-128 — AES in counter mode with 128 Bits
• aes-ctr-192 — AES in counter mode with 192 Bits
• aes-ctr-256 — AES in counter mode with 256 Bits

• -e, --role <role> — SATP uses different session keys for inbound and outbound traffic. the role parameter decides which keys get used for outbound or inbound packets. on both sides of a vpn connection you have to use different roles. possible values are left and right. you may also use alice or server as a replacement for left, and bob or client as a replacement for right. by default left is used. 💫
• -E, --passphrase <passphrase> — this passphrase is used to generate the master key and master salt. for the master key, the last n bits of the SHA256 digest of the passphrase are used (where n is the length of the master key in bits). the master salt gets generated with the SHA1 digest. you may force a specific key and or salt by using --key and --salt. 🎀
• -K, --key <master key> — master key to use for key derivation.

master key in hexadecimal notation, e.g. 01a2b3c4d5e6f708a9b0cadbecfd0fa1, with a mandatory length of 32, 48 or 64 characters (128, 192 or 256 bits).

• -A, --salt <master salt> — master salt to use for key derivation.

master salt in hexadecimal notation, e.g. 01a2b3c4d5e6f708a9b0cadbecfd, with a mandatory length of 28 characters (14 bytes).

• -c, --cipher <cipher type> — payload encryption algorithm.

the encryption algorithm used for encrypting the payload.

possible values:

• null — no encryption
• aes-ctr — AES in counter mode with 128 Bits, default value
• aes-ctr-128 — AES in counter mode with 128 Bits
• aes-ctr-192 — AES in counter mode with 192 Bits
• aes-ctr-256 — AES in counter mode with 256 Bits

• -a, --auth-algo <algo type> — message authentication algorithm.

this option sets the message authentication algorithm.

if HMAC-SHA1 is used, the packet length is increased. the additional bytes contain the authentication data. see --auth-tag-length for more info.

possible values:

• null — no message authentication
• sha1 — HMAC-SHA1, default value

• -b, --auth-tag-length <length> — the number of bytes to use for the auth tag. this value defaults to 10 bytes, unless the null auth algo is used, in which case it defaults to 0. 🌸

---

🌸 EXAMPLES 🌸

okay bestie this is the part where it all comes together, the vibe check of "does this actually work" 💅

✨ P2P Setup between two unicast enpoints ✨

(two hosts, one tunnel, mutual obsession 🫶)

Host A:

anytun -r hostb.example.com -t tun -n 192.168.123.1/30 -c
aes-ctr-256 -k aes-ctr-256 \ -E have_a_very_safe_and_productive_day
-e left

Host B:

anytun -r hosta.example.com -t tun -n 192.168.123.2/30 -c
aes-ctr-256 -k aes-ctr-256 \ -E have_a_very_safe_and_productive_day
-e right

see how they're mirror images of each other? 🦋 that's the whole point, they point at each other and they match. iconic.

---

💜 One unicast and one anycast tunnel endpoint 💜

Unicast tunnel endpoint:

anytun -r anycast.anytun.org -d anytun0 -t tun -n 192.0.2.2/30 -a
null -c null -w 0 -e client

Anycast tunnel endpoints:

On the host with unicast hostname unicast1.anycast.anytun.org and anycast hostname anycast.anytun.org:

# anytun -i anycast.anytun.org -d anytun0 -t tun -n 192.0.2.1/30 -a null -c null -w 0 -e server \
         -S 2342 -M unicast2.anycast.anytun.org:2342,unicast3.anycast.anytun.org:2342

On the host with unicast hostname unicast2.anycast.anytun.org and anycast hostname anycast.anytun.org:

# anytun -i anycast.anytun.org -d anytun0 -t tun -n 192.0.2.1/30 -a null -c null -w 0 -e server \
         -S 2342 -M unicast1.anycast.anytun.org:2342,unicast3.anycast.anytun.org:2342

On the host with unicast hostname unicast3.anycast.anytun.org and anycast hostname anycast.anytun.org:

# anytun -i anycast.anytun.org -d anytun0 -t tun -n 192.0.2.1/30 -a null -c null -w 0 -e server \
         -S 2342 -M unicast1.anycast.anytun.org:2342,unicast2.anycast.anytun.org:2342

not me noticing that each anycast host lists the other two unicast peers in -M and never itself 👀 that's not a coincidence bestie, that's the whole design. the way that three hosts are out here being each other's main characters ✨

For more sophisticated examples (like multiple unicast endpoints to one anycast tunnel endpoint) please consult the man page of anytun-config(8).

---

💀 BUGS 💀

ngl, most likely there are some bugs in Anytun. that's just how software is, it's giving "we tried our best" 😭 If you find a bug, please let the developers know at satp@anytun.org. Of course, patches are preferred. (yes queen, sending a fix > sending a complaint, we love a contributor 🫶)

---

🌈 SEE ALSO 🌈

• anytun-config(8)
• anytun-controld(8)
• anytun-showtables(8)

go read those too, they're the rest of the friend group 💖

---

👑 AUTHORS 👑

• Othmar Gsenger <otti@anytun.org>
• Erwin Nindl <nine@anytun.org>
• Christian Pointner <equinox@anytun.org>

the founding mothers... okay founding devs, but honestly they ate 🔥

---

⭐ RESOURCES ⭐

Main web site: http://www.anytun.org/

---

🎀 COPYING 🎀

Copyright (C) 2007-2014 Markus Grüneis, Othmar Gsenger, Erwin Nindl and Christian Pointner. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

---

and that's a wrap bestie, the whole ANYTUN(8) page, version stamped 01/06/2020, source being the Anytun project itself 🌸 now go tunnel something responsibly, drink water, and remember: no cap, you understood all of that 💖💅✨