nsproxy
====================

nsproxy (namespace proxy) is a Linux-specific command-line tool that forces apps
to use a specific SOCKS5 or HTTP proxy.

Functionally similar to tsocks / proxychains-ng / graftcp, but using a different
mechanism. It creates a new network_namespace with a TUN device and launches
programs within it, and then connects the TUN device to a user-mode TCP/IP stack
which redirects all connections to the proxy.

It has the following features:

 - Supports SOCKS5 / HTTP proxy protocols.
 - Supports TCP / UDP protocols.
 - Supports DNS redirection.
 - Works on statically linked programs or forked processes.
 - No privileges or capabilities required.
 - No system-wide side effects.


BUILD
----------

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
sudo cmake --install build  # Optional


USAGE
----------

Usage:
  nsproxy [OPTIONS...] <COMMAND> [ARGS...]

Examples:
  # Use SOCKS5 proxy
  nsproxy curl http://example.com

  # Use HTTP proxy
  nsproxy -H curl http://example.com

  # Specify a custom proxy server and port
  nsproxy -s 192.168.1.100 -p 8888 curl http://example.com

Options:
  -H
    Use HTTP proxy, not SOCKS5.
    Note: UDP is **NOT** supported in HTTP protocol. UDP packets will be dropped.

  -s <server>
    Proxy server address.
    Default value is "127.0.0.1"

  -p <port>
    Proxy server port.
    Default value is "1080" for SOCKS5, "8080" for HTTP

  -d <dns>
    DNS redirection, allow following options:
      -d off
        Do nothing on DNS, treat as normal UDP packets.
      -d tcp://<server_ip>[:port]
        Redirect DNS requests to specified TCP nameserver.
      -d udp://<server_ip>[:port]
        Redirect DNS requests to specified UDP nameserver.
    IPv6 addresses must be enclosed in brackets (e.g. udp://[::1]:53).
    Default value is "tcp://1.1.1.1".

  -a <user:pass>
    Proxy authentication (SOCKS5 or HTTP Basic Auth).

  -6
    Enable IPv6 support.
    Default is disabled

  -v
    Verbose mode. Use "-vv" or "-vvv" for more verbose.

  -q
    Be quiet. Suppress output.


LIMITATIONS
----------

All UIDs and GIDs except the current user's are mapped to the overflow UID/GID.
This means programs like sudo or su will not work.

It's unable to establish a connection from the outside to the inside. This means
programs listening on a port like apache or nginx will not work.

Connections to loopback addresses (127.0.0.1) refer to the inside of the
namespace, not the host.


CREDITS
----------

lwip - A Lightweight TCP/IP stack
https://savannah.nongnu.org/projects/lwip/

slirp4netns - User-mode networking for unprivileged network namespaces
https://github.com/rootless-containers/slirp4netns


LICENSE
----------

Copyright (C) 2023 NaLan ZeYu <nalanzeyu@gmail.com>

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 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.