Skip to content
BranchesTags

Repository files navigation

EgressShare

Share a Linux Internet egress — VPN tunnel or local proxy — to other devices over Wi-Fi or Ethernet.

EgressShare turns an Ubuntu/Debian computer into a small, controlled gateway. A console, TV, phone, IoT device, another computer, or a router can connect to it and use either a VPN/TUN interface or a proxy already running on the Linux host.

It is designed for the common case where an application such as v2rayN, Xray, sing-box, Clash/Mihomo, Hiddify or another client is already providing a local proxy or tunnel on the computer, but the downstream device cannot run that client itself.

What it can share

Client connection Internet egress Supported
Wi-Fi hotspot VPN/TUN interface Yes
Ethernet/LAN VPN/TUN interface Yes
Wi-Fi hotspot SOCKS5 proxy Yes
Ethernet/LAN SOCKS5 proxy Yes
Wi-Fi hotspot HTTP/HTTPS CONNECT proxy Yes, TCP + proxied DNS
Ethernet/LAN HTTP/HTTPS CONNECT proxy Yes, TCP + proxied DNS

Architecture

Tunnel mode:

Internet / VPN provider
          ↑
      tun0 / wg0
          ↑
      EgressShare
       ↙       ↘
 Wi-Fi AP      LAN
     ↓          ↓
 console / TV / phone / PC

Proxy mode:

Internet
   ↑
local SOCKS5 or HTTP proxy (for example v2rayN)
   ↑
 sing-box TProxy engine
   ↑
 EgressShare
   ↑
Wi-Fi hotspot or LAN client

The transparent proxy is deliberately scoped to packets arriving from EgressShare's downstream interface. The host's own traffic is not transparently captured by EgressShare.

Egress modes

tunnel

Share an explicit tunnel (tun0, wg0, etc.) or use strict auto-detection. In auto tunnel detection EgressShare only chooses a tunnel when the current public IPv4 route is actually using that interface. This avoids accidentally selecting a split-tunnel/private overlay such as a Tailscale interface.

proxy

Use either:

  • the selected desktop user's GNOME System Proxy, or
  • a manually configured SOCKS5 / HTTP / HTTPS proxy.

For a GNOME desktop, apps that use “Set System Proxy” can therefore be detected without manually copying the port every time.

auto

Prefer a real Internet-default tunnel. If it disappears, fall back to the configured System/Manual Proxy. If neither egress is usable, the client network can stay up but the kill switch blocks Internet access instead of leaking through the normal connection.

Proxy mode details

EgressShare uses sing-box TProxy on Linux so downstream applications do not need proxy support themselves.

Upstream proxy TCP UDP DNS ICMP
SOCKS5 Yes Yes * DoH through proxy No
HTTP CONNECT Yes No DoH through proxy No
HTTPS CONNECT Yes No DoH through proxy No

* SOCKS5 UDP requires the upstream SOCKS5 server to implement UDP ASSOCIATE. A local proxy can expose a SOCKS5 listener but still disable UDP; that is an upstream limitation.

For consoles and games, prefer a SOCKS5 endpoint with UDP support or a real VPN/TUN interface. HTTP proxy mode is useful for web/TCP traffic but it cannot turn an HTTP CONNECT proxy into a full UDP VPN.

DNS from downstream clients is transparently hijacked by sing-box and resolved via DoH through the selected proxy. Non-DNS UDP is blocked in HTTP/HTTPS proxy mode instead of being allowed to leak directly.

GNOME System Proxy detection

egressshare proxy-list reads:

org.gnome.system.proxy
org.gnome.system.proxy.socks
org.gnome.system.proxy.http
org.gnome.system.proxy.https

for DESKTOP_USER.

Preference is SOCKS → HTTPS → HTTP. GNOME mode=auto (PAC URL/script) is detected and reported, but EgressShare does not evaluate PAC scripts. Configure the local SOCKS/HTTP endpoint manually in that case.

It also shows TCP listeners owned by common proxy processes as hints. A listening port alone does not reliably reveal whether it speaks SOCKS5 or HTTP, so EgressShare does not guess the protocol from a process name.

Wi-Fi behavior

When the same physical Wi-Fi radio is used both as the upstream client and as the hotspot, the driver must support concurrent managed + AP operation. If the hardware restricts that combination to one channel, EgressShare automatically reads the current upstream Wi-Fi channel and recreates the AP if the router changes channel.

A second Wi-Fi adapter is not required when the radio/driver supports concurrent AP + managed mode.

Ethernet/LAN behavior

Choose an unused Ethernet port as the downstream. EgressShare temporarily takes that interface away from NetworkManager, assigns the gateway address and DHCP service, and returns it to NetworkManager when sharing stops.

It refuses to take over the interface that is currently the main-table default Internet uplink.

