{"id":13484342,"url":"https://github.com/tun2proxy/tun2proxy","last_synced_at":"2025-10-21T03:59:07.883Z","repository":{"id":44440745,"uuid":"402253566","full_name":"tun2proxy/tun2proxy","owner":"tun2proxy","description":"Tunnel (TUN) interface for SOCKS and HTTP proxies","archived":false,"fork":false,"pushed_at":"2025-01-10T10:48:41.000Z","size":2521,"stargazers_count":657,"open_issues_count":11,"forks_count":108,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-02-07T09:15:25.747Z","etag":null,"topics":["http-proxy","proxy","socks","socks5","tun2http","tun2proxy","tun2socks","tunnel"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tun2proxy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-02T01:34:14.000Z","updated_at":"2025-02-07T02:44:31.000Z","dependencies_parsed_at":"2024-01-01T07:27:02.616Z","dependency_job_id":"cb7c762b-40c7-4116-ad93-ec132a10629f","html_url":"https://github.com/tun2proxy/tun2proxy","commit_stats":null,"previous_names":["tun2proxy/tun2proxy","blechschmidt/tun2proxy"],"tags_count":69,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tun2proxy%2Ftun2proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tun2proxy%2Ftun2proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tun2proxy%2Ftun2proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tun2proxy%2Ftun2proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tun2proxy","download_url":"https://codeload.github.com/tun2proxy/tun2proxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245882227,"owners_count":20687854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["http-proxy","proxy","socks","socks5","tun2http","tun2proxy","tun2socks","tunnel"],"created_at":"2024-07-31T17:01:22.786Z","updated_at":"2025-10-21T03:59:07.876Z","avatar_url":"https://github.com/tun2proxy.png","language":"Rust","funding_links":[],"categories":["Rust","proxy"],"sub_categories":[],"readme":"[![tun2proxy](https://socialify.git.ci/tun2proxy/tun2proxy/image?description=1\u0026language=1\u0026name=1\u0026stargazers=1\u0026theme=Light)](https://github.com/tun2proxy/tun2proxy)\n\n# tun2proxy\nA tunnel interface for HTTP and SOCKS proxies on Linux, Android, macOS, iOS and Windows.\n\n[![Crates.io](https://img.shields.io/crates/v/tun2proxy.svg)](https://crates.io/crates/tun2proxy)\n[![tun2proxy](https://docs.rs/tun2proxy/badge.svg)](https://docs.rs/tun2proxy)\n[![Documentation](https://img.shields.io/badge/docs-release-brightgreen.svg?style=flat)](https://docs.rs/tun2proxy)\n[![Download](https://img.shields.io/crates/d/tun2proxy.svg)](https://crates.io/crates/tun2proxy)\n[![License](https://img.shields.io/crates/l/tun2proxy.svg?style=flat)](https://github.com/tun2proxy/tun2proxy/blob/master/LICENSE)\n\n\u003e Additional information can be found in the [wiki](https://github.com/tun2proxy/tun2proxy/wiki)\n\n## Features\n- HTTP proxy support (unauthenticated, basic and digest auth)\n- SOCKS4 and SOCKS5 support (unauthenticated, username/password auth)\n- SOCKS4a and SOCKS5h support (through the virtual DNS feature)\n- Minimal configuration setup for routing all traffic\n- IPv4 and IPv6 support\n- GFW evasion mechanism for certain use cases (see [issue #35](https://github.com/tun2proxy/tun2proxy/issues/35))\n- SOCKS5 UDP support\n- Native support for proxying DNS over TCP\n- UdpGW (UDP gateway) support for UDP over TCP, see the [wiki](https://github.com/tun2proxy/tun2proxy/wiki/UDP-gateway-feature) for more information\n\n## Build\nClone the repository and `cd` into the project folder. Then run the following:\n```\ncargo build --release\n```\n\n### Building Framework for Apple Devices\nTo build an XCFramework for macOS and iOS, run the following:\n```\n./build-apple.sh\n```\n\n## Installation\n\n### Install from binary\n\nDownload the binary from [releases](https://github.com/tun2proxy/tun2proxy/releases) and put it in your `PATH`.\n\n\u003cdetails\u003e\n  \u003csummary\u003eAuthenticity Verification\u003c/summary\u003e\n\nSince v0.2.23 [build provenance attestations](https://docs.github.com/en/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds#verifying-artifact-attestations-with-the-github-cli)\nare supported. These allow you to ensure that the builds have been generated from the code on GitHub through the GitHub\nCI/CD pipeline. To verify the authenticity of the build files, you can use the [GitHub CLI](https://cli.github.com/):\n```shell\ngh attestation verify \u003c*.zip file\u003e --owner tun2proxy\n```\n\n\u003c/details\u003e\n\n### Install from source\n\nIf you have [rust](https://rustup.rs/) toolchain installed, this should work:\n```shell\ncargo install tun2proxy\n```\n\u003e Note: In Windows, you need to copy [wintun](https://www.wintun.net/) DLL to the same directory as the binary.\n\u003e It's `%USERPROFILE%\\.cargo\\bin` by default.\n\n## Setup\n## Automated Setup\nUsing `--setup`, you can have tun2proxy configure your system to automatically route all traffic through the\nspecified proxy. This requires running the tool as root and will roughly perform the steps outlined in the section\ndescribing the manual setup, except that a bind mount is used to overlay the `/etc/resolv.conf` file.\n\nYou would then run the tool as follows:\n```bash\nsudo ./target/release/tun2proxy-bin --setup --proxy \"socks5://1.2.3.4:1080\"\n```\n\nApart from SOCKS5, SOCKS4 and HTTP are supported.\n\nNote that if your proxy is a non-global IP address (e.g. because the proxy is provided by some tunneling tool running\nlocally), you will additionally need to provide the public IP address of the server through which the traffic is\nactually tunneled. In such a case, the tool will tell you to specify the address through `--bypass \u003cIP/CIDR\u003e` if you\nwish to make use of the automated setup feature.\n\n## Manual Setup\nA standard setup, which would route all traffic from your system through the tunnel interface, could look as follows:\n```shell\n# The proxy type can be either SOCKS4, SOCKS5 or HTTP.\nPROXY_TYPE=SOCKS5\nPROXY_IP=1.2.3.4\nPROXY_PORT=1080\nBYPASS_IP=123.45.67.89\n\n# Create a tunnel interface named tun0 which you can bind to,\n# so we don't need to run tun2proxy as root.\nsudo ip tuntap add name tun0 mode tun\nsudo ip link set tun0 up\n\n# To prevent a routing loop, we add a route to the proxy server that behaves\n# like the default route.\nsudo ip route add \"$BYPASS_IP\" $(ip route | grep '^default' | cut -d ' ' -f 2-)\n\n# Route all your traffic through tun0 without interfering with the default route.\nsudo ip route add 128.0.0.0/1 dev tun0\nsudo ip route add 0.0.0.0/1 dev tun0\n\n# If you wish to also route IPv6 traffic through the proxy, these two commands will do.\nsudo ip route add ::/1 dev tun0\nsudo ip route add 8000::/1 dev tun0\n\n# Make sure that DNS queries are routed through the tunnel.\nsudo sh -c \"echo nameserver 198.18.0.1 \u003e /etc/resolv.conf\"\n\n./target/release/tun2proxy-bin --tun tun0 --proxy \"$PROXY_TYPE://$PROXY_IP:$PROXY_PORT\"\n```\n\nThis tool implements a virtual DNS feature that is used by switch `--dns virtual`. When a DNS packet to port 53 is detected, an IP\naddress from `198.18.0.0/15` is chosen and mapped to the query name. Connections destined for an IP address from that\nrange will supply the proxy with the mapped query name instead of the IP address. Since many proxies do not support UDP,\nthis enables an out-of-the-box experience in most cases, without relying on third-party resolvers or applications.\nDepending on your use case, you may want to disable this feature using `--dns direct`.\nIn that case, you might need an additional tool like [dnsproxy](https://github.com/AdguardTeam/dnsproxy) that is\nconfigured to listen on a local UDP port and communicates with a third-party upstream DNS server via TCP.\n\nWhen you terminate this program and want to eliminate the impact caused by the above several commands,\nyou can execute the following command. The routes will be automatically deleted with the tunnel device.\n```shell\nsudo ip link del tun0\n```\n\n## CLI\n```\nTunnel interface to proxy.\n\nUsage: tun2proxy-bin [OPTIONS] --proxy \u003cURL\u003e [ADMIN_COMMAND]...\n\nArguments:\n  [ADMIN_COMMAND]...  Specify a command to run with root-like capabilities in the new namespace when using `--unshare`. This could be\n                      useful to start additional daemons, e.g. `openvpn` instance\n\nOptions:\n  -p, --proxy \u003cURL\u003e                        Proxy URL in the form proto://[username[:password]@]host:port, where proto is one of\n                                           socks4, socks5, http. Username and password are encoded in percent encoding. For example:\n                                           socks5://myname:pass%40word@127.0.0.1:1080\n  -t, --tun \u003cname\u003e                         Name of the tun interface, such as tun0, utun4, etc. If this option is not provided, the\n                                           OS will generate a random one\n      --tun-fd \u003cfd\u003e                        File descriptor of the tun interface\n      --close-fd-on-drop \u003ctrue or false\u003e   Set whether to close the received raw file descriptor on drop or not. This setting is\n                                           dependent on [tun_fd] [possible values: true, false]\n      --unshare                            Create a tun interface in a newly created unprivileged namespace while maintaining proxy\n                                           connectivity via the global network namespace\n      --unshare-pidfile \u003cUNSHARE_PIDFILE\u003e  Create a pidfile of `unshare` process when using `--unshare`\n  -6, --ipv6-enabled                       IPv6 enabled\n  -s, --setup                              Routing and system setup, which decides whether to setup the routing and system\n                                           configuration. This option requires root-like privileges on every platform.\n                                           It is very important on Linux, see `capabilities(7)`\n  -d, --dns \u003cstrategy\u003e                     DNS handling strategy [default: direct] [possible values: virtual, over-tcp, direct]\n      --dns-addr \u003cIP\u003e                      DNS resolver address [default: 8.8.8.8]\n      --virtual-dns-pool \u003cCIDR\u003e            IP address pool to be used by virtual DNS in CIDR notation [default: 198.18.0.0/15]\n  -b, --bypass \u003cIP/CIDR\u003e                   IPs used in routing setup which should bypass the tunnel, in the form of IP or IP/CIDR.\n                                           Multiple IPs can be specified, e.g. --bypass 3.4.5.0/24 --bypass 5.6.7.8\n      --tcp-timeout \u003cseconds\u003e              TCP timeout in seconds [default: 600]\n      --udp-timeout \u003cseconds\u003e              UDP timeout in seconds [default: 10]\n  -v, --verbosity \u003clevel\u003e                  Verbosity level [default: info] [possible values: off, error, warn, info, debug, trace]\n      --daemonize                          Daemonize for unix family or run as Windows service\n      --exit-on-fatal-error                Exit immediately when fatal error occurs, useful for running as a service\n      --max-sessions \u003cnumber\u003e              Maximum number of sessions to be handled concurrently [default: 200]\n      --udpgw-server \u003cIP:PORT\u003e             UDP gateway server address, forwards UDP packets via specified TCP server\n      --udpgw-connections \u003cnumber\u003e         Max connections for the UDP gateway, default value is 5\n      --udpgw-keepalive \u003cseconds\u003e          Keepalive interval in seconds for the UDP gateway, default value is 30\n  -h, --help                               Print help\n  -V, --version                            Print version\n```\nCurrently, tun2proxy supports HTTP, SOCKS4/SOCKS4a and SOCKS5. A proxy is supplied to the `--proxy` argument in the\nURL format. For example, an HTTP proxy at `1.2.3.4:3128` with a username of `john.doe` and a password of `secret` is\nsupplied as `--proxy http://john.doe:secret@1.2.3.4:3128`. This works analogously to curl's `--proxy` argument.\n\n## Container Support\n### Docker\nTun2proxy can serve as a proxy for other Docker containers. To make use of that feature, first build the image:\n\n```bash\ndocker buildx build -t tun2proxy .\n```\n\nThis will build an image containing a statically linked `tun2proxy` binary (based on `musl`) without OS.\n\nAlternatively, you can build images based on Ubuntu or Alpine as follows:\n\n```bash\ndocker buildx build -t tun2proxy --target tun2proxy-ubuntu .\ndocker buildx build -t tun2proxy --target tun2proxy-alpine .\n```\n\nNext, start a container from the tun2proxy image:\n\n```bash\ndocker run -d \\\n\t-v /dev/net/tun:/dev/net/tun \\\n\t--sysctl net.ipv6.conf.default.disable_ipv6=0 \\\n\t--cap-add NET_ADMIN \\\n\t--name tun2proxy \\\n\ttun2proxy --proxy proto://[username[:password]@]host:port\n```\n\nYou can then provide the running container's network to another worker container by sharing the network namespace (like kubernetes sidecar):\n\n```bash\ndocker run -it \\\n\t--network \"container:tun2proxy\" \\\n\tubuntu:latest\n```\n### Docker Compose\n\nCreate a `docker-compose.yaml` file with the following content:\n\n```yaml\nservices:\n  tun2proxy:\n    volumes:\n      - /dev/net/tun:/dev/net/tun\n    sysctls:\n      - net.ipv6.conf.default.disable_ipv6=0\n    cap_add:\n      - NET_ADMIN\n    container_name: tun2proxy\n    image: ghcr.io/tun2proxy/tun2proxy-ubuntu:latest\n    command: --proxy proto://[username[:password]@]host:port\n  alpine:\n    stdin_open: true\n    tty: true\n    network_mode: container:tun2proxy\n    image: alpine:latest\n    command: apk add curl \u0026\u0026 curl ifconfig.icu \u0026\u0026 sleep 10\n```\n\nThen run the compose file\n\n```bash\ndocker compose up -d tun2proxy\ndocker compose up alpine\n```\n\n## Configuration Tips\n### DNS\nWhen DNS resolution is performed by a service on your machine or through a server in your local network, DNS resolution\nwill not be performed through the tunnel interface, since the routes to localhost or your local network are more\nspecific than `0.0.0.0/1` and `128.0.0.0/1`.\nIn this case, it may be advisable to update your `/etc/resolv.conf` file to use a nameserver address that is routed\nthrough the tunnel interface. When virtual DNS is working correctly, you will see log messages like\n`DNS query: example.org` for hostnames which your machine is connecting to after having resolved them through DNS.\n\nNote that software like the `NetworkManager` may change the `/etc/resolv.conf` file automatically at any time, which\nwill result in DNS leaks. A hacky solution to prevent this consists in making the file immutable as follows:\n`sudo chattr +i \"$(realpath /etc/resolv.conf)\"`.\n\n### IPv6\nSome proxy servers might not support IPv6. When using virtual DNS, this is not a problem as DNS names are resolved by\nthe proxy server. When DNS names are resolved to IPv6 addresses locally, this becomes a problem as the proxy will be\nasked to open connections to IPv6 destinations. In such a case, you can disable IPv6 on your machine. This can be done\neither through `sysctl -w net.ipv6.conf.all.disable_ipv6=1` and `sysctl -w net.ipv6.conf.default.disable_ipv6=1`\nor through `ip -6 route del default`, which causes the `libc` resolver (and other software) to not issue DNS AAAA\nrequests for IPv6 addresses.\n\n## Contributors ✨\nThanks goes to these wonderful people:\n\n\u003ca href=\"https://github.com/tun2proxy/tun2proxy/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=tun2proxy/tun2proxy\" /\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftun2proxy%2Ftun2proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftun2proxy%2Ftun2proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftun2proxy%2Ftun2proxy/lists"}