Skip to content

EN User Guide

Jump to bottom
SlimRG edited this page Aug 23, 2026 · 1 revision

Shadowsocks Reborn — User Guide

English guide | Русское руководство | 中文使用说明 | README

shadowsocks-reborn is a modern Windows continuation of the classic Shadowsocks for Windows client. Version 5.2.31 targets .NET 10, WinUI 3 / Windows App SDK, x64, Windows 10 build 19041+ and Windows 11.

This is an independent fork, not the upstream shadowsocks/shadowsocks-windows repository.

What is included

  • WinUI 3 desktop UI and notification-area menu.
  • Multiple Shadowsocks servers, QR import/export and ss:// protocol handling.
  • Local SOCKS5, managed HTTP/1.1 forward proxy and HTTPS CONNECT tunnelling.
  • UDP relay.
  • User Mode and elevated Admin Mode.
  • WinDivert-based transparent TCP/UDP capture in Admin Mode.
  • Automatic Game Mode that suspends Admin capture for configured applications and restores it afterwards.
  • Managed C# GeoSite/EasyList/ABP network routing.
  • SIP003 plugin management, including known plugins and manual ZIP/TAR.GZ import.
  • Optional DNSCrypt/DoH resolver management; ODoH remains disabled.
  • Automatic application update with SHA-256, version and rollback checks.
  • Hotkeys, traffic/log pages, GeoSite management and disposable Clean Mode.

Download and integrity

Official release assets are:

Shadowsocks-win-x64.zip
Shadowsocks-win-x64.zip.sha256

The product ZIP contains exactly:

Shadowsocks.exe

The release is self-contained; a separate .NET Runtime installation is not required. Verify the ZIP with the sidecar or manually:

(Get-FileHash .\Shadowsocks-win-x64.zip -Algorithm SHA256).Hash

First start and servers

  1. Start Shadowsocks.exe.
  2. Open Servers and add or import a server.
  3. Configure server name, address, port, password, encryption method and optional SIP003 plugin.
  4. Select the active server and traffic mode from the application or tray.
  5. Use Share / QR to export or import ss:// server information.

Configured unnamed servers receive stable Server N names; explicit names are preserved.

Traffic modes

User Mode

User Mode requires no elevation. It does not start transparent WinDivert capture. Applications use Shadowsocks through the system proxy, Local/Online PAC, local SOCKS5 endpoint or managed HTTP proxy.

Admin Mode

Admin Mode requests UAC and activates the isolated Shadowsocks.NetworkService helper. The helper is embedded in Shadowsocks.exe, extracted on demand into the managed runtime area, validated and used for transparent WinDivert TCP/UDP capture. The UI reports broker/capture status and redirect ports.

Game Mode

Game Mode is not a third selectable traffic mode. When one of the configured games/applications is running, transparent Admin capture is suspended automatically; the configured Admin state is restored after the trigger exits.

Per-application routing

Application rules have higher priority than managed domain rules and support:

  • Proxy
  • Direct
  • Block

Local proxy

The client provides a local SOCKS5 service and a managed HTTP forward proxy.

  • HTTP: HTTP/1.1 forwarding.
  • HTTPS: CONNECT byte tunnelling; TLS can negotiate HTTP/2 end-to-end without a local HTTP/2 parser.
  • FTP gateway: not implemented.

Use the ports shown in the application settings rather than assuming a fixed port.

Local PAC and managed C# routing

Local GeoSite + EasyList/ABP filtering is entirely managed C#. The old bundled abp.js, compiled-PAC compatibility backend, backend selector and executable custom abp.txt override are removed.

The Local PAC exists only because Windows system proxy/PAC clients need a PAC endpoint. It contains a tiny FindProxyForURL funnel that sends eligible HTTP/HTTPS traffic to ManagedHttpProxyService; it does not evaluate EasyList/ABP rules.

Routing order is:

request
  ↓