Safety defaults

  • Kill switch enabled.
  • No direct fallback to the normal Internet connection.
  • Downstream IPv6 disabled by default to avoid an unhandled IPv6 path.
  • Downstream access to services on the Linux host blocked by default, except required DHCP/TProxy traffic.
  • Optional private-destination blocking in proxy mode.
  • Wi-Fi client isolation enabled.
  • TCP MSS clamping in tunnel mode.
  • Root-only configuration file (0600) because it may contain Wi-Fi/proxy credentials.

Installation

Ubuntu 24.04+ and Ubuntu 26.04 are the primary targets. Other modern apt-based Debian systems may also work.

unzip EgressShare.zip
cd EgressShare
./install.sh

Do not need to prefix it with sudo; the installer requests sudo itself.

It installs the required tools, including hostapd, dnsmasq-base, iw, iproute2, iptables, NetworkManager CLI tools, whiptail, qrencode and jq. If sing-box is missing, the installer adds the official SagerNet APT repository and installs it. It does not enable, stop or reconfigure the package's normal sing-box.service; EgressShare starts its own isolated sing-box process only for transparent proxying.

Network restrictions during installation

The sing-box package is downloaded from the official SagerNet APT repository. In networks where that repository is blocked or unreliable, including some connections in Iran, connect the Linux host through a VPN before running ./install.sh. The VPN is only needed while APT downloads the required packages; it is not a permanent installation requirement.

Skip the setup wizard during installation with:

./install.sh --no-setup

Then run:

egressshare setup

Interactive CLI

Run without arguments:

egressshare

The terminal UI provides start/stop, setup, status, clients, QR code, tunnel/proxy discovery, diagnostics, logs and boot settings.

The command automatically asks for sudo when an administrative action is required.

Common commands

egressshare start
egressshare stop
egressshare restart
egressshare status

egressshare setup
egressshare doctor
egressshare clients
egressshare qr
egressshare logs 200

egressshare interfaces
egressshare egress-list
egressshare tunnel-list
egressshare proxy-list

egressshare enable
egressshare disable

Force a tunnel

egressshare set egress tunnel
egressshare set tunnel tun0
egressshare restart

Use the active GNOME System Proxy

egressshare set egress proxy
egressshare set proxy-source system
egressshare set desktop-user "$USER"
egressshare proxy-list
egressshare restart

If v2rayN is configured to set GNOME's System Proxy and exposes a SOCKS listener there, EgressShare will use it. If GNOME only contains an HTTP proxy, EgressShare uses HTTP CONNECT mode and reports the TCP-only limitation.

Manual SOCKS5

egressshare set egress proxy
egressshare set proxy-source manual
egressshare set proxy-type socks5
egressshare set proxy-host 127.0.0.1
egressshare set proxy-port 10808
egressshare restart

Auto tunnel → proxy fallback

egressshare set egress auto
egressshare set tunnel auto
egressshare set proxy-source system
egressshare restart

Persistent service

egressshare enable

starts the service and enables it at boot. Disable it with:

egressshare disable

The runtime daemon monitors:

  • upstream Wi-Fi channel changes,
  • tunnel appearance/disappearance,
  • GNOME System Proxy endpoint changes,
  • proxy reachability,
  • hostapd/dnsmasq/sing-box child health.

Files

/usr/local/bin/egressshare
/etc/egressshare/egressshare.conf
/etc/systemd/system/egressshare.service
/etc/NetworkManager/conf.d/zz-egressshare-ap.conf
/var/lib/egressshare/dnsmasq.leases
/run/egressshare/

Runtime-generated hostapd, dnsmasq and sing-box configurations live under /run/egressshare and disappear across reboots.

Uninstall

Keep configuration:

./uninstall.sh

Remove configuration too:

./uninstall.sh --purge

Shared packages such as sing-box, hostapd and NetworkManager are intentionally not removed.

Limitations

  • Linux only.
  • Main implementation currently targets NetworkManager + systemd + iptables-compatible firewall tooling.
  • Wi-Fi concurrent hotspot mode depends on the radio and driver.
  • 6 GHz concurrent AP is not yet supported.
  • PAC proxy scripts are detected but not evaluated.
  • HTTP/HTTPS CONNECT cannot carry arbitrary UDP.
  • SOCKS5 UDP depends on upstream UDP ASSOCIATE support.
  • Proxy mode is IPv4 downstream today; IPv6 is disabled on the client side by default.

See docs/PROXY_MODE.md, docs/ARCHITECTURE.md and docs/TROUBLESHOOTING.md for more detail.

Security

See SECURITY.md. If you find a security issue, avoid publishing credentials, IPs, proxy URLs or full debug logs in a public issue.

License

MIT

About

Share VPN tunnels, SOCKS5 or HTTP proxies over Wi-Fi hotspot or Ethernet on Linux. EgressShare provides automatic tunnel/proxy detection, system proxy support, DHCP, NAT, kill switch, routing, systemd integration, and an interactive CLI for securely sharing internet connections.

Topics

bashclidhcphotspothotspot-wifilinuxnetworkingnetworkmanagerproxysharesocks5systemdtunneltunnel-sharevpnvpn-sharewifi

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

2 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages