{"id":13615886,"url":"https://github.com/Jigsaw-Code/outline-ss-server","last_synced_at":"2025-04-13T21:31:49.297Z","repository":{"id":37333784,"uuid":"142062974","full_name":"Jigsaw-Code/outline-ss-server","owner":"Jigsaw-Code","description":"Outline Shadowsocks server","archived":false,"fork":true,"pushed_at":"2025-03-21T22:38:03.000Z","size":2019,"stargazers_count":769,"open_issues_count":33,"forks_count":193,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-03-27T19:20:03.669Z","etag":null,"topics":["censorship-circumvention","shadowsocks"],"latest_commit_sha":null,"homepage":"https://getoutline.org","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"fortuna/ss-example","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jigsaw-Code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2018-07-23T19:59:14.000Z","updated_at":"2025-03-27T18:04:42.000Z","dependencies_parsed_at":"2023-01-26T02:31:43.034Z","dependency_job_id":null,"html_url":"https://github.com/Jigsaw-Code/outline-ss-server","commit_stats":null,"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jigsaw-Code%2Foutline-ss-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jigsaw-Code%2Foutline-ss-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jigsaw-Code%2Foutline-ss-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jigsaw-Code%2Foutline-ss-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jigsaw-Code","download_url":"https://codeload.github.com/Jigsaw-Code/outline-ss-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248786422,"owners_count":21161447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["censorship-circumvention","shadowsocks"],"created_at":"2024-08-01T20:01:19.908Z","updated_at":"2025-04-13T21:31:44.280Z","avatar_url":"https://github.com/Jigsaw-Code.png","language":"Go","readme":"# Outline ss-server\n\n[![Build Status](https://github.com/Jigsaw-Code/outline-ss-server/actions/workflows/go.yml/badge.svg)](https://github.com/Jigsaw-Code/outline-ss-server/actions/workflows/go.yml?query=branch%3Amaster)\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/Jigsaw-Code/outline-ss-server)](https://goreportcard.com/report/github.com/Jigsaw-Code/outline-ss-server)\n[![Go Reference](https://pkg.go.dev/badge/github.com/Jigsaw-Code/outline-ss-server.svg)](https://pkg.go.dev/github.com/Jigsaw-Code/outline-ss-server)\n\n[![Mattermost](https://badgen.net/badge/Mattermost/Outline%20Community/blue)](https://community.internetfreedomfestival.org/community/channels/outline-community)\n[![Reddit](https://badgen.net/badge/Reddit/r%2Foutlinevpn/orange)](https://www.reddit.com/r/outlinevpn/)\n\nThis repository has the Shadowsocks backend used by the [Outline Server](https://github.com/Jigsaw-Code/outline-server).\n\nThe Outline Shadowsocks service allows for:\n- Multiple users on a single port.\n  - Does so by trying all the different credentials until one succeeds.\n- Multiple ports\n- Whitebox monitoring of the service using [prometheus.io](https://prometheus.io)\n  - Includes traffic measurements and other health indicators.\n- Live updates via config change + SIGHUP\n- Replay defense (add `--replay_history 10000`).  See [PROBES](service/PROBES.md) for details.\n\n![Graphana Dashboard](https://user-images.githubusercontent.com/113565/44177062-419d7700-a0ba-11e8-9621-db519692ff6c.png \"Graphana Dashboard\")\n\n## How to run it\n\nCall the `outline-ss-server` command with the recommended flags, [as done by the official Outline Server](https://github.com/Jigsaw-Code/outline-server/blob/b2639d09c30a50479eddcd33b84432f57081be0c/src/shadowbox/server/outline_shadowsocks_server.ts#L91-L100):\n```\noutline-ss-server -replay_history=10000 -metrics=127.0.0.1:9091 -config=$CONFIG_YML  -ip_country_db=$COUNTRY_MMDB -ip_asn_db=$ASN_MMDB\n```\n\nFlags:\n- `replay_history`: Enables replay protection for the last 10000 connections.\n- `metrics`: Where the webserver exposing the Prometheus metrics will listen on. You should specify localhost so it's not accessible from outside the machine, unless you know what you are doing.\n- `config`: The config file with the access keys. See the config example.\n- `ip_country_db`: The IP-Country MMDB file to enable per-country metrics breakdown.\n- `ip_asn_db`: The IP-ASN MMDB file to enable per-country metrics breakdown.\n\nIn the example, you can open https://127.0.0.1:9091 on your browser to see the exported Prometheus metrics.\n\nTo fetch and update MMDB files from [DB-IP](https://db-ip.com), you can do something like the [update_mmdb.sh from the Outline Server](https://github.com/Jigsaw-Code/outline-server/blob/master/src/shadowbox/scripts/update_mmdb.sh).\n\n\n## Full Working Example: Try It!\n\nDownload the [Prometheus](https://prometheus.io/download/) binary.\n\n\n### Run the server\nOn Terminal 1, from the repository directory, build and start the SS server:\n```\ngo run ./cmd/outline-ss-server -config cmd/outline-ss-server/config_example.yml -metrics localhost:9091 --replay_history=10000\n```\nIn production, you may want to specify `-ip_country_db` to get per-country metrics. See [how the Outline Server calls outline-ss-server](https://github.com/Jigsaw-Code/outline-server/blob/master/src/shadowbox/server/outline_shadowsocks_server.ts).\n\n\n### Run the Prometheus scraper for metrics collection\nOn Terminal 2, start prometheus scraper for metrics collection:\n```\nprometheus --config.file=cmd/outline-ss-server/prometheus_example.yml\n```\n\n### Run the SOCKS-to-Shadowsocks client\nOn Terminal 3, start the SS client:\n```\ngo run github.com/shadowsocks/go-shadowsocks2@latest -c ss://chacha20-ietf-poly1305:Secret0@:9000 -verbose  -socks localhost:1080\n```\n\n### Fetch a page over Shadowsocks\nOn Terminal 4, fetch a page using the SS client:\n```\ncurl --proxy socks5h://localhost:1080 example.com\n```\n\nStop and restart the client on Terminal 3 with \"Secret1\" as the password and try to fetch the page again on Terminal 4.\n\n### Check the metrics\nOpen http://localhost:9091/metrics and see the exported Prometheus variables.\n\nOpen http://localhost:9090/ and see the Prometheus server dashboard.\n\n\n## Performance Testing\n\nStart the iperf3 server (runs on port 5201 by default):\n```\niperf3 -s\n```\n\nStart the SS server (listening on port 9000):\n```\ngo run ./cmd/outline-ss-server -config cmd/outline-ss-server/config_example.yml\n```\n\nStart the SS tunnel to redirect port 8000 -\u003e localhost:5201 via the proxy on 9000:\n```\ngo run github.com/shadowsocks/go-shadowsocks2@latest -c ss://chacha20-ietf-poly1305:Secret0@:9000 -tcptun \":8000=localhost:5201\" -udptun \":8000=localhost:5201\" -verbose\n```\n\nTest TCP upload (client -\u003e server):\n```\niperf3 -c localhost -p 8000\n```\n\nTest TCP download (server -\u003e client):\n```\niperf3 -c localhost -p 8000 --reverse\n```\n\nTest UDP upload:\n```\niperf3 -c localhost -p 8000 --udp -b 0\n```\n\nTest UDP download:\n```\niperf3 -c localhost -p 8000 --udp -b 0 --reverse\n```\n\n### Compare to go-shadowsocks2\n\nRun the commands above, but start the SS server with\n```\ngo run github.com/shadowsocks/go-shadowsocks2 -s ss://chacha20-ietf-poly1305:Secret0@:9000 -verbose\n```\n\n\n### Compare to shadowsocks-libev \n\nStart the SS server (listening on port 10001):\n```\nss-server -s localhost -p 10001 -m chacha20-ietf-poly1305 -k Secret1 -u -v\n```\n\nStart the SS tunnel to redirect port 10002 -\u003e localhost:5201 via the proxy on 10001:\n```\nss-tunnel -s localhost -p 10001 -m chacha20-ietf-poly1305 -k Secret1 -l 10002 -L localhost:5201 -u -v\n```\n\nRun the iperf3 client tests listed above on port 10002.\n\nYou can mix and match the libev and go servers and clients.\n\n## Tests and Benchmarks\n\nTo run the tests and benchmarks, call:\n```\ngo run github.com/go-task/task/v3/cmd/task test\n```\n\nYou can benchmark the cipher finding code with\n```\ngo test -cpuprofile cpu.prof -memprofile mem.prof -bench . -benchmem -run=^$ github.com/Jigsaw-Code/outline-ss-server/shadowsocks\n```\n\nYou can inspect the CPU or memory profiles with `go tool pprof cpu.prof` or `go tool pprof mem.prof`, and then enter `web` on the prompt.\n\n## Release\n\nWe use [GoReleaser](https://goreleaser.com/) to build and upload binaries to our [GitHub releases](https://github.com/Jigsaw-Code/outline-ss-server/releases).\n\nSummary:\n- Test the build locally:\n  ```\n  go run github.com/go-task/task/v3/cmd/task release-local\n  ```\n- Export an environment variable named `GITHUB_TOKEN` with a temporary repo-scoped GitHub token ([create one here](https://github.com/settings/tokens/new)):\n  ```bash\n  read -s -p \"Type your Github token:\" GITHUB_TOKEN\n  export GITHUB_TOKEN\n  ```\n- Create a new tag and push it to GitHub e.g.:\n  ```bash\n  git tag v1.0.0\n  git push origin v1.0.0\n  ```\n- Build and upload:\n  ```bash\n  go run github.com/go-task/task/v3/cmd/task release\n  ```\n- Go to https://github.com/Jigsaw-Code/outline-ss-server/releases, review and publish the release.\n\n- Delete the Github token you created for the release on the [Personal Access Tokens page](https://github.com/settings/tokens).\n\nFull instructions in [GoReleaser's Quick Start](https://goreleaser.com/quick-start) (jump to the section starting \"You’ll need to export a GITHUB_TOKEN environment variable\").\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJigsaw-Code%2Foutline-ss-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJigsaw-Code%2Foutline-ss-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJigsaw-Code%2Foutline-ss-server/lists"}