Skip to content
Intermediate / 9 min read

How to Configure IPRoyal Shadowsocks Proxies on Linux for Privacy-Focused CLI and Browser Traffic

Set up IPRoyal Shadowsocks on Linux with shadowsocks-libev, run it as a systemd service, verify your outbound IP, and route curl, Git, Python, and browser traffic through a local SOCKS5 proxy.

Linux SOCKS5 Shadowsocks Privacy/Anonymity

Overview

Shadowsocks is a SOCKS5-based encrypted proxy protocol. On Linux, a local Shadowsocks client listens on 127.0.0.1:1080, encrypts traffic, and forwards it to a remote Shadowsocks endpoint. This lets you route selected CLI tools, browsers, or system traffic through an IPRoyal Shadowsocks endpoint without changing your whole network stack.

This tutorial shows how to configure IPRoyal Shadowsocks proxies on Linux using shadowsocks-libev, run the client as a systemd service, verify your outbound IP, and route common tools such as curl, git, Python, and Firefox through the local SOCKS5 listener. IPRoyal is used as the example provider because it lists residential, ISP, and datacenter proxies with HTTP, SOCKS5, and Shadowsocks support. If you use another provider, replace the credentials and server details with your own.

Prerequisites

  • A Linux distribution with systemd, such as Ubuntu, Debian, Fedora, Arch Linux, or a compatible server or desktop.
  • sudo or root access for installation and service management.
  • An IPRoyal account with Shadowsocks credentials: server address, server port, password, and encryption method.
  • Basic familiarity with the terminal and text editors such as nano or vim.
  • Optional: curl for testing.

How IPRoyal Shadowsocks fits into a Linux setup

Shadowsocks is not an HTTP proxy. It creates an encrypted tunnel to a remote endpoint and exposes a local SOCKS5 proxy. Your applications must be configured to use that local SOCKS5 proxy, or you can selectively route traffic through it.

A typical flow:

  1. An application connects to 127.0.0.1:1080.
  2. The local Shadowsocks client encrypts the request.
  3. The encrypted request goes to the IPRoyal Shadowsocks endpoint.
  4. The endpoint forwards the request to the destination site.
  5. The response returns through the same tunnel.

Because the local listener is SOCKS5, you can use it with tools that support SOCKS5 or socks5h (SOCKS5 with remote DNS resolution). Use socks5h when you want DNS queries to resolve through the proxy rather than on your local machine.

Steps

Step 1: Install a Shadowsocks client on Linux

Install shadowsocks-libev, which provides the ss-local client and works well with systemd.

For Debian or Ubuntu:

sudo apt update
sudo apt install shadowsocks-libev

For Fedora or RHEL-family distributions:

sudo dnf install shadowsocks-libev

For Arch Linux:

sudo pacman -S shadowsocks-libev

If your distribution does not package shadowsocks-libev, you can install shadowsocks-rust from your package manager or build it from source. The configuration concepts below are the same, though the binary names may differ.

Step 2: Create the IPRoyal Shadowsocks environment file

Create an environment file that contains the IPRoyal Shadowsocks endpoint details. Replace the placeholder values with the exact server, port, password, and method from your IPRoyal dashboard.

sudo mkdir -p /etc/iproyal
sudo nano /etc/iproyal/shadowsocks.env

Add the following values:

SS_SERVER=YOUR_IPROYAL_SERVER
SS_PORT=8388
SS_PASSWORD=YOUR_IPROYAL_PASSWORD
SS_METHOD=aes-256-gcm
SS_LOCAL_ADDRESS=127.0.0.1
SS_LOCAL_PORT=1080

Notes:

  • Use the encryption method exactly as provided by IPRoyal. Common methods include aes-256-gcm, chacha20-ietf-poly1305, and aes-128-gcm, but the endpoint must support the method you choose.
  • If IPRoyal gives you a SOCKS5 endpoint instead of a Shadowsocks endpoint, use a SOCKS5 client configuration or a tool such as ProxyChains instead of Shadowsocks.
  • Keep the file readable only by root if it contains credentials:
sudo chmod 600 /etc/iproyal/shadowsocks.env

Step 3: Test the configuration in the foreground

Before creating a service, run the client in the foreground to confirm that the credentials and network path work.

sudo ss-local -s YOUR_IPROYAL_SERVER -p 8388 -b 127.0.0.1 -l 1080 -k YOUR_IPROYAL_PASSWORD -m aes-256-gcm -u -v

Leave that terminal open. In a second terminal, test the local SOCKS5 listener:

curl --socks5-hostname 127.0.0.1:1080 https://ifconfig.me

If the command returns an IP address that differs from your normal public IP, the tunnel is working. Press Ctrl+C in the first terminal to stop the foreground client.

Step 4: Run the Shadowsocks client as a systemd service

Create a systemd unit so the client starts at boot and restarts after failures.

sudo nano /etc/systemd/system/iproyal-shadowsocks.service

Add:

[Unit]
Description=IPRoyal Shadowsocks local client
After=network-online.target
Wants=network-online.target

[Service]
EnvironmentFile=/etc/iproyal/shadowsocks.env
ExecStart=/usr/bin/ss-local -s ${SS_SERVER} -p ${SS_PORT} -b ${SS_LOCAL_ADDRESS} -l ${SS_LOCAL_PORT} -k ${SS_PASSWORD} -m ${SS_METHOD} -u
Restart=on-failure
RestartSec=5
LimitNOFILE=32768

[Install]
WantedBy=multi-user.target

Adjust the ExecStart path if your ss-local binary is elsewhere. You can find it with:

command -v ss-local

If your provider does not support UDP relay, remove -u from the ExecStart line.

Reload systemd and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now iproyal-shadowsocks
sudo systemctl status iproyal-shadowsocks

Step 5: Verify the local SOCKS5 listener and outbound IP

Check that the client is listening locally:

ss -ltnp | grep 1080

Then verify the outbound IP through the proxy:

curl --socks5-hostname 127.0.0.1:1080 https://ifconfig.me
curl --socks5-hostname 127.0.0.1:1080 https://ipinfo.io/ip

Compare the result with your direct connection:

curl https://ifconfig.me

If the addresses differ, the local client is forwarding traffic through the IPRoyal Shadowsocks endpoint. If they match, see the troubleshooting section below.

Step 6: Route CLI tools through the local SOCKS5 proxy

Use the local SOCKS5 listener with tools that support SOCKS5. Prefer socks5h so DNS resolution happens through the proxy.

For curl:

curl --socks5-hostname 127.0.0.1:1080 https://httpbin.org/ip

For git:

git config --global http.proxy socks5h://127.0.0.1:1080
git config --global https.proxy socks5h://127.0.0.1:1080

To remove those Git proxy settings later:

git config --global --unset http.proxy
git config --global --unset https.proxy

For Python requests, install SOCKS support and use the proxy:

python3 -m pip install 'requests[socks]'

import requests

proxies = {
    'http': 'socks5h://127.0.0.1:1080',
    'https': 'socks5h://127.0.0.1:1080',
}

response = requests.get('https://httpbin.org/ip', proxies=proxies, timeout=30)
print(response.json())

For wget, use a SOCKS5-compatible wrapper or environment variables where supported. curl and Python usually provide the least ambiguous behavior for SOCKS5 testing.

Step 7: Configure a browser or desktop proxy

For Firefox, open Settings, search for Network Settings, choose Manual proxy configuration, and set:

  • SOCKS Host: 127.0.0.1
  • Port: 1080
  • SOCKS v5: selected
  • Proxy DNS when using SOCKS v5: enabled

For GNOME desktop environments, you can set the system proxy manually:

gsettings set org.gnome.system.proxy mode 'manual'
gsettings set org.gnome.system.proxy.socks host '127.0.0.1'
gsettings set org.gnome.system.proxy.socks port 1080

To return to a direct connection:

gsettings set org.gnome.system.proxy mode 'none'

Not every application respects system proxy settings. When in doubt, configure the proxy directly in the application or use a SOCKS5-aware wrapper.

Step 8: Confirm DNS and leak behavior

Run a request that reports the resolver and IP:

curl --socks5-hostname 127.0.0.1:1080 https://ipinfo.io/json

Check whether the reported IP belongs to the proxy endpoint. Because socks5h sends the hostname to the proxy for resolution, local DNS queries are avoided for that request. If you use socks5:// instead, the hostname may be resolved locally first, which can leak DNS information.

Troubleshooting

The service starts but the IP does not change

  • Confirm that your test command uses --socks5-hostname or socks5h://, not a direct connection.
  • Check the service logs:
journalctl -u iproyal-shadowsocks -e
  • Verify that the server address, port, password, and encryption method match the IPRoyal dashboard exactly.
  • Test with a different destination such as https://httpbin.org/ip to rule out site-specific behavior.

ss-local fails with an authentication or method error

  • The encryption method must match the remote endpoint. If IPRoyal provides chacha20-ietf-poly1305, do not use aes-256-gcm.
  • Check for trailing spaces or hidden characters in the password field.
  • If your password contains special characters, quote it correctly in the environment file or use a config file that your client supports.
  • Run the client in verbose mode to see the exact error:
sudo ss-local -s YOUR_IPROYAL_SERVER -p 8388 -b 127.0.0.1 -l 1080 -k YOUR_IPROYAL_PASSWORD -m aes-256-gcm -u -v

Connection refused on 127.0.0.1:1080

  • Another service may already use port 1080. Check with:
sudo ss -ltnp | grep 1080
  • Change SS_LOCAL_PORT in the environment file to another value, such as 1081, restart the service, and update your client commands.
  • Confirm that the systemd service is actually running:
systemctl is-active iproyal-shadowsocks

Timeouts or slow throughput

  • Try a different IPRoyal endpoint or region if your dashboard offers multiple locations.
  • Test with TCP-only mode by removing -u from the ExecStart line if the endpoint does not support UDP.
  • Check your local firewall and network policies. Some corporate or campus networks block non-standard outbound ports.
  • Reduce timeout values only for testing; very low timeouts can cause false failures on slow links.

Browser traffic does not use the proxy

  • In Firefox, make sure SOCKS v5 is selected and Proxy DNS when using SOCKS v5 is enabled.
  • If using GNOME settings, remember that only some applications honor the system proxy.
  • Test the same destination with curl --socks5-hostname to confirm the local SOCKS5 listener works independently of the browser.

Summary

You configured an IPRoyal Shadowsocks endpoint on Linux by installing shadowsocks-libev, creating a local client configuration, running it as a systemd service, and verifying the outbound IP through a local SOCKS5 listener. You also learned how to route curl, Git, Python requests, and browser traffic through 127.0.0.1:1080, and how to troubleshoot common authentication, port, DNS, and timeout issues. IPRoyal is one provider to consider when you need residential, ISP, or datacenter proxies with SOCKS5 and Shadowsocks-style support; always confirm the exact protocol and credentials in your provider dashboard before configuring clients.