Home

Awesome

🌐 Shadowsocks URI Generator

Build Release Nuget AUR version AUR version AUR version AUR version

Shadowsocks URI Generator is a management and distribution platform for censorship circumvention services.

Features

Build

Prerequisites: .NET 8 SDK

Note for packagers: The application by default uses executable directory as config directory. To use user's config directory, define the constant PACKAGED when building.

$ # Build with Release configuration
$ dotnet build -c Release

$ # Publish as framework-dependent
$ dotnet publish ShadowsocksUriGenerator -c Release

$ # Publish as self-contained for Linux x64
$ dotnet publish ShadowsocksUriGenerator -c Release \
    -p:PublishSingleFile=true \
    -p:PublishTrimmed=true \
    -p:DebuggerSupport=false \
    -p:EnableUnsafeBinaryFormatterSerialization=false \
    -p:EnableUnsafeUTF7Encoding=false \
    -p:InvariantGlobalization=true \
    -r linux-x64 --self-contained

$ # Publish as self-contained for packaging on Linux x64
$ dotnet publish ShadowsocksUriGenerator -c Release \
    -p:DefineConstants=PACKAGED \
    -p:PublishSingleFile=true \
    -p:PublishTrimmed=true \
    -p:DebuggerSupport=false \
    -p:EnableUnsafeBinaryFormatterSerialization=false \
    -p:EnableUnsafeUTF7Encoding=false \
    -p:InvariantGlobalization=true \
    -r linux-x64 --self-contained

API Server

The API Server provides an API endpoint for basic management tasks and online config.

To start the server, simple run the binary or start the systemd service:

$ ss-uri-gen-server

$ systemctl --user enable --now ss-uri-gen-server.service

When built with PACKAGED, it searches for appsettings.json in Shadowsocks URI Generator's config directory. Make sure to supplement appsettings.json before starting the server.

Some appsettings.json samples are included in the project directory. appsettings.systemd.json is configured to use the systemd logging format.

To generate API URLs and tokens, make sure to set ApiServerBaseUrl and ApiServerSecretPath:

$ # Set ApiServerBaseUrl and ApiServerSecretPath.
$ ss-uri-gen settings set --api-server-base-url https://example.com --api-server-secret-path 8c1da4d8-8684-4a2c-9abb-57b9d5fa7e52
$ # Get API URLs and tokens from CLI.
$ ss-uri-gen online-config get-links

Linked Telegram users can get their API URLs and tokens from the Telegram bot by executing /get_online_config_links.

CLI

The CLI is the primary management tool for Shadowsocks URI Generator.

$ # See usage guide.
$ ss-uri-gen --help

$ # Enter interactive mode (REPL).
$ ss-uri-gen interactive

$ # Run as a service to execute scheduled tasks.
$ ss-uri-gen service --interval 3600 --pull-outline-server --generate-online-config

$ # Add users.
$ ss-uri-gen user add MyUserA MyUserB

$ # Add groups.
$ ss-uri-gen group add MyGroupA MyGroupB

$ # Add a new node.
$ ss-uri-gen node add MyGroupA MyNodeA 1.1.1.1 853

$ # Add a new node with v2ray-plugin.
$ ss-uri-gen node add MyGroupB MyNodeB 1.1.1.1 853 --plugin v2ray-plugin --plugin-opts "tls;host=cloudflare-dns.com"

$ # Deactivate a node to exclude it from delivery.
$ ss-uri-gen node deactivate MyGroupB MyNodeB

$ # Join a group.
$ ss-uri-gen user join MyUserB MyGroupB

$ # Add multiple users to a group.
$ ss-uri-gen group add-user MyGroupA MyUserA MyUserB

$ # Add a credential associating MyGroupA with MyUserA.
$ ss-uri-gen user add-credential MyUserA MyGroupA --method aes-256-gcm --password MyPassword

$ # Add a credential in base64url.
$ ss-uri-gen user add-credential MyUserB MyGroupA --userinfo-base64url eGNoYWNoYTIwLWlldGYtcG9seTEzMDU6TXlQYXNzd29yZA

$ # Print a user's ss:// links.
$ ss-uri-gen user get-ss-links MyUserA

$ # Get a user's data usage metrics.
$ ss-uri-gen user get-data-usage MyUserA

$ # Get a group's data usage metrics.
$ ss-uri-gen group get-data-usage MyGroupA

$ # Generate Open Online Config (OOC) v1 files.
$ ss-uri-gen online-config generate

$ # Print all users' Open Online Config (OOC) v1 delivery URLs.
$ ss-uri-gen online-config get-links

$ # Associate a group with an Outline server.
$ ss-uri-gen outline-server add MyGroupA '{"apiUrl":"https://localhost/example","certSha256":"EXAMPLE"}'

$ # Change Outline server settings.
$ ss-uri-gen outline-server set MyGroupA --name MyOutlineA --hostname github.com --metrics true

$ # Pull updates from Outline server.
$ ss-uri-gen outline-server pull MyGroupA

$ # Deploy local configuration to Outline server.
$ ss-uri-gen outline-server deploy MyGroupA

$ # Generate data usage report and export as CSV to current directory.
$ ss-uri-gen report --csv-outdir .

$ # Set default user for Outline server's access key id 0.
$ ss-uri-gen settings set --outline-server-global-default-user MyUserA

$ # Settings: change the online configuration generation output directory to 'sip008'.
$ ss-uri-gen settings set --online-config-output-directory sip008

$ # Rescue tool: rebuild database from generated online config.
$ ss-uri-gen-rescue --online-config-dir /path/to/online/config

Telegram Bot

The Telegram bot can act as a client portal for your service. The user ID is used as the secret key for authentication.

Send your users their user ID, so they can use /link <user_id> to link their Telegram account to their registered user.

See the full command list for what the bot can do. Some commands can be disabled in the config.

To host your Telegram bot, register a bot at Bot Father and get the bot token. Then choose one of the following methods:

$ # Method 1: Set the bot token in the config.
$ ss-uri-gen-chatbot-telegram config set --bot-token "1234567:4TT8bAc8GHUspu3ERYn-KGcvsvGB9u_n4ddy"
$ # Start the bot.
$ ss-uri-gen-chatbot-telegram

$ # Method 2: Set the bot token as an environment variable.
$ export TELEGRAM_BOT_TOKEN="1234567:4TT8bAc8GHUspu3ERYn-KGcvsvGB9u_n4ddy"
$ # Start the bot.
$ ss-uri-gen-chatbot-telegram

$ # Method 3: Start the bot and pass the bot token as an argument.
$ ss-uri-gen-chatbot-telegram --bot-token "1234567:4TT8bAc8GHUspu3ERYn-KGcvsvGB9u_n4ddy"

License

© 2024 database64128