Setting Up a SOCKS5 Proxy on iOS via SSH Tunnel

ByEric Ma Posted on Updated on

iOS doesn’t expose SOCKS proxy settings in the Settings UI, but it supports Proxy Auto-Config (PAC) files natively. This lets you route iOS traffic through an SSH tunnel on a Linux/Unix host without installing a VPN app.

Prerequisites

  • iOS device (iPhone/iPad) on WiFi
  • Linux/Unix host (same network or internet-accessible) with SSH access
  • Web server to host the PAC file
  • SSH SOCKS tunnel listening on a network-accessible interface

Set Up the SSH SOCKS Tunnel

First, create a SOCKS5 proxy on your Linux/Unix host. For local testing on the same network:

ssh -D 0.0.0.0:1080 -f -C -q -N user@remote-host

This opens port 1080 on all interfaces. The flags mean:

  • -D 0.0.0.0:1080 — bind SOCKS proxy to all interfaces on port 1080
  • -f — fork to background
  • -C — enable compression
  • -q — quiet mode
  • -N — don’t execute a remote command

For better security, use the server’s GatewayPorts SSH option instead of binding to 0.0.0.0, or restrict to specific IPs with firewall rules.

If your iOS device and Linux host are on different networks, tunnel through a jump host or use -L for local port forwarding and expose that locally.

Create a PAC File

Proxy Auto-Config is JavaScript that tells clients which proxy to use. Create proxy.pac:

function FindProxyForURL(url, host) {
    return "SOCKS5 proxy-host:1080";
}

Replace proxy-host with the actual IP or hostname of your Linux box.

For selective routing (only certain domains through the proxy):

function FindProxyForURL(url, host) {
    var proxy = "SOCKS5 proxy-host:1080";
    var direct = "DIRECT";

    // Route internal domains through proxy
    if (host.indexOf("internal.example.com") !== -1 ||
        host.indexOf("api.internal") !== -1) {
        return proxy;
    }

    // Skip private networks
    if (host.match(/^(10\.|192\.168\.|172\.1[6-9]\.|172\.2[0-9]\.|172\.3[01]\.)/)) {
        return direct;
    }

    // Everything else direct
    return direct;
}

Host the PAC File

Deploy the PAC file on any web server accessible from your iOS device.

Python 3 (quick local testing):

python3 -m http.server 8000 --directory /path/to/pac/files

Nginx (production):

server {
    listen 80;
    server_name proxy.local;

    location / {
        root /var/www;
        types {
            application/x-ns-proxy-autoconfig pac;
            text/plain txt;
        }
    }
}

Node.js alternative:

npx http-server -p 8000 -c-1

Verify the PAC file is accessible at http://proxy-host:8000/proxy.pac or whatever URL you’re using.

Configure iOS WiFi to Use the PAC File

On your iOS device:

  1. Go to Settings → Wi-Fi
  2. Tap the ⓘ icon next to your connected network
  3. Scroll to HTTP Proxy
  4. Select Automatic
  5. Enter the PAC URL: http://proxy-host:8000/proxy.pac
  6. Tap Save

iOS fetches and applies the PAC immediately. The configuration applies to all traffic on that WiFi network only.

Verify the Setup

Check that traffic routes through the proxy:

From the iOS device:

  • Visit https://whatismyipaddress.com or https://ipleak.net and confirm the IP matches your SSH tunnel origin
  • Use a test app that shows your outbound IP

From the Linux host:

  • Monitor the SSH tunnel: watch -n 1 'ss -tuln | grep 1080'
  • Check active SSH connections: ps aux | grep socks
  • Monitor SSH logs: journalctl -u ssh -f (if using systemd)

From another device on the network:

curl -x socks5://proxy-host:1080 https://example.com

Troubleshooting

