myl7 / ssrcli

SSR management client on Linux with command line interface

ssrcli

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

ssrcli's Issues

Todo list

A

• SSR integration
• Speed test & location test
• PAC support
• Multi-instance

B

• pacman-style CLI
• Check test coverage
• Interactive add
• HTTP API
• GUI