Readme.txt

   1 netns-socks - Run a command or shell in a transient torified network namespace.
   2
   3 -------------
   4 PREREQUISITES
   5 -------------
   6
   7 1. tun2socks [https://github.com/xjasonlyu/tun2socks] must be installed
   8    somewhere in your $PATH.
   9
  10 2. A SOCKS server listening on localhost:9050. Tor daemon usually listens on
  11    this port by default.
  12
  13 3. A DNS server listening on localhost:9051/udp. It is recommended to add the
  14    following lines to your tor configuration file (typically on
  15    /etc/tor/torrc) and restart your tor daemon:
  16
  17 DNSPort 9051
  18 AutomapHostsOnResolve 1
  19 VirtualAddrNetworkIPv4 "10.192.0.0/10"
  20 VirtualAddrNetworkIPv6 "[FC00::]/7"
  21 AutomapHostsSuffixes "."
  22
  23 4. If netns-socks fails with "unshare: Operation not permitted", you probably
  24    need to allow unprivileged user namespaces on your system using the
  25    following commands, taken from
  26    https://man.archlinux.org/man/slirp4netns.1.en#EXAMPLE:
  27
  28       $ sudo sh -c 'echo "user.max_user_namespaces=28633" >> /etc/sysctl.d/userns.conf'
  29       $ if [ -f /proc/sys/kernel/unprivileged_userns_clone ]; then sudo sh -c 'echo "kernel.unprivileged_userns_clone=1" >> /etc/sysctl.d/userns.conf'; fi
  30       $ sudo sysctl --system
  31
  32 -----------------------
  33 BUILDING AND INSTALLING
  34 -----------------------
  35
  36 To build netns-socks, simply run 'make'. You can optionally specify custom
  37 compiler flags by prepending the make commands with CFLAGS="...", for example
  38 'CFLAGS="-g -O0" make'.
  39
  40 'make install' installs the program into /usr/local/... You can specify a
  41 custom prefix to install to by prefixing the make command with PREFIX="...",
  42 for example 'PREFIX="$HOME/.local" make install'.
  43
  44 -----
  45 USAGE
  46 -----
  47
  48     $ netns-socks [COMMAND [ARGS ...]]
  49
  50 Run COMMAND in a network namespace such that all network activity is forwarded
  51 through a SOCKS proxy. If COMMAND isn't given, it defaults to your $SHELL.
  52 Example:
  53
  54     $ netns-socks mpv 'ytdl://https://www.youtube.com/watch?v=oZzjmAbyyIQ'
  55
  56 This will let you watch the linked video through the tor network.
  57
  58 ------------
  59 HOW IT WORKS
  60 ------------
  61
  62 netns-socks creates a new network namespace (man network_namespaces(7)) which
  63 initially doesn't have any non-loopback network interfaces. Inside this
  64 namespace, it creates and configures a virtual tun interface and starts
  65 listening for DNS UDP packets on port 53.
  66
  67 Outside of the network namespace, netns-socks executes tun2socks and passes it
  68 the tun interface. Additionally, it forwards all DNS UDP packets received on
  69 port 53 from inside the namespace to the DNS server listening on port 9051
  70 outside the namespace.
  71
  72 Finally, netns-socks executes COMMAND inside the network namespace. The command
  73 thus sees only the virtual network interface and all network traffic it
  74 generates goes through the virtual tun interface and tun2socks forwards it over
  75 the SOCKS proxy.
  76
  77 You may notice that, with the above suggested tor daemon configuration, DNS
  78 queries from COMMAND resolve into incorrect dummy addresses from the local
  79 10.*.*.* IP address pool (try 'netns-socks curl -v example.org'). Under such
  80 configuration, tor's DNS server doesn't actually resolve a hostname on the
  81 internet, it merely replies with a generated virtual address. Later, when tor's
  82 SOCKS proxy receives a request to forward a connection to such a virtual IP
  83 address, it remembers for which hostname it replied with this IP address and
  84 establishes a connection using the hostname rather than the IP address. The tor
  85 protocol allows requesting connections to a hostname instead of an IP address,
  86 leaving hostname resolution up to an exit node. This also means that connecting
  87 to .onion links is possible with netns-socks.
  88
  89 Since netns-socks runs COMMAND in a rootless user namespace with limited uid
  90 mappings, some suid or capabilites(7)-enabled programs such as 'sudo' or 'ping'
  91 won't work correctly. If you need to run such programs, it may work if you run
  92 netns-socks with 'sudo' as a privileged user.
  93
  94 ----------------------
  95 COMPARISON TO TORSOCKS
  96 ----------------------
  97
  98 torsocks is simpler to use and doesn't require setting up the tor DNS server.
  99 It uses LD_PRELOAD to override network-related system calls of the called
 100 COMMAND. netns-socks was mostly written because torsocks doesn't work with some
 101 programs. The previously mention mpv command fails, for example.
 102
 103 ---------------
 104 ACKNOWLEDGMENTS
 105 ---------------
 106
 107 A lot of code was taken from slirp4netns
 108 [https://github.com/rootless-containers/slirp4netns] and util-linux
 109 [https://git.kernel.org/pub/scm/utils/util-linux/util-linux.git].