PdaNet-CachyOS

Transparent, system-wide PdaNet SOCKS5 tunneling for CachyOS and Arch Linux.

Turn PdaNet's SOCKS5 proxy into a resilient Linux-wide tunnel using tun2socks, policy routing, automatic gateway detection, DNS handling, health checks, and automatic reconnection.

Quick Start • How It Works • Configuration • Troubleshooting • Contributing

Overview

PdaNet can expose a SOCKS5 proxy to a computer connected to an Android phone. The problem is that many Linux applications do not automatically support or respect an application-level SOCKS proxy.

PdaNet-CachyOS solves that at the network layer.

It creates a virtual TUN interface, sends system traffic into that interface using Linux policy routing, and forwards the traffic through PdaNet's SOCKS5 proxy using tun2socks.

The result is a much more transparent setup than manually configuring individual applications.

Note

The project was built primarily for CachyOS and Arch-based Linux systems. It may work on other distributions, but they are not currently the main target.

Why This Project?

Typical SOCKS5 setups require applications to support proxy configuration individually.

This project instead provides:

System-wide tunneling through a TUN interface
Automatic PdaNet gateway detection
Automatic network interface detection
Automatic SOCKS5 availability checks
Automatic reconnection when PdaNet restarts
Gateway-change detection
Connection health monitoring
Policy-based routing instead of manually configuring every app
Automatic DNS configuration
Configurable TTL and MTU
Safe cleanup routines for routes, TUN interfaces, DNS state, and processes
PID-based process management
Built-in status, restart, and stop commands
Optional KDE Plasma desktop launcher

Architecture

┌─────────────────────────────┐
│      Linux Applications     │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│    Linux Network Stack      │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│      Policy Routing         │
│        Table 100            │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│       TUN Interface         │
│           tun0              │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│         tun2socks           │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│   PdaNet SOCKS5 Proxy       │
│   <PHONE_GATEWAY>:8000      │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│       Android / PdaNet      │
└──────────────┬──────────────┘
               │
               ▼
          Internet

The PdaNet gateway itself is excluded from the tunnel routing rule so that traffic destined for the SOCKS5 server does not loop back into the tunnel.

Features

Transparent tunneling

Traffic is routed into a TUN interface and converted to SOCKS5 connections by tun2socks.

Automatic network detection

Unless manually configured, the script detects:

the active network interface
the default gateway
the PdaNet proxy endpoint

Automatic recovery

The watchdog monitors the tunnel and can recover from:

PdaNet being restarted
gateway disappearance
gateway IP changes
tun2socks crashes
temporary internet loss

Automatic cleanup

On exit, the script attempts to restore the system by cleaning up:

tun2socks
policy routing rules
routing table 100
DNS-specific routes
gateway routes
TTL rules
the TUN interface
DNS backup state
PID state

Repository Structure

PdaNet-CachyOS/
├── pdanet-proxy.sh        # Main tunnel manager
├── pdanet-proxy.conf      # User configuration
├── pdanet-proxy.desktop   # Optional KDE launcher
├── README.md
└── .directory

`pdanet-proxy.sh`

Main Bash application responsible for:

dependency validation
root privilege checks
automatic network discovery
SOCKS5 availability checks
TUN interface management
tun2socks lifecycle management
DNS configuration
TTL configuration
policy routing
watchdog monitoring
automatic reconnection
cleanup

`pdanet-proxy.conf`

Configuration file for network, tunnel, DNS, TTL, logging, and watchdog settings.

`pdanet-proxy.desktop`

Optional KDE Plasma launcher.

Important

The current desktop file contains a user-specific example path. You must edit it before installing the launcher.

Requirements

Android side

You need:

an Android device
PdaNet installed and running
a working internet connection on the phone
the Linux computer connected to the network exposed by PdaNet
the PdaNet SOCKS5 proxy reachable from the Linux machine

The default proxy port used by this project is:

Linux side

Required commands:

tun2socks
ip
iptables
curl
sysctl

The script also uses common Linux utilities such as:

ping
timeout
awk
sed
xargs
pgrep
killall

Quick Start

1. Clone the repository

git clone https://github.com/Dr-Kozmik/PdaNet-CachyOS.git
cd PdaNet-CachyOS

2. Make the script executable

chmod +x pdanet-proxy.sh

3. Start PdaNet on your phone

Connect your Linux machine to the PdaNet network and make sure the phone has internet access.

4. Start the tunnel

sudo ./pdanet-proxy.sh start

You can also run:

sudo ./pdanet-proxy.sh

because start is the default action.

Command Reference

Start

sudo ./pdanet-proxy.sh start

Stop

sudo ./pdanet-proxy.sh stop

Restart

sudo ./pdanet-proxy.sh restart

Status

sudo ./pdanet-proxy.sh status

The status command checks the main process, TUN interface, tun2socks, and internet connectivity.

Startup Flow

When started, the script performs approximately the following sequence:

Root privilege check
        │
        ▼
Dependency check
        │
        ▼
Running-instance check
        │
        ▼
Network interface detection
        │
        ▼
PdaNet gateway detection
        │
        ▼
SOCKS5 proxy check
        │
        ▼
Old-state cleanup
        │
        ▼
TUN interface creation
        │
        ▼
tun2socks startup
        │
        ▼
Policy routing setup
        │
        ▼
DNS configuration
        │
        ▼
Connectivity test
        │
        ▼
Watchdog

Configuration

The default configuration file is:

pdanet-proxy.conf

Default values:

# Optional manual overrides:
# GATEWAY_IP=192.168.96.92
# INTERFACE=wlan0

PROXY_PORT=8000

TUN_DEV=tun0
TUN_SUBNET="10.0.0.1/24"
TUN_MTU=1400

DNS_SERVERS="8.8.8.8 1.1.1.1"

TTL_VALUE=65

HEALTH_CHECK_INTERVAL=30
HEALTH_CHECK_RETRIES=3
HEALTH_CHECK_COOLDOWN=60

LOG_FILE="/var/log/pdanet-proxy.log"
PID_FILE="/tmp/pdanet-proxy.pid"

You can also provide another config file:

sudo CONF_FILE=/path/to/custom.conf ./pdanet-proxy.sh start

Configuration Reference

Setting	Default	Description
`GATEWAY_IP`	auto	Manually override the detected PdaNet gateway
`INTERFACE`	auto	Manually override the detected network interface
`PROXY_PORT`	`8000`	PdaNet SOCKS5 proxy port
`TUN_DEV`	`tun0`	TUN interface name
`TUN_SUBNET`	`10.0.0.1/24`	Address assigned to the TUN interface
`TUN_MTU`	`1400`	TUN interface MTU
`DNS_SERVERS`	`8.8.8.8 1.1.1.1`	DNS servers used while tunnel is active
`TTL_VALUE`	`65`	TTL value applied through iptables
`HEALTH_CHECK_INTERVAL`	`30`	Seconds between watchdog checks
`HEALTH_CHECK_RETRIES`	`3`	Consecutive failures before reconnect
`HEALTH_CHECK_COOLDOWN`	`60`	Delay after failed reconnect cycles
`LOG_FILE`	`/var/log/pdanet-proxy.log`	Log file path
`PID_FILE`	`/tmp/pdanet-proxy.pid`	Main process PID file

Network Detection

By default, the script reads the Linux routing table to determine the active network interface and gateway.

Example:

default via 192.168.96.92 dev wlan0

This would approximately resolve to:

GATEWAY_IP=192.168.96.92
INTERFACE=wlan0

You can inspect your current network state with:

ip route

TUN and `tun2socks`

The script creates a virtual interface similar to:

ip tuntap add dev tun0 mode tun
ip addr add 10.0.0.1/24 dev tun0
ip link set tun0 mtu 1400 up

It then starts tun2socks approximately as follows:

tun2socks \
  -device tun://tun0 \
  -proxy socks5://<GATEWAY_IP>:8000 \
  -interface <NETWORK_INTERFACE> \
  -loglevel warn

Policy Routing

The project uses a dedicated routing table instead of simply replacing the system default route.

The tunnel default route is placed in table 100:

ip route add default dev tun0 table 100

Traffic is then routed through that table while excluding the PdaNet gateway.

Inspect the policy rules with:

ip rule

and table 100 with:

ip route show table 100

DNS Handling

While the tunnel is active, the script configures /etc/resolv.conf using the configured DNS servers and requests TCP-based DNS resolution.

Default DNS servers:

8.8.8.8
1.1.1.1

The script attempts to back up the existing resolver configuration to:

/etc/resolv.conf.bak

and restore it during cleanup.

Warning

Systems using NetworkManager, systemd-resolved, or resolvconf may manage /etc/resolv.conf automatically. If DNS behaves unexpectedly, inspect your system's resolver configuration before making manual changes.

TTL Handling

The default configuration applies:

TTL_VALUE=65

using an iptables mangle rule.

Important

Network providers may have rules or terms regarding tethering, proxying, or TTL manipulation. You are responsible for ensuring that your usage complies with your provider's terms and applicable rules.

Watchdog and Automatic Reconnection

The watchdog runs continuously while the tunnel is active.

It checks:

whether the PdaNet gateway still exists
whether the gateway IP changed
whether tun2socks is still running
whether internet connectivity still works

Default values:

HEALTH_CHECK_INTERVAL=30
HEALTH_CHECK_RETRIES=3
HEALTH_CHECK_COOLDOWN=60

If PdaNet is restarted, the script can wait for the gateway and proxy to become available again and rebuild the tunnel automatically.

Connection lost
      │
      ▼
Cleanup old tunnel
      │
      ▼
Wait for PdaNet network
      │
      ▼
Detect new gateway
      │
      ▼
Wait for SOCKS5 proxy
      │
      ▼
Recreate TUN
      │
      ▼
Restart tun2socks
      │
      ▼
Restore routing
      │
      ▼
Test connectivity

Logging

Default log file:

/var/log/pdanet-proxy.log

Follow it live with:

sudo tail -f /var/log/pdanet-proxy.log

Show the last 100 lines:

sudo tail -n 100 /var/log/pdanet-proxy.log

Disable file logging by setting:

LOG_FILE=""

KDE Plasma Launcher

The included pdanet-proxy.desktop file currently contains a user-specific path:

Exec=konsole --hold -e sudo /home/koray/proje/pdanet-proxy.sh
Path=/home/koray/proje

Change these paths to match your clone location.

Example:

[Desktop Entry]
Name=PdaNet Proxy
Comment=PdaNet Wi-Fi Direct Transparent Proxy
Exec=konsole --hold -e sudo /home/alice/PdaNet-CachyOS/pdanet-proxy.sh
Icon=network-vpn
Terminal=false
Type=Application
Categories=Network;
Path=/home/alice/PdaNet-CachyOS

Install it for the current user:

mkdir -p ~/.local/share/applications
cp pdanet-proxy.desktop ~/.local/share/applications/
chmod +x ~/.local/share/applications/pdanet-proxy.desktop

Troubleshooting

Script requires root privileges

Run:

sudo ./pdanet-proxy.sh start

The script must modify TUN interfaces, routing tables, DNS, sysctl state, and iptables rules.

Gateway cannot be detected

Inspect:

ip route

You should normally see a default route similar to:

default via 192.168.x.x dev wlan0

If no default route exists:

reconnect to the phone
restart PdaNet
verify NetworkManager connectivity
manually configure GATEWAY_IP if needed

Wrong interface detected

Inspect:

ip link
ip route

Then configure the correct interface:

INTERFACE=wlan0

SOCKS5 proxy cannot be reached

Check the gateway:

ip route show default

Test the port:

timeout 5 bash -c 'echo >/dev/tcp/<PHONE_IP>/8000'

If it fails:

verify PdaNet is running
verify the computer is connected to the phone
verify PROXY_PORT
restart PdaNet

Tunnel exists but internet does not work

Run:

ip addr show tun0
pgrep -a tun2socks
ip rule
ip route show table 100
cat /etc/resolv.conf
sudo tail -n 100 /var/log/pdanet-proxy.log

IP connectivity works but DNS does not

Test raw connectivity:

ping -c 3 1.1.1.1

Then test DNS resolution:

getent hosts example.com

Inspect resolver state:

cat /etc/resolv.conf
ls -l /etc/resolv.conf

Some websites stall or fail to load

Investigate the tunnel MTU.

Default:

TUN_MTU=1400

For troubleshooting, you may try a lower value such as:

TUN_MTU=1350

Then restart:

sudo ./pdanet-proxy.sh restart

Network state looks broken after an interrupted run

First try:

sudo ./pdanet-proxy.sh stop

Then inspect:

ip rule
ip route
ip route show table 100
ip link show tun0

Useful Debugging Commands

# Interfaces
ip addr

# Main routing table
ip route

# Policy routing rules
ip rule

# Tunnel routing table
ip route show table 100

# TUN interface
ip addr show tun0

# tun2socks process
pgrep -a tun2socks

# TTL rules
sudo iptables -t mangle -L POSTROUTING -n -v

# DNS
cat /etc/resolv.conf

# Logs
sudo tail -f /var/log/pdanet-proxy.log

# Main process PID
cat /tmp/pdanet-proxy.pid

Security Considerations

This project runs with root privileges and modifies core networking state, including:

TUN interfaces
routing tables
policy routing rules
/etc/resolv.conf
iptables rules
kernel network parameters

Review the script before using it on a production, work, or security-sensitive system.

You should also understand and trust the DNS resolvers configured in pdanet-proxy.conf.

Current Limitations

Primarily designed around IPv4
IPv6 is disabled while the tunnel is active
Requires root privileges
Requires PdaNet to expose a reachable SOCKS5 proxy
DNS handling directly modifies /etc/resolv.conf
Primarily tested/designed for CachyOS and Arch-based Linux
The desktop launcher currently contains a user-specific path
Behavior can vary depending on NetworkManager or other resolver/network managers
Different tun2socks implementations may expose different CLI flags

Roadmap

Contributing

Contributions, bug reports, and improvements are welcome.

Recommended workflow

Fork the repository.
Create a feature branch.

git checkout -b feature/my-improvement

Make and test your changes.
Commit them.

git commit -m "feat: add my improvement"

Push your branch.

git push origin feature/my-improvement

Open a Pull Request.

When reporting networking bugs, useful information includes:

Linux distribution
network interface name
PdaNet connection method
relevant ip route output
relevant ip rule output
relevant log output
steps required to reproduce the problem

Please remove sensitive or personally identifying information before posting logs.

Disclaimer

PdaNet-CachyOS is an independent community project and is not affiliated with, endorsed by, or maintained by PdaNet or its developers.

Use this project at your own risk.

You are responsible for complying with your network provider's terms of service and any applicable rules regarding tethering, proxying, traffic routing, or TTL manipulation.

The project authors and contributors are not responsible for connectivity loss, system configuration issues, provider restrictions, account consequences, data loss, or other unintended behavior resulting from the use or modification of this software.

License

A license file is not currently included in this repository.

If you intend to allow reuse, modification, and redistribution, add an explicit open-source license such as MIT, Apache-2.0, or GPL-3.0.

Support the Project

If PdaNet-CachyOS helped you, consider giving the repository a star. It helps other Linux users discover the project.

⭐ Star the repo · Report bugs · Suggest improvements · Contribute fixes

Made by Dr-Kozmik

Name		Name	Last commit message	Last commit date
.directory		.directory
README.md		README.md
pdanet-proxy.conf		pdanet-proxy.conf
pdanet-proxy.desktop		pdanet-proxy.desktop
pdanet-proxy.sh		pdanet-proxy.sh

Latest commit

History

Folders and files

Repository files navigation