Skip to main content

SSR management client with shell interface

Project description

ssrcli

Build Status codecov.io Code Coverage Known Vulnerabilities Maintainability

SSR management client on Linux with command line interface

Features

  • Command line interface, which is friendly for headless environment
  • All-in-one management for SSR application, configuration and subscription
  • pacman-style commands, which is short and easy for use
  • Support subscription update, configuration share URL and more useful function

Prerequisites

  • Python >= 3.6
  • git for SSR installation
  • lsof to check local port

Get Started

First install this package from PyPI:

pip3 install ssrcli

Then use ssrcli to install SSR:

ssrcli --install

Following XDG Base Directory Specification, SSR will be downloaded to ~/.local/share/shadowsocksr

Then add your SSR configuration using ssrcli and use it. For example, if you have a SSR subscription url, do:

# Add a subscription
ssrcli -Saj '{"name": "<the name>", "url": "<the url>"}'
# Update all subscription
ssrcli -Sua
# List all got configuration
ssrcli -Cla
# Choose one. With its id, use the configuration
ssrcli -Csc '<the id>'
# Start SSR
ssrcli -O
# Or restart SSR, which would ensure SSR is on
ssrcli -R

For more information, refer to the below content of this readme or ssrcli -h

Config

We recommend not to use a custom ssrcli config file for the default config is enough and good

ssrcli will go through XDG_CONFIG_DIRS to search for ssrcli/ssrcli-config.json to load. Following XDG Standard, you should put your config file as ~/.config/ssrcli/ssrcli-config.json. This is a JSON file which can optionally contains the below options. Both upper case and lower case is OK.

Name Default Value Description
DB_PATH ~/.local/share/ssrcli/db.sqlite3 Path to the database file containing all data
SSR_APP_PATH ~/.local/share/shadowsocksr Path to the folder containing SSR
SSR_CONF_PATH ~/.config/ssrcli/ssr-config.json Path to the SSR config file
SSR_LOCAL_PORT 1080 Local port used by SSR
SSR_CONF_EXTRA_FIELDS See below Extra JSON content added to SSR config file
UPDATE_TIMEOUT 10 Timeout when updating (Unit: s)
UPDATE_RETRY 5 Retry times when update failed

The default value of SSR_CONF_EXTRA_FIELDS is:

{
  "local_address": "127.0.0.1",
  "local_port": "$SSR_LOCAL_PORT",
  "timeout": 300
}

In this JSON $SSR_LOCAL_PORT will be replaced by the same-name config argument SSR_LOCAL_PORT

Usage

Show help and version:

More options could be found here

ssrcli -h
ssrcli -V

Below we shorten configuration as conf and subscription as sub

Install/remove SSR with --install and --remove

Start/stop/restart SSR with -O(on), -F(off) and -R(restart)

Test SSR integrity with --test

Manage conf with -C and sub with -S

Both conf and sub support -l(list), -n(add), -d(delete)

Conf additionally support -s(use), sub additionally support -u(update)

You can pass multi -c <id> to choose multi objects to be processed

You can pass -j <json> to provide information. The option value should be a valid JSON with all required fields.

You can add -a to perform action on all objects, and usually without -a, the default objects of a action is all objects except for -d(delete). Without given objects -d(delete) will raise a exception.

As for update, when updating a sub, all old conf belonging to the sub will be removed

You can pass -r(current) to ssrcli when using -l(list) to show currently used SSR conf

For more information, type ssrcli -h to read. The below is some examples:

# Show help
ssrcli -h
# Add a conf from JSON
ssrcli -Caj '{
  "server": "::1",
  "server_port": 30000,
  "protocol": "origin",
  "method": "none",
  "obfs": "plain",
  "password": "test",
  "obfs_param": "",
  "protocol_param": "",
  "remarks": "test",
  "group": "test"
  }'
# Add a sub from JSON
ssrcli -Caj '{"name": "test", "url": "https://test.test"}'
# List all conf with currently used conf
ssrcli -Clar
# Update all sub with proxy
ssrcli -Suap '{"socks5": "127.0.0.1:1080"}'

Test

First install the test requirements in requirements.txt

Then Move to tests folder and start the tests with test.sh script:

cd tests  # IMPORTANT, as many tests would rely on the relative path
./test.sh

In tests, port 1080, 8001, 8002 will be used. Make sure them bindable or change the ports in test.sh and shared.py.

Internet is required to download SSR. Or you can use another pytest command in test.sh with downloading SSR to tests/shadowsocksr previously.

For the use of Popen, after a failed test port 1080 may be bind by left SSR. Just kill it.

License

MIT

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for ssrcli, version 3.1.2
Filename, size File type Python version Upload date Hashes
Filename, size ssrcli-3.1.2.tar.gz (13.6 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page