README

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

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

Functionally similar to proxychains / tsocks / graftcp, it takes a different
approach by using Linux namespaces + TUN device + user-mode TCP/IP stack.

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:
  # Run curl with SOCKS proxy
  nsproxy -s 192.168.1.100 -p 1080 curl http://example.com

  # Run curl with HTTP proxy
  nsproxy -H -s 192.168.1.100 -p 8080 curl http://example.com

Common Options:
  -H               Use an HTTP proxy instead of SOCKS5
  -s <server>      Set the proxy server address
  -p <port>        Set the proxy server port
  -d <dns>         Redirect DNS queries to <tcp|udp>://<IP>[:PORT] or "off"
  -a <user:pass>   Set the proxy username and password
  -6               Enable IPv6 support
  -v               Increase verbosity
  -q               Be quiet

For more details, see the man page.


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.