application rule (if any)
  ↓
immutable GeoSite + user-rule.txt snapshot
  ↓
C# Shadowsocks.Routing.FilterEngine
  ↓
DIRECT or PROXY

The managed matcher supports the network-rule subset used by the project, including domain anchors, start/end anchors, wildcards, separators, explicit regular expressions, $domain= and $match-case. Cosmetic browser filtering is outside the client scope. In Local mode the PAC / GeoSite page provides Open user-rule.txt; these user rules are evaluated before GeoSite defaults, watched for changes and atomically republished. The Local managed-routing, user-rule and GeoSite cards are hidden when Online PAC is selected.

In Admin Mode, unmatched TCP can be deferred until the transparent relay sees HTTP Host or TLS ClientHello SNI. HTTP can provide path/query context; TLS provides hostname only. Shadowsocks does not decrypt TLS, install a CA or replace certificates. UDP and protocols without usable Host/SNI use deterministic fallback routing.

Online PAC

Online PAC is a separate, explicit compatibility feature. If enabled, the selected external PAC program is authoritative and is executed by the Windows PAC environment. It is not the Local EasyList/ABP engine and cannot be losslessly converted into ABP rules in the general case.

DNS and DNSCrypt

The DNS page provides the following policies in Administrator Mode:

  • System — preserve normal system DNS behavior under the transparent-routing contract.
  • Direct — send classic DNS directly according to configured resolver rules.
  • Proxy — route classic UDP/TCP DNS through Shadowsocks.
  • CustomDoh — send DNS wire messages to the configured HTTPS endpoint, with its own Shadowsocks-route option.
  • DnsCrypt — redirect to the managed local dnscrypt-proxy listener.

The application does not bundle dnscrypt-proxy.exe. When requested, it obtains the official Windows x64 component, verifies signed release material and manages it below the current storage root. On the first install/enable path the DNS page keeps an animated operation card visible for download, verification, installation and activation, while unavailable DNSCrypt settings remain hidden until activation completes.

Automatic resolver selection applies the configured DNSSEC/no-log/no-filter/IPv4/IPv6 requirements to the signed catalog. Resolver geography is derived from endpoint IP GeoIP data rather than names or descriptions. Manual mode can select signed DNSCrypt/DoH resolvers; ODoH is disabled. Runtime DNSCrypt failures are fail-closed rather than silently falling back to plaintext system DNS.

User Mode does not transparently intercept arbitrary system DNS. Game Mode suspends system-level DNS interception together with Admin capture.

SIP003 plugins

The Plugins page manages SIP003 plugins. Known choices include xray-plugin, v2ray-plugin and qtun; plugins can also be imported from ZIP/TAR.GZ archives. When an imported ss:// configuration names a known catalog plugin that is not installed, the Share / QR page offers to install it before the server is imported (with an explicit import-without-plugin alternative). Installed plugin files live below the active storage root and server configurations refer to them by plugin ID.

Built-in catalog installation fetches the latest Windows x64 release when Install is pressed and stores trusted repository/release/asset provenance in the managed package metadata. Catalog-installed plugins are checked automatically once per day while the application is running; an in-use plugin is deferred until a later check. Check updates forces an immediate pass, and Automatic updates can be disabled per managed catalog plugin. A failed network/release check does not consume the daily success window, so maintenance can retry later.

Updates are extracted into bounded staging storage and promoted with rollback-safe directory replacement. Unsafe archive paths, Windows alternate-data-stream names and TAR link/special entries are rejected; when GitHub supplies an asset SHA-256 digest it is verified before installation. Manual ZIP/TAR.GZ imports never participate in background network updates. An arbitrary custom repository field is intentionally deferred until a separate repository-trust and asset-selection design is implemented.

Automatic application updates

The updater:

  1. checks GitHub Releases;
  2. selects only an eligible newer version;
  3. downloads Shadowsocks-win-x64.zip and its .sha256 sidecar;
  4. validates SHA-256 and archive layout;
  5. validates the replacement EXE version;
  6. stages the transaction under %TEMP%\Shadowsocks\Updates;
  7. launches a separately verified updater copy;
  8. waits for the current process to exit;
  9. creates rollback state and replaces the primary EXE;
  10. launches the updated primary copy;
  11. removes intermediate transaction files.

A stale startup copy does not redefine the installed version: update selection is aware of the primary executable.

Start with Windows

In normal mode, Start with Windows synchronizes a validated copy to:

%LOCALAPPDATA%\Shadowsocks\Startup\Shadowsocks.exe

The Run entry points to that stable copy and preserves the original product path through startup metadata. Matching legacy Run entries are migrated/removed. A process-level single-instance gate prevents the startup copy and original executable from becoming two simultaneous controller owners.

Clean Mode does not support Start with Windows.

Storage

Normal persistent state lives below:

%LOCALAPPDATA%\Shadowsocks

This includes settings, rollback settings snapshot, logs, PAC/GeoSite cache, plugins, startup copy and managed runtime/component data. See Storage policy for the exact ownership model.

Clean Mode

Rename the executable so its stem ends in p, for example:

Shadowsocksp.exe
Shadowsocks-5.2p.exe

The application then creates an isolated session below %TEMP%\Shadowsocks\Clean\.... Settings, caches, logs, plugins and downloaded runtime state remain inside that disposable tree and are removed on normal shutdown on a best-effort basis.

Hotkeys, logs and diagnostics

The Hotkeys page can register actions at startup and reports registration conflicts. The Logs page provides selectable text, severity highlighting, horizontal scrolling, live refresh and bounded read/history behavior. PAC/GeoSite, traffic and DNS pages expose local operational diagnostics; domain/URL routing decisions are not uploaded as telemetry by the managed matcher.

Build from source

Use Windows with .NET SDK 10.0.303 or newer. Directory.Build.props is the canonical product version source.

dotnet restore .\shadowsocks-reborn.sln -p:Platform=x64 -r win-x64
dotnet build .\shadowsocks-reborn.sln -c Release -p:Platform=x64 -m:1 --no-restore
dotnet test .\Shadowsocks.UnitTests\Shadowsocks.UnitTests.csproj -c Release -p:Platform=x64 --no-build

Before a release:

.\packaging\Validate-Repository.ps1
.\packaging\Build-Release.ps1

Build-Release.ps1 validates metadata, runs restore/build/tests with release NuGet audit, publishes the self-contained product, verifies that only Shadowsocks.exe remains, checks FileVersion and creates the ZIP plus SHA-256 sidecar.

Security and licensing

Shadowsocks Reborn is distributed under GPL-3.0-or-later. Legal text is embedded in the one-file product and available from About. Third-party components keep their own licenses.

More documentation

DNSCrypt resolver-catalog bootstrap

Shadowsocks Reborn refreshes the signed DNSCrypt resolver catalog itself instead of allowing dnscrypt-proxy to bootstrap remote source hostnames. Cloudflare DoH (1.1.1.1, TLS/SNI cloudflare-dns.com) is the primary resolver and Google DoH (8.8.8.8, TLS/SNI dns.google) is the fallback; both DoH HTTPS connections are opened through the active local Shadowsocks SOCKS5 listener. The HTTPS download of public-resolvers.md and .minisig also travels through Shadowsocks after the source hostname is resolved by that DoH path.

The downloaded pair is size-bounded and verified with the pinned DNSCrypt public Minisign key before publication. dnscrypt-proxy then receives only the local authenticated cache with urls = [], bootstrap_resolvers = [] and ignore_system_dns = true. If refresh is temporarily unavailable, an existing valid signed cache may continue to be used; without a valid cache the operation fails closed and the previous DNS mode is retained.

Clone this wiki locally