netns-socks - Run a command or shell in a transient torified network namespace.

-------------
PREREQUISITES
-------------

1. tun2socks [https://github.com/xjasonlyu/tun2socks] must be installed
   somewhere in your $PATH.

2. A SOCKS server listening on localhost:9050. Tor daemon usually listens on
   this port by default.

3. A DNS server listening on localhost:9051/udp. It is recommended to add the
   following lines to your tor configuration file (typically on
   /etc/tor/torrc) and restart your tor daemon:

DNSPort 9051
AutomapHostsOnResolve 1
VirtualAddrNetworkIPv4 "10.192.0.0/10"
VirtualAddrNetworkIPv6 "[FC00::]/7"
AutomapHostsSuffixes "."

4. If netns-socks fails with "unshare: Operation not permitted", you probably
   need to allow unprivileged user namespaces on your system using the
   following commands, taken from
   https://man.archlinux.org/man/slirp4netns.1.en#EXAMPLE:

      $ sudo sh -c 'echo "user.max_user_namespaces=28633" >> /etc/sysctl.d/userns.conf'
      $ if [ -f /proc/sys/kernel/unprivileged_userns_clone ]; then sudo sh -c 'echo "kernel.unprivileged_userns_clone=1" >> /etc/sysctl.d/userns.conf'; fi
      $ sudo sysctl --system

-----------------------
BUILDING AND INSTALLING
-----------------------

To build netns-socks, simply run 'make'. You can optionally specify custom
compiler flags by prepending the make commands with CFLAGS="...", for example
'CFLAGS="-g -O0" make'.

'make install' installs the program into /usr/local/... You can specify a
custom prefix to install to by prefixing the make command with PREFIX="...",
for example 'PREFIX="$HOME/.local" make install'.

-----
USAGE
-----

    $ netns-socks [COMMAND [ARGS ...]]

Run COMMAND in a network namespace such that all network activity is forwarded
through a SOCKS proxy. If COMMAND isn't given, it defaults to your $SHELL.
Example:

    $ netns-socks mpv 'ytdl://https://www.youtube.com/watch?v=oZzjmAbyyIQ'

This will let you watch the linked video through the tor network.

------------
HOW IT WORKS
------------

netns-socks creates a new network namespace (man network_namespaces(7)) which
initially doesn't have any non-loopback network interfaces. Inside this
namespace, it creates and configures a virtual tun interface and starts
listening for DNS UDP packets on port 53.

Outside of the network namespace, netns-socks executes tun2socks and passes it
the tun interface. Additionally, it forwards all DNS UDP packets received on
port 53 from inside the namespace to the DNS server listening on port 9051
outside the namespace.

Finally, netns-socks executes COMMAND inside the network namespace. The command
thus sees only the virtual network interface and all network traffic it
generates goes through the virtual tun interface and tun2socks forwards it over
the SOCKS proxy.

You may notice that, with the above suggested tor daemon configuration, DNS
queries from COMMAND resolve into incorrect dummy addresses from the local
10.*.*.* IP address pool (try 'netns-socks curl -v example.org'). Under such
configuration, tor's DNS server doesn't actually resolve a hostname on the
internet, it merely replies with a generated virtual address. Later, when tor's
SOCKS proxy receives a request to forward a connection to such a virtual IP
address, it remembers for which hostname it replied with this IP address and
establishes a connection using the hostname rather than the IP address. The tor
protocol allows requesting connections to a hostname instead of an IP address,
leaving hostname resolution up to an exit node. This also means that connecting
to .onion links is possible with netns-socks.

Since netns-socks runs COMMAND in a rootless user namespace with limited uid
mappings, some suid or capabilites(7)-enabled programs such as 'sudo' or 'ping'
won't work correctly. If you need to run such programs, it may work if you run
netns-socks with 'sudo' as a privileged user.

----------------------
COMPARISON TO TORSOCKS
----------------------

torsocks is simpler to use and doesn't require setting up the tor DNS server.
It uses LD_PRELOAD to override network-related system calls of the called
COMMAND. netns-socks was mostly written because torsocks doesn't work with some
programs. The previously mention mpv command fails, for example.

---------------
ACKNOWLEDGMENTS
---------------

A lot of code was taken from slirp4netns
[https://github.com/rootless-containers/slirp4netns] and util-linux
[https://git.kernel.org/pub/scm/utils/util-linux/util-linux.git].