| Name | shadowsocks-manager JSON |
| Version |
0.1.5
JSON |
| download |
| home_page | https://github.com/alexzhangs/shadowsocks-manager |
| Summary | A shadowsocks manager for multi-user and traffic statistics |
| upload_time | 2024-05-06 05:00:30 |
| maintainer | None |
| docs_url | None |
| author | Alex |
| requires_python | >=2.7 |
| license | MIT License Copyright (c) 2021 Alex Zhang Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
shadowsocks
manager
django
web
statistics
cluster
celery
uwsgi
pypi
docker
github-actions
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://github.com/alexzhangs/shadowsocks-manager/)
[](https://github.com/alexzhangs/shadowsocks-manager/commits/master)
[](https://github.com/alexzhangs/shadowsocks-manager/issues)
[](https://github.com/alexzhangs/shadowsocks-manager/pulls)
[](https://github.com/alexzhangs/shadowsocks-manager/tags)
[](https://github.com/alexzhangs/shadowsocks-manager/actions/workflows/ci-unittest.yml)
[](https://github.com/alexzhangs/shadowsocks-manager/actions/workflows/ci-testpypi.yml)
[](https://github.com/alexzhangs/shadowsocks-manager/actions/workflows/ci-pypi.yml)
[](https://pypi.org/project/shadowsocks-manager/)
[](https://codecov.io/gh/alexzhangs/shadowsocks-manager)
[](https://github.com/alexzhangs/shadowsocks-manager/actions/workflows/ci-docker.yml)
[](https://hub.docker.com/r/alexzhangs/shadowsocks-manager)
# shadowsocks-manager
A web-based Shadowsocks management tool.
Features:
* Central user management
* Heartbeat on Shadowsocks ports(users)
* Shadowsocks multi-user API
* Shadowsocks node cluster
* Statistic for network traffic usage
* Scheduled jobs
* name.com API
* Auto-creating DNS records
* Production deployment ready
* How's the Shadowsocks supported:
* libev edition:
* Full functional.
* No builtin service manager, you need to install it and start the service by yourself.
* python edition:
* Lacks the collection of traffic statistics.
* Lacks the ability to test user port creation status.
* ~~Pre-installed, and have a builtin service manager.~~
* No builtin service manager, you need to install it and start the service by yourself.
Code in Python, base on Django, Django REST framework, Celery, and SQLite.
The development status can be found at: [project home](https://github.com/alexzhangs/shadowsocks-manager/projects/1).
Shadowsocks Node List:
Add Shadowsocks Node:
## 1. Requirements
* Python 2.7, Python 3.x
* Django 1.11.x, Django 3.x
* Docker
* [Shadowsocks-libev 3.2.0 for Linux (multi-user API is required)](https://github.com/shadowsocks/shadowsocks-libev)
## 2. Install
This project is a part of an entire VPN solution, which includes the Shadowsocks server and Shadowsocks manager. The Shadowsocks server serves the traffic, the Shadowsocks manager serves the users and the traffic statistics. The solution is designed to be deployed in the AWS cloud. If you are looking for such a solution, you can refer to the repo [aws-cfn-vpn](https://github.com/alexzhangs/aws-cfn-vpn). With `aws-cfn-vpn`, you can deploy the entire solution with a few commands.
### 2.1. Dependencies
Assume you have installed the [Docker](https://www.docker.com/) on your host.
### 2.2. Manual installation
```sh
# create a docker network
docker network create ssm-network
# run memcached, used by django cache
docker run -d --network ssm-network --name ssm-memcached memcached
# run rabbitmq, used by celery
docker run -d --network ssm-network --name ssm-rabbitmq rabbitmq
# create a directory to store the data, it will be mounted to the shadowsocks-manager container
mkdir -p ~/ssm-volume
# run the shadowsocks-manager
docker run -d -p 80:80 -v ~/ssm-volume:/var/local/ssm \
--network ssm-network --name ssm alexzhangs/shadowsocks-manager \
-e SSM_SECRET_KEY=yourkey -e SSM_DEBUG=False \
-e SSM_MEMCACHED_HOST=ssm-memcached -e SSM_RABBITMQ_HOST=ssm-rabbitmq \
-u admin -p yourpassword -M admin@yourdomain.com
```
### 2.3. Install with script
```sh
git clone https://github.com/alexzhangs/shadowsocks-manager
bash shadowsocks-manager/install.sh -u admin -p yourpassword -M admin@yourdomain.com
```
### 2.4. Verify the installation
If all go smoothly, the shadowsocks-manager services should have been all started. Open the web admin console in a web browser, and log on with the admin user.
Use:
```
http://<your_server_ip>/admin
or
http://localhost/admin
```
If goes well, then congratulations! The installation has succeeded.
## 3. Using shadowsocks-manager
1. Shadowsocks server
First, you need to have a Shadowsocks server with the multi-user API
enabled.
Install it with docker on the same server with shadowsocks-manager.
```sh
# run shadowsocks-libev
MGR_PORT=6001
SS_PORTS=8381-8480
ENCRYPT=aes-256-cfb
docker run -d -p $SS_PORTS:$SS_PORTS/UDP -p $SS_PORTS:$SS_PORTS \
--network ssm-network --name ssm-ss-libev shadowsocks/shadowsocks-libev:edge \
ss-manager --manager-address 0.0.0.0:$MGR_PORT \
--executable /usr/local/bin/ss-server -m $ENCRYPT -s 0.0.0.0 -u
# Use below command to get the private IP address of the shadowsocks-libev container for later configuration.
docker inspect ssm-ss-libev | grep IPAddress
```
1. Add Shadowsocks server to shadowsocks-manager
Add the Shadowsocks server as a Node of shadowsocks-manager from
web admin console: `Home › Shadowsocks › Shadowsocks Nodes`.
1. Create users(ports) and assign Shadowsocks Node
Create users from web admin console: `Home › Shadowsocks ›
Shadowsocks Accounts` and assign the existing nodes to them.
After a few seconds, the created user ports should be available to your
Shadowsocks client.
## 4. Sendmail (Optional)
`sendmail` is used to send account notification Email, it should
be configured on the same server with shadowsocks-manager.
About how to configure `sendmail` client to use AWS SES as SMTP server on AWS EC2 instance, refer to repo
[aws-ec2-ses](https://github.com/alexzhangs/aws-ec2-ses).
On macOS, refer to repo
[macos-aws-ses](https://github.com/alexzhangs/macos-aws-ses).
NOTE: This dependency needs the manual setup anyway, it is not handled by any installation script.
## 5. Differences from the alternation: [shadowsocks/shadowsocks-manager](https://github.com/shadowsocks/shadowsocks-manager)
**This repo Do's:**
* Serve as a nonprofit business model.
* Have central user management for multi nodes.
* Collect traffic statistic that can be viewed by account, node, and period.
* Show the existence and accessibility of ports in the admin.
* Handle the DNS records if using Name.com as nameserver.
**This repo Don'ts:**
* Handle self-serviced user registration.
* Handle bill or payment.
* Need to run an additional agent on each Shadowsocks server.
## 6. Some differences between the Shadowsocks Python edition (2.8.2) and libev edition
Version status for the Shadowsocks Python edition:
* pypi: [2.8.2](https://pypi.org/project/shadowsocks/)
* github: [3.0.0](https://github.com/shadowsocks/shadowsocks/tree/master)
Although the Shadowsocks Python edition
supports the multi-user API, but it doesn't fit this project, here's why:
* The python edition code and doc seem to be out of maintenance due to some reason. If you really need this you probably need to fork it and make your own.
* They are having different service process names and CLI interfaces which introduces the complexity of installation.
* The Python edition lacks the `list` commands. A pull request was opened years ago but never merged.
* The Python edition's `stat` command has a very different way to use, I didn't figure the usage syntax out by looking into the code.
* The Python edition's `ping` command returns a simple string `pong` rather than a list of ports.
* The Python edition's `ping` command has to be sent as the syntax: `ping:{}` in order to work if tested with `nc`. It caused by the tailing newline: `ping\n`.
So either you get some change on your own or stick with the libev edition.
## 7. Known Issues
1. DNS records matching for Node may not be accurate on macOS.
For unknown reason sometimes DNS query returns only one IP address
while multiple IP addresses were configured for the domain.
1. The Shadowsocks Python edition's ssserver won't start on macOS.
The error message is like:
```
$ ssserver -k passw0rd
WARNING: /Users/***/.pyenv/versions/3.12.0/envs/ssm-3.12/bin/python3.12 is loading libcrypto in an unsafe way
Abort trap: 6
```
Solution:
Link the homebrew openssl library to the system library.
```sh
sudo ln -s /opt/homebrew/opt/openssl/lib/libcrypto.dylib /usr/local/lib/
sudo ln -s /opt/homebrew/opt/openssl/lib/libssl.dylib /usr/local/lib/
```
1. Install the project by source with pip under Python 2.7 get error:
```
python --version
Python 2.7.18
pip install .
```
Error message:
```
...
Collecting pyyaml
Downloading PyYAML-5.4.1.tar.gz (175 kB)
|████████████████████████████████| 175 kB 392 kB/s
Installing build dependencies ... done
Getting requirements to build wheel ... error
ERROR: Command errored out with exit status 1:
...
raise AttributeError, attr
AttributeError: cython_sources
...
```
Solution:
```sh
pip install setuptools wheel
pip install --no-build-isolation .
```
## 8. Development
The development of this project requires Python 3.x.
However, the installation of the project is compatible with both Python 2.7 and 3.x.
To keep the compatibility is difficult, but it's kept due to the historical reason.
The following files are kept only for installing the source distribution of the PyPI package under Python 2.7:
* setup.py
* setup.cfg
### 8.1. Development Environment Setup
1. Install the dependencies
```sh
# run memcached, used by django cache
docker run -d -p 11211:11211 --name ssm-dev-memcached memcached
# run rabbitmq, used by celery
docker run -d -p 5672:5672 --name ssm-dev-rabbitmq rabbitmq
# run shadowsocks-libev, simulate localhost node
MGR_PORT=6001 SS_PORTS=8381-8479 ENCRYPT=aes-256-cfb
docker run -d -p 127.0.0.1:$MGR_PORT:$MGR_PORT/UDP \
-p 127.0.0.1:$SS_PORTS:$SS_PORTS/UDP -p 127.0.0.1:$SS_PORTS:$SS_PORTS \
--name ssm-dev-ss-libev-localhost shadowsocks/shadowsocks-libev:edge \
ss-manager --manager-address 0.0.0.0:$MGR_PORT \
--executable /usr/local/bin/ss-server -m $ENCRYPT -s 0.0.0.0 -u
# get the private IP address of the host, double check the result, it might not be correct
PRIVATE_IP=$(ipconfig getifaddr en0 2>/dev/null || hostname -i | awk '{print $1}' 2>/dev/null)
echo "PRIVATE_IP=$PRIVATE_IP"
# run shadowsocks-libev, simulate private IP node
MGR_PORT=6002 SS_PORTS=8381-8479 ENCRYPT=aes-256-cfb
docker run -d -p $PRIVATE_IP:$MGR_PORT:$MGR_PORT/UDP \
-p $PRIVATE_IP:$SS_PORTS:$SS_PORTS/UDP -p $PRIVATE_IP:$SS_PORTS:$SS_PORTS \
--name ssm-dev-ss-libev-private shadowsocks/shadowsocks-libev:edge \
ss-manager --manager-address 0.0.0.0:$MGR_PORT \
--executable /usr/local/bin/ss-server -m $ENCRYPT -s 0.0.0.0 -u
# run shadowsocks-libev, simulate public IP node
MGR_PORT=6003 SS_PORTS=8480 ENCRYPT=aes-256-cfb
docker run -d -p $PRIVATE_IP:$MGR_PORT:$MGR_PORT/UDP \
-p $PRIVATE_IP:$SS_PORTS:$SS_PORTS/UDP -p $PRIVATE_IP:$SS_PORTS:$SS_PORTS \
--name ssm-dev-ss-libev-public shadowsocks/shadowsocks-libev:edge \
ss-manager --manager-address 0.0.0.0:$MGR_PORT \
--executable /usr/local/bin/ss-server -m $ENCRYPT -s 0.0.0.0 -u
```
1. Link the project code in your workspace to the Python environment
```sh
cd shadowsocks-manager
pip install -e .
```
1. Set the SSM_DATA_HOME environment variable (optional, default is Django root directory)
```sh
export SSM_DATA_HOME=~/.ssm-dev-data
```
1. Configure the shadowsocks-manager
```sh
ssm-setup -c -m -l -u admin -p yourpassword
```
1. Run the development server
Make sure the memcached and rabbitmq are running.
```sh
ssm-dev-start
```
1. Stop the development server
```sh
ssm-dev-stop
```
1. Test the Django code
Make sure the memcached and rabbitmq are running, and also the 3 shadowsocks-libev node are running.
```sh
ssm-test -t
# or use the django test command directly for more options
ssm-manage test --no-input -v 2
```
1. Test the Django code with coverage
```sh
pip install coverage
ssm-test -c
```
1. Upload the coverage report to codecov
Make sure the `CODECOV_TOKEN` is exported in the environment before uploading.
```sh
pip install codecov-cli
ssm-test -u
```
1. Test the Github workflows locally
```sh
brew install act
act -j test
```
1. Build the PyPI package
```sh
pip install build
# build source and binary distribution, equivalent to `python setup.py sdist bdist_wheel`
# universal wheel is enabled in the pyproject.toml to make the wheel compatible with both Python 2 and 3
python -m build
```
1. Upload the PyPI package
Set the ~/.pypirc file with the API token from the TestPyPI and PyPI before uploading.
```sh
pip install twine
# upload the package to TestPyPI
python -m twine upload --repository testpypi dist/*
# upload the package to PyPI
python -m twine upload dist/*
```
1. Test the PyPI package
```sh
# install the package from TestPyPI
# --no-deps is used to skip installing dependencies for the TestPyPI environment
pip install -i https://test.pypi.org/simple/ --no-deps shadowsocks-manager
# install the package from PyPI
# --no-binary is used to force building the package from the source
# --use-pep517 is used together to make sure the PEP 517 is tested
pip install --no-binary shadowsocks-manager --use-pep517 shadowsocks-manager
```
1. Build the docker image
```sh
docker build -t alexzhangs/shadowsocks-manager .
```
### 8.2. CI/CD
Github Actions is currently used for the CI/CD.
Travis CI is removed due to the limitation of the free plan.
The CI/CD workflows are defined in the `.github/workflows` directory.
* ci-unittest.yml: Run the unit tests.
* ci-testpypi.yml: Build and upload the package to TestPyPI.
* ci-pypi.yml: Build and upload the package to PyPI. It can be triggered by the tag: `ci-pypi` or `ci-pypi-(major|minor|patch|suffx)`.
* ci-docker.yml: Build and push the docker image to Docker Hub. It can be triggered by the Github release.
## 9. Troubleshooting
1. Check the logs
```
# supervisor
cat /var/log/supervisor/supervisord.log
# uWSGI
cat /var/log/ssm-uwsgi.log
# Celery
cat /var/log/ssm-cerlery*
```
1. Check the services
```
# nginx
service nginx {status|start|stop|reload}
# supervisor
service supervisord {status|start|stop|restart}
supervisorctl reload
supervisorctl start all
# uWSGI
supervisorctl start ssm-uwsgi
# Celery
supervisorctl start ssm-celery-worker
supervisorctl start ssm-celery-beat
# Docker
docker ps
```
1. Check the listening ports and processes (Linux)
```
# TCP
netstat -tanp
# UDP
netstat -uanp
```
1. Check the listening ports (MacOS)
```
# TCP
netstat -anp tcp
# UDP
netstat -anp udp
# find the process by port
lsof -i :80 -P
```
Raw data
{
"_id": null,
"home_page": "https://github.com/alexzhangs/shadowsocks-manager",
"name": "shadowsocks-manager",
"maintainer": null,
"docs_url": null,
"requires_python": ">=2.7",
"maintainer_email": null,
"keywords": "shadowsocks, manager, django, web, statistics, cluster, celery, uwsgi, pypi, docker, github-actions",
"author": "Alex",
"author_email": "Alex <alexzhangs@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/00/17/ec0c7462815620186a6d3103f14b75cc2a46222c7be8db994200113ad7f6/shadowsocks_manager-0.1.5.tar.gz",
"platform": null,
"description": "[](https://github.com/alexzhangs/shadowsocks-manager/)\n[](https://github.com/alexzhangs/shadowsocks-manager/commits/master)\n[](https://github.com/alexzhangs/shadowsocks-manager/issues)\n[](https://github.com/alexzhangs/shadowsocks-manager/pulls)\n[](https://github.com/alexzhangs/shadowsocks-manager/tags)\n\n[](https://github.com/alexzhangs/shadowsocks-manager/actions/workflows/ci-unittest.yml)\n[](https://github.com/alexzhangs/shadowsocks-manager/actions/workflows/ci-testpypi.yml)\n[](https://github.com/alexzhangs/shadowsocks-manager/actions/workflows/ci-pypi.yml)\n[](https://pypi.org/project/shadowsocks-manager/)\n[](https://codecov.io/gh/alexzhangs/shadowsocks-manager)\n\n[](https://github.com/alexzhangs/shadowsocks-manager/actions/workflows/ci-docker.yml)\n[](https://hub.docker.com/r/alexzhangs/shadowsocks-manager)\n\n# shadowsocks-manager\n\nA web-based Shadowsocks management tool.\n\nFeatures:\n\n* Central user management\n* Heartbeat on Shadowsocks ports(users)\n* Shadowsocks multi-user API\n* Shadowsocks node cluster\n* Statistic for network traffic usage\n* Scheduled jobs\n* name.com API\n* Auto-creating DNS records\n* Production deployment ready\n* How's the Shadowsocks supported:\n * libev edition:\n * Full functional.\n * No builtin service manager, you need to install it and start the service by yourself.\n * python edition:\n * Lacks the collection of traffic statistics.\n * Lacks the ability to test user port creation status.\n * ~~Pre-installed, and have a builtin service manager.~~\n * No builtin service manager, you need to install it and start the service by yourself.\n\nCode in Python, base on Django, Django REST framework, Celery, and SQLite.\n\nThe development status can be found at: [project home](https://github.com/alexzhangs/shadowsocks-manager/projects/1).\n\nShadowsocks Node List:\n\n\nAdd Shadowsocks Node:\n\n\n\n## 1. Requirements\n\n* Python 2.7, Python 3.x\n* Django 1.11.x, Django 3.x\n* Docker\n* [Shadowsocks-libev 3.2.0 for Linux (multi-user API is required)](https://github.com/shadowsocks/shadowsocks-libev)\n\n\n## 2. Install\n\nThis project is a part of an entire VPN solution, which includes the Shadowsocks server and Shadowsocks manager. The Shadowsocks server serves the traffic, the Shadowsocks manager serves the users and the traffic statistics. The solution is designed to be deployed in the AWS cloud. If you are looking for such a solution, you can refer to the repo [aws-cfn-vpn](https://github.com/alexzhangs/aws-cfn-vpn). With `aws-cfn-vpn`, you can deploy the entire solution with a few commands.\n\n### 2.1. Dependencies\n\nAssume you have installed the [Docker](https://www.docker.com/) on your host.\n\n### 2.2. Manual installation\n\n```sh\n# create a docker network\ndocker network create ssm-network\n\n# run memcached, used by django cache\ndocker run -d --network ssm-network --name ssm-memcached memcached\n\n# run rabbitmq, used by celery\ndocker run -d --network ssm-network --name ssm-rabbitmq rabbitmq\n\n# create a directory to store the data, it will be mounted to the shadowsocks-manager container\nmkdir -p ~/ssm-volume\n\n# run the shadowsocks-manager\ndocker run -d -p 80:80 -v ~/ssm-volume:/var/local/ssm \\\n --network ssm-network --name ssm alexzhangs/shadowsocks-manager \\\n -e SSM_SECRET_KEY=yourkey -e SSM_DEBUG=False \\\n -e SSM_MEMCACHED_HOST=ssm-memcached -e SSM_RABBITMQ_HOST=ssm-rabbitmq \\\n -u admin -p yourpassword -M admin@yourdomain.com\n```\n\n### 2.3. Install with script\n\n```sh\ngit clone https://github.com/alexzhangs/shadowsocks-manager\nbash shadowsocks-manager/install.sh -u admin -p yourpassword -M admin@yourdomain.com\n```\n\n### 2.4. Verify the installation\n\nIf all go smoothly, the shadowsocks-manager services should have been all started. Open the web admin console in a web browser, and log on with the admin user.\n\nUse:\n```\nhttp://<your_server_ip>/admin\nor \nhttp://localhost/admin\n```\n\nIf goes well, then congratulations! The installation has succeeded.\n\n\n## 3. Using shadowsocks-manager\n\n1. Shadowsocks server\n\n First, you need to have a Shadowsocks server with the multi-user API\nenabled.\n\n Install it with docker on the same server with shadowsocks-manager.\n\n ```sh\n # run shadowsocks-libev\n MGR_PORT=6001\n SS_PORTS=8381-8480\n ENCRYPT=aes-256-cfb\n docker run -d -p $SS_PORTS:$SS_PORTS/UDP -p $SS_PORTS:$SS_PORTS \\\n --network ssm-network --name ssm-ss-libev shadowsocks/shadowsocks-libev:edge \\\n ss-manager --manager-address 0.0.0.0:$MGR_PORT \\\n --executable /usr/local/bin/ss-server -m $ENCRYPT -s 0.0.0.0 -u\n\n # Use below command to get the private IP address of the shadowsocks-libev container for later configuration.\n docker inspect ssm-ss-libev | grep IPAddress\n ```\n\n1. Add Shadowsocks server to shadowsocks-manager\n\n Add the Shadowsocks server as a Node of shadowsocks-manager from\nweb admin console: `Home \u203a Shadowsocks \u203a Shadowsocks Nodes`.\n\n1. Create users(ports) and assign Shadowsocks Node\n\n Create users from web admin console: `Home \u203a Shadowsocks \u203a\nShadowsocks Accounts` and assign the existing nodes to them.\n\n After a few seconds, the created user ports should be available to your\nShadowsocks client.\n\n\n## 4. Sendmail (Optional)\n\n`sendmail` is used to send account notification Email, it should\nbe configured on the same server with shadowsocks-manager.\n\nAbout how to configure `sendmail` client to use AWS SES as SMTP server on AWS EC2 instance, refer to repo\n[aws-ec2-ses](https://github.com/alexzhangs/aws-ec2-ses).\n\nOn macOS, refer to repo\n[macos-aws-ses](https://github.com/alexzhangs/macos-aws-ses).\n\nNOTE: This dependency needs the manual setup anyway, it is not handled by any installation script.\n\n\n## 5. Differences from the alternation: [shadowsocks/shadowsocks-manager](https://github.com/shadowsocks/shadowsocks-manager)\n\n**This repo Do's:**\n\n* Serve as a nonprofit business model.\n* Have central user management for multi nodes.\n* Collect traffic statistic that can be viewed by account, node, and period.\n* Show the existence and accessibility of ports in the admin.\n* Handle the DNS records if using Name.com as nameserver.\n\n**This repo Don'ts:**\n\n* Handle self-serviced user registration.\n* Handle bill or payment.\n* Need to run an additional agent on each Shadowsocks server.\n\n\n## 6. Some differences between the Shadowsocks Python edition (2.8.2) and libev edition\n\nVersion status for the Shadowsocks Python edition:\n* pypi: [2.8.2](https://pypi.org/project/shadowsocks/)\n* github: [3.0.0](https://github.com/shadowsocks/shadowsocks/tree/master)\n\nAlthough the Shadowsocks Python edition\nsupports the multi-user API, but it doesn't fit this project, here's why:\n\n* The python edition code and doc seem to be out of maintenance due to some reason. If you really need this you probably need to fork it and make your own.\n* They are having different service process names and CLI interfaces which introduces the complexity of installation.\n* The Python edition lacks the `list` commands. A pull request was opened years ago but never merged.\n* The Python edition's `stat` command has a very different way to use, I didn't figure the usage syntax out by looking into the code.\n* The Python edition's `ping` command returns a simple string `pong` rather than a list of ports.\n* The Python edition's `ping` command has to be sent as the syntax: `ping:{}` in order to work if tested with `nc`. It caused by the tailing newline: `ping\\n`.\n\nSo either you get some change on your own or stick with the libev edition.\n\n\n## 7. Known Issues\n\n1. DNS records matching for Node may not be accurate on macOS.\n For unknown reason sometimes DNS query returns only one IP address\nwhile multiple IP addresses were configured for the domain.\n\n1. The Shadowsocks Python edition's ssserver won't start on macOS.\n The error message is like:\n ```\n $ ssserver -k passw0rd\n WARNING: /Users/***/.pyenv/versions/3.12.0/envs/ssm-3.12/bin/python3.12 is loading libcrypto in an unsafe way\n Abort trap: 6\n ```\n\n Solution:\n Link the homebrew openssl library to the system library.\n ```sh\n sudo ln -s /opt/homebrew/opt/openssl/lib/libcrypto.dylib /usr/local/lib/\n sudo ln -s /opt/homebrew/opt/openssl/lib/libssl.dylib /usr/local/lib/\n ```\n\n1. Install the project by source with pip under Python 2.7 get error:\n ```\n python --version\n Python 2.7.18\n\n pip install .\n ```\n\n Error message:\n ```\n ...\n Collecting pyyaml\n Downloading PyYAML-5.4.1.tar.gz (175 kB)\n |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 175 kB 392 kB/s \n Installing build dependencies ... done\n Getting requirements to build wheel ... error\n ERROR: Command errored out with exit status 1:\n ...\n raise AttributeError, attr\n AttributeError: cython_sources\n ...\n ```\n\n Solution:\n ```sh\n pip install setuptools wheel\n pip install --no-build-isolation .\n ```\n\n\n## 8. Development\n\nThe development of this project requires Python 3.x.\n\nHowever, the installation of the project is compatible with both Python 2.7 and 3.x.\nTo keep the compatibility is difficult, but it's kept due to the historical reason.\nThe following files are kept only for installing the source distribution of the PyPI package under Python 2.7:\n\n* setup.py\n* setup.cfg\n\n### 8.1. Development Environment Setup\n\n1. Install the dependencies\n\n ```sh\n # run memcached, used by django cache\n docker run -d -p 11211:11211 --name ssm-dev-memcached memcached\n\n # run rabbitmq, used by celery\n docker run -d -p 5672:5672 --name ssm-dev-rabbitmq rabbitmq\n\n # run shadowsocks-libev, simulate localhost node\n MGR_PORT=6001 SS_PORTS=8381-8479 ENCRYPT=aes-256-cfb\n docker run -d -p 127.0.0.1:$MGR_PORT:$MGR_PORT/UDP \\\n -p 127.0.0.1:$SS_PORTS:$SS_PORTS/UDP -p 127.0.0.1:$SS_PORTS:$SS_PORTS \\\n --name ssm-dev-ss-libev-localhost shadowsocks/shadowsocks-libev:edge \\\n ss-manager --manager-address 0.0.0.0:$MGR_PORT \\\n --executable /usr/local/bin/ss-server -m $ENCRYPT -s 0.0.0.0 -u\n\n # get the private IP address of the host, double check the result, it might not be correct\n PRIVATE_IP=$(ipconfig getifaddr en0 2>/dev/null || hostname -i | awk '{print $1}' 2>/dev/null)\n echo \"PRIVATE_IP=$PRIVATE_IP\"\n\n # run shadowsocks-libev, simulate private IP node\n MGR_PORT=6002 SS_PORTS=8381-8479 ENCRYPT=aes-256-cfb\n docker run -d -p $PRIVATE_IP:$MGR_PORT:$MGR_PORT/UDP \\\n -p $PRIVATE_IP:$SS_PORTS:$SS_PORTS/UDP -p $PRIVATE_IP:$SS_PORTS:$SS_PORTS \\\n --name ssm-dev-ss-libev-private shadowsocks/shadowsocks-libev:edge \\\n ss-manager --manager-address 0.0.0.0:$MGR_PORT \\\n --executable /usr/local/bin/ss-server -m $ENCRYPT -s 0.0.0.0 -u\n \n # run shadowsocks-libev, simulate public IP node\n MGR_PORT=6003 SS_PORTS=8480 ENCRYPT=aes-256-cfb\n docker run -d -p $PRIVATE_IP:$MGR_PORT:$MGR_PORT/UDP \\\n -p $PRIVATE_IP:$SS_PORTS:$SS_PORTS/UDP -p $PRIVATE_IP:$SS_PORTS:$SS_PORTS \\\n --name ssm-dev-ss-libev-public shadowsocks/shadowsocks-libev:edge \\\n ss-manager --manager-address 0.0.0.0:$MGR_PORT \\\n --executable /usr/local/bin/ss-server -m $ENCRYPT -s 0.0.0.0 -u\n ```\n\n1. Link the project code in your workspace to the Python environment\n\n ```sh\n cd shadowsocks-manager\n pip install -e .\n ```\n\n1. Set the SSM_DATA_HOME environment variable (optional, default is Django root directory)\n\n ```sh\n export SSM_DATA_HOME=~/.ssm-dev-data\n ```\n\n1. Configure the shadowsocks-manager\n\n ```sh\n ssm-setup -c -m -l -u admin -p yourpassword\n ```\n\n1. Run the development server\n\n Make sure the memcached and rabbitmq are running.\n\n ```sh\n ssm-dev-start\n ```\n\n1. Stop the development server\n\n ```sh\n ssm-dev-stop\n ```\n\n1. Test the Django code\n\n Make sure the memcached and rabbitmq are running, and also the 3 shadowsocks-libev node are running.\n\n ```sh\n ssm-test -t\n\n # or use the django test command directly for more options\n ssm-manage test --no-input -v 2\n ```\n\n1. Test the Django code with coverage\n\n ```sh\n pip install coverage\n ssm-test -c\n ```\n\n1. Upload the coverage report to codecov\n\n Make sure the `CODECOV_TOKEN` is exported in the environment before uploading.\n\n ```sh\n pip install codecov-cli\n ssm-test -u\n ```\n\n1. Test the Github workflows locally\n\n ```sh\n brew install act\n act -j test\n ```\n\n1. Build the PyPI package\n\n ```sh\n pip install build\n\n # build source and binary distribution, equivalent to `python setup.py sdist bdist_wheel`\n # universal wheel is enabled in the pyproject.toml to make the wheel compatible with both Python 2 and 3\n python -m build\n ```\n\n1. Upload the PyPI package\n\n Set the ~/.pypirc file with the API token from the TestPyPI and PyPI before uploading.\n\n ```sh\n pip install twine\n\n # upload the package to TestPyPI\n python -m twine upload --repository testpypi dist/*\n\n # upload the package to PyPI\n python -m twine upload dist/*\n ```\n\n1. Test the PyPI package\n\n ```sh\n # install the package from TestPyPI\n # --no-deps is used to skip installing dependencies for the TestPyPI environment\n pip install -i https://test.pypi.org/simple/ --no-deps shadowsocks-manager\n\n # install the package from PyPI\n # --no-binary is used to force building the package from the source\n # --use-pep517 is used together to make sure the PEP 517 is tested\n pip install --no-binary shadowsocks-manager --use-pep517 shadowsocks-manager\n ```\n\n1. Build the docker image\n\n ```sh\n docker build -t alexzhangs/shadowsocks-manager .\n ```\n\n### 8.2. CI/CD\n\nGithub Actions is currently used for the CI/CD.\nTravis CI is removed due to the limitation of the free plan.\n\nThe CI/CD workflows are defined in the `.github/workflows` directory.\n\n* ci-unittest.yml: Run the unit tests.\n* ci-testpypi.yml: Build and upload the package to TestPyPI.\n* ci-pypi.yml: Build and upload the package to PyPI. It can be triggered by the tag: `ci-pypi` or `ci-pypi-(major|minor|patch|suffx)`.\n* ci-docker.yml: Build and push the docker image to Docker Hub. It can be triggered by the Github release.\n\n\n## 9. Troubleshooting\n\n1. Check the logs\n\n ```\n # supervisor\n cat /var/log/supervisor/supervisord.log\n\n # uWSGI\n cat /var/log/ssm-uwsgi.log\n\n # Celery\n cat /var/log/ssm-cerlery*\n ```\n\n1. Check the services\n\n ```\n # nginx\n service nginx {status|start|stop|reload}\n\n # supervisor\n service supervisord {status|start|stop|restart}\n supervisorctl reload\n supervisorctl start all\n\n # uWSGI\n supervisorctl start ssm-uwsgi\n\n # Celery\n supervisorctl start ssm-celery-worker\n supervisorctl start ssm-celery-beat\n\n # Docker\n docker ps\n ```\n\n1. Check the listening ports and processes (Linux)\n\n ```\n # TCP\n netstat -tanp\n\n # UDP\n netstat -uanp\n ```\n\n1. Check the listening ports (MacOS)\n\n ```\n # TCP\n netstat -anp tcp\n\n # UDP\n netstat -anp udp\n\n # find the process by port\n lsof -i :80 -P\n ```\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2021 Alex Zhang Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "A shadowsocks manager for multi-user and traffic statistics",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/alexzhangs/shadowsocks-manager",
"homepage": "https://www.0xbeta.com/shadowsocks-manager/",
"issues": "https://github.com/alexzhangs/shadowsocks-manager/issues",
"repository": "https://github.com/alexzhangs/shadowsocks-manager"
},
"split_keywords": [
"shadowsocks",
" manager",
" django",
" web",
" statistics",
" cluster",
" celery",
" uwsgi",
" pypi",
" docker",
" github-actions"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dd8c10cc49f53b7a891c014d6f013368d567d7813c3f2ec8b194605113e4653b",
"md5": "b7377e6fe3e3954c3e380ea419326c5f",
"sha256": "f78a831747a9cf817efe782abfcf63dc23781a472a5b007f4b2838d2f9330c86"
},
"downloads": -1,
"filename": "shadowsocks_manager-0.1.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "b7377e6fe3e3954c3e380ea419326c5f",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=2.7",
"size": 76188,
"upload_time": "2024-05-06T05:00:28",
"upload_time_iso_8601": "2024-05-06T05:00:28.075647Z",
"url": "https://files.pythonhosted.org/packages/dd/8c/10cc49f53b7a891c014d6f013368d567d7813c3f2ec8b194605113e4653b/shadowsocks_manager-0.1.5-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0017ec0c7462815620186a6d3103f14b75cc2a46222c7be8db994200113ad7f6",
"md5": "b262eab48c30a2ea48c11f05d46fd54d",
"sha256": "2e41ce4ed502cf5d296cf46038f9e425fb7b6b0b391113c2c87c1888b09a3988"
},
"downloads": -1,
"filename": "shadowsocks_manager-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "b262eab48c30a2ea48c11f05d46fd54d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7",
"size": 57129,
"upload_time": "2024-05-06T05:00:30",
"upload_time_iso_8601": "2024-05-06T05:00:30.098291Z",
"url": "https://files.pythonhosted.org/packages/00/17/ec0c7462815620186a6d3103f14b75cc2a46222c7be8db994200113ad7f6/shadowsocks_manager-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-06 05:00:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexzhangs",
"github_project": "shadowsocks-manager",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "shadowsocks-manager"
}
