SSR management client with shell interface
Project description
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.6git
for SSR installationlsof
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.