PAC file won’t load

  • Open the PAC URL directly in Safari. If it fails, the server isn’t reachable.
  • Confirm the URL format (use http://, not https://, unless you’ve configured TLS)
  • Check firewall rules on the Linux host blocking the web server port

Wrong MIME type errors

  • Ensure your web server sends application/x-ns-proxy-autoconfig for .pac files, or fallback to text/plain
  • Test with curl: curl -i http://proxy-host:8000/proxy.pac | head -5

Proxy not actually being used

  • Verify proxy-host:1080 in the PAC file is reachable from the iOS device: nslookup proxy-host and nc -zv proxy-host 1080 from another device on the same network
  • PAC files control HTTP/HTTPS traffic only. Other protocols (DNS, app-specific) may bypass the proxy.

DNS leaks

  • PAC files don’t intercept DNS queries by default. If privacy is critical, also configure DNS over HTTPS in iOS Settings → Privacy, or tunnel all traffic through the SSH connection with a VPN wrapper.

IPv6 compatibility

  • If proxy-host resolves to IPv6, ensure your SOCKS tunnel listens on IPv6:
ssh -D [::]:1080 -f -C -q -N user@remote-host

Or bind to both:

ssh -D 0.0.0.0:1080 -D [::]:1080 -f -C -q -N user@remote-host

Production Considerations

  • HTTPS PAC delivery: Host the PAC file behind TLS to prevent interception, especially on untrusted networks
  • SSH key authentication: Use SSH keys instead of passwords. Configure SSH to not require a password prompt:
ssh -i /path/to/key -D 0.0.0.0:1080 -f -C -q -N user@remote-host
  • MDM deployment: For fleet management, use Mobile Device Management to distribute the PAC URL automatically
  • Persistence: The PAC configuration persists per WiFi network. You’ll need to reconfigure for other networks.
  • Monitoring: Log SOCKS5 traffic with tools like tcpdump or enable verbose SSH logging if needed

27 Comments

  1. I hosted my file here:

    http://copy.com/yTqsQZqHAsl2F0nE/sunshine.pac

    And used this same url on my iphone, but for some reason it doesn’t work. It doesn’t send traffic through the proxy. I was wondering if i did something wrong. The IP address and ports on the .pac file work because I use them on other pc’s in the local network and they successfully connect to the proxy.

    Reply

  2. Thanks for this information. But this only sets the proxy for a single WIFI connection. Is there a way to set the proxy system-wide? For instance, so that I use the proxy over the 3G data link as well?

    Reply

    1. Yes there are ways to set the system-wide proxy (but I never tested them yet): https://developer.apple.com/library/ios/featuredarticles/iPhoneConfigurationProfileRef/Introduction/Introduction.html

      Note that: you need to turn the device to the supervised mode (you will need a Mac and the Apple Configurator app; a tutorial).

      If you are using a VPN, it will be easier: there is an option to set the proxy that you will connect through to the VPN server.

      Reply

  5. Hi, can I place my PAC file inside my ssh server?
    I am using free ddns service for my dns address.

    Reply

  6. Hello,
    where i need to put the pac file? Stored where? In my iphone or on my ssh server?

    “Assume this PAC file is named proxy.pac and is stored at address http://www.my-server.com/proxy.pac.”

    I have debian ssh vps, iphone connected thorugh http proxy also

    could you help me?

    Reply

      1. Thank you for you reply!
        I am in Office with:

        -PC Office with http proxy for surfing (proxy:8080)
        -iPhone on same lan
        -vps for tunneling

        I would like to surf free and under SSH with my iPhone.

        -I set iphone in same lan with proxy auto with ( file:///private/var/root/proxy.pac)

        -proxy.pac filed with: “function FindProxyForURL(url, host)
        {
        return “SOCKS localhost:1084″;
        }”

        – ssh_config file with this line added:
        “Proxycommand connect -H IPofOfficePC:4040 %h %p”

        -SSH connection with mterminal “ssh -D 1084 -C -p Proxyport -N root@IPofVPS”

        – in my Office PC port 4040->8080

        The problem is that only Safari is under Socks proxy (has same IP of my VPS) but other apps not! I cannot open whatsapp.. Facebook msg… :-(

        Reply

        1. Your settings look good.

          But be aware that iOS does not force the apps to use the system proxy. Instead, apps poll the system proxy settings to receive proxy configuration. Hence, apps can bypass the proxy settings and make the connections out directly.

          Apps like whatsapp and facebook message may choose to bypass the proxy settings (but I am not 100% sure about this).

          Reply

          1. Hi!
            I should use it on server pc (work office windows pc) or on a client (iphone jailbroken)?
            Can you explain me how please!
            Read also other my comments below:
            I report to you here:
            “*I can open an SSH tunnel with kitty in work windows pc with port forwarding dynamic. But still i can surf under socks only with Safari in my iphone client :-(
            Please help me!”

            Thanks again ^^

            Reply

          2. Hi Willy,

            sshuttle runs on the client (your iOS).

            As noted, I did not ever tried it on iOS. Neither do I know whether it works and how hard to make it work.

            Please check the shuttle manuals online and see whether you can make it work for you. We would be happy to know the results.

            Reply

  7. Update:
    I can open an SSH tunnel with kitty over work proxy with port forwarding dynamic.

    In the proxy.pac i set workPCip:PORTforwarded

    But still i can surf under socks only with Safari :-(

    Please help me!

    Reply

  9. Hi! How can I run sshuttle on Iphone? I think impossible.. on manuals nothing written, no istructions to follow for iphone :(

    Reply

  11. hi, I rent a vps, and use socks5 proxy over ssh.Now i can use my laptop to connect the vps and can use proxy. However, i use your method and this is my pac file address ,but this dosent’t work on my iphone

    Reply

  14. Hey!
    Very handy tutorial, many thanks! One point tho
    $ ssh -D 8080 username@sshd_server
    wouldn’t allow other users to use the tunnel
    $ ssh -g -D 8080 username@sshd_server
    would solve this problem!

    Reply

  15. Thanks _very_ much for this. Managed to unblock Bluey for my 4 year old (wonderful Australian series!). You have absolutely made her (and my!) day.

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *