alexzhangs/shadowsocks-manager

Python:2.7	Python:3.6	Python:3.7	Python:3.8	Python:3.9

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 version:
    • Full functional.
    • No builtin service manager, you need to install it and start the service by yourself.
  • python version:
    • Lacks the collection of traffic statistics.
    • Lacks the ability to test user port creation status.
    • Pre-installed, and have a builtin service manager.

Code in Python, base on Django, Django REST framework, Celery, and SQLite.

The development status can be found at: project home.

Node List:

Node's Shadowsocks Manager:

1. Requirements

• Python 2.7, Python 3.x
• Django 1.11.x, Django 3.x
• macOS Big Sur (only the core python code tested, the installation scripts work on Linux only)
• AWS Amazon Linux AMI
• AWS Amazon Linux 2 AMI
• Shadowsocks-libev 3.2.0 for Linux (multi-user API is required)

2. Install

NOTE: It's better to install the project within a virtualenv.

Open a terminal on the server in which the shadowsocks-manager is going to run.

1. Get the code:

   git clone https://github.com/alexzhangs/shadowsocks-manager

2. Install

   The installation scripts can WORK ONLY ON LINUX and be tested only with Amazon Linux AMI and Amazon Linux 2 AMI.

   Run below commands under root.

   bash shadowsocks-manager/one-click-deploy.sh

   If you want to customize the shadowsocks-manager installation, see: bash shadowsocks-manager/one-click-deploy.sh -h:

   Description:
     Deploy shadowsocks-manager with one single command.
     Run this script under root on Linux.
   
   Usage:
     one-click-deploy.sh [-n DOMAIN] [-u USERNAME] [-p PASSWORD] [-e EMAIL] [-t TIMEZONE] [-o PORT_BEGIN] [-O PORT_END] [-h]
   
   Options:
     [-n DOMAIN]
   
     Domain name resolved to the shadowsocks-manager web application.
   
     [-u USERNAME]
   
     Username for shadowsocks-manager administrator, default is 'admin'.
   
     [-p PASSWORD]
   
     Password for shadowsocks-manager administrator, default is 'passw0rd'.
   
     [-e EMAIL]
   
     Email for the shadowsocks-manager administrator.
     Also, be used as the sender of the account notification Email.
   
     [-t TIMEZONE]
   
     Set Django's timezone, default is 'UTC'.
     Statistic period also senses this setting. Note that AWS billing is based on UTC.
   
     [-r PORT_BEGIN]
   
     Port range allowed for all Shadowsocks nodes.
   
     [-R PORT_END]
   
     Port range allowed for all Shadowsocks nodes.
   
     [-h]
   
     This help.
   

3. 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
   

   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.

   About how to install and configure Shadowsocks server in AWS, refer to the repo aws-ec2-shadowsocks-libev

   After the server is installed and started, there should be a running process named ss-manager. Write down the IP address and the port that the ss-manager is listening on, and also the public IP address of the server, the encryption method that Shadowsocks is using, they are going to be used in the next step.

2. Add Shadowsocks server to shadowsocks-manager

   Add the Shadowsocks server as a Node of shadowsocks-manager from web admin console: Home › Shadowsocks › Shadowsocks Nodes.

3. 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. The builtin local service manager for Shadowsocks python version

   There's a builtin local service manager available for the Shadowsocks python version.

   The python version is pre-installed with shadowsocks-manager. With the service manager, you can start&stop the local service daemon on-the-fly. Check it out from the web admin console Home › Shadowsocks › Shadowsocks Nodes, under the SHADOWSOCKS MANAGERS tab.

   However the traffice statistics and user port creation status features are not available for the python version.

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.

On macOS, refer to repo macos-aws-ses.

NOTE: This dependency needs the manual setup anyway, it is not handled by any installation script.

5. Can the installation be easier?

Yes, if you are deploying the services in the AWS.

aws-cfn-vpn is a set of AWS CloudFormation templates which let you deploy VPN services, including Shadowsocks (support cluster) and XL2TPD, with a single click. Also, this repo, shadowsocks-manager and all its dependencies are handled by aws-cfn-vpn.

6. Differences from the alternation: 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.

7. Some differences between the Shadowsocks Python version and libev version

Although the Shadowsocks Python version supports the multi-user API, but it doesn't fit this project, here's why:

• The python version 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 version lacks the list commands. A pull request was opened years ago but never merged.
• The Python version'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 version's ping command returns a simple string pong rather than a list of ports.
• The Python version'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 version.

8. 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.

9. Troubleshooting

1. Check the logs

   # supervisor
   cat /tmp/supervisord.log
   
   # uWSGI
   cat /var/log/ssm-uwsgi.log
   
   # Celery
   cat /var/log/ssm-cerlery*
   

2. 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
   

3. Check the listening ports (Linux)

   # TCP
   netstat -tan
   
   # UDP
   netstat -uan
   

shadowsocks-manager's Issues

can't install

[root@do-1v-2g-2t-sfo2-01 shadowsocks-manager]# pip install -r requirements.txt
DEPRECATION: Python 2.7 will reach the end of its life on January 1st, 2020. Please upgrade your Python as Python 2.7 won't be maintained after that date. A future version of pip will drop support for Python 2.7. More details about Python 2 support in pip, can be found at https://pip.pypa.io/en/latest/development/release-process/#python-2-support
Collecting backports.weakref (from -r requirements.txt (line 1))
  Using cached https://files.pythonhosted.org/packages/88/ec/f598b633c3d5ffe267aaada57d961c94fdfa183c5c3ebda2b6d151943db6/backports.weakref-1.0.post1-py2.py3-none-any.whl
Collecting celery==4.3.0 (from -r requirements.txt (line 2))
  Using cached https://files.pythonhosted.org/packages/5c/a1/a3dd9d8bfa09156ec2cba37f90accf35c0f4ecc3980d96cb4fb99e56504b/celery-4.3.0-py2.py3-none-any.whl
Collecting Django==1.11.20 (from -r requirements.txt (line 3))
  Using cached https://files.pythonhosted.org/packages/8e/1f/20bbc601c442d02cc8d9b25a399a18ef573077e3350acdf5da3743ff7da1/Django-1.11.20-py2.py3-none-any.whl
Collecting django-cache-lock==0.2.1 (from -r requirements.txt (line 4))
  Using cached https://files.pythonhosted.org/packages/b7/e4/baa986fb268430d313d4f780c906ebfe2a6eaac30236955edb993833445d/django_cache_lock-0.2.1-py2.py3-none-any.whl
Collecting django-celery-beat==1.5.0 (from -r requirements.txt (line 5))
  Using cached https://files.pythonhosted.org/packages/88/13/2dbab42ea826efab897d8638304d499078e0093e73c9b5fa19259e48ea94/django_celery_beat-1.5.0-py2.py3-none-any.whl
Collecting django-celery-results==1.1.1 (from -r requirements.txt (line 6))
  Using cached https://files.pythonhosted.org/packages/1d/3f/a82aa9fb1f2e35a72a710134a7bf9d9b1dc45dea9f6c2c16d06bb6363554/django_celery_results-1.1.1-py2.py3-none-any.whl
Collecting django-enumfield==1.5 (from -r requirements.txt (line 7))
  Using cached https://files.pythonhosted.org/packages/ff/47/7d4c29c841e32e047dc22526f17259fd280ec1dbb5f609c7d29155f1ffe9/django-enumfield-1.5.tar.gz
Collecting django-import-export==1.2.0 (from -r requirements.txt (line 8))
  Using cached https://files.pythonhosted.org/packages/62/7a/ddd9aef718243504e7715bda9bb5a100cfc353be37dc819d9914a7073cba/django_import_export-1.2.0-py2.py3-none-any.whl
Collecting djangorestframework==3.9.2 (from -r requirements.txt (line 9))
  Using cached https://files.pythonhosted.org/packages/cc/6d/5f225f18d7978d8753c1861368efc62470947003c7f9f9a5cc425fc0689b/djangorestframework-3.9.2-py2.py3-none-any.whl
Collecting python-memcached==1.59 (from -r requirements.txt (line 10))
  Using cached https://files.pythonhosted.org/packages/f5/90/19d3908048f70c120ec66a39e61b92c253e834e6e895cd104ce5e46cbe53/python_memcached-1.59-py2.py3-none-any.whl
Collecting pytz==2019.1 (from -r requirements.txt (line 11))
  Using cached https://files.pythonhosted.org/packages/3d/73/fe30c2daaaa0713420d0382b16fbb761409f532c56bdcc514bf7b6262bb6/pytz-2019.1-py2.py3-none-any.whl
Collecting requests==2.22.0 (from -r requirements.txt (line 12))
  Using cached https://files.pythonhosted.org/packages/51/bd/23c926cd341ea6b7dd0b2a00aba99ae0f828be89d72b2190f27c11d4b7fb/requests-2.22.0-py2.py3-none-any.whl
Collecting vine>=1.3.0 (from celery==4.3.0->-r requirements.txt (line 2))
  Using cached https://files.pythonhosted.org/packages/7f/60/82c03047396126c8331ceb64da1dc52d4f1317209f32e8fe286d0c07365a/vine-1.3.0-py2.py3-none-any.whl
Collecting billiard<4.0,>=3.6.0 (from celery==4.3.0->-r requirements.txt (line 2))
  Using cached https://files.pythonhosted.org/packages/68/1d/2aea8fbb0b1e1260a8a2e77352de2983d36d7ac01207cf14c2b9c6cc860e/billiard-3.6.1.0.tar.gz
Collecting kombu<5.0,>=4.4.0 (from celery==4.3.0->-r requirements.txt (line 2))
  Using cached https://files.pythonhosted.org/packages/bb/22/58104fd214fb32008f2f4d64a1918c81e353f23e7beee9605674f9ecd6b2/kombu-4.6.4-py2.py3-none-any.whl
Requirement already satisfied: six>=1.0.0 in /usr/lib/python2.7/site-packages (from django-cache-lock==0.2.1->-r requirements.txt (line 4)) (1.9.0)
Collecting django-timezone-field>=2.0 (from django-celery-beat==1.5.0->-r requirements.txt (line 5))
  Using cached https://files.pythonhosted.org/packages/1a/c0/6aa03df6a901123b9eeb7fbc8ea64f9e8f9f4a1a10ab91313ac2b1d46c0e/django_timezone_field-3.0-py2.py3-none-any.whl
Collecting python-crontab>=2.3.4 (from django-celery-beat==1.5.0->-r requirements.txt (line 5))
  Using cached https://files.pythonhosted.org/packages/01/3f/e81716ba2592e7006c174251f70486b7e1d06abea80fe0c25a07d6527f5b/python-crontab-2.3.9.tar.gz
Collecting tablib (from django-import-export==1.2.0->-r requirements.txt (line 8))
  Using cached https://files.pythonhosted.org/packages/77/bf/c58a0aaf9e94c002955ae64f1bfd044dc5f34b3e9b278de152402560d060/tablib-0.13.0.tar.gz
Collecting diff-match-patch (from django-import-export==1.2.0->-r requirements.txt (line 8))
  Using cached https://files.pythonhosted.org/packages/f0/2a/5ba07def0e9107d935aba62cf632afbd0f7c723a98af47ccbcab753d2452/diff-match-patch-20181111.tar.gz
    ERROR: Command errored out with exit status 1:
     command: /usr/bin/python2 -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'/tmp/pip-install-zj0lvn/diff-match-patch/setup.py'"'"'; __file__='"'"'/tmp/pip-install-zj0lvn/diff-match-patch/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base pip-egg-info
         cwd: /tmp/pip-install-zj0lvn/diff-match-patch/
    Complete output (13 lines):
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/tmp/pip-install-zj0lvn/diff-match-patch/setup.py", line 37, in <module>
        install_requires=[],
      File "/usr/lib64/python2.7/distutils/core.py", line 112, in setup
        _setup_distribution = dist = klass(attrs)
      File "/usr/lib/python2.7/site-packages/setuptools/dist.py", line 265, in __init__
        self.fetch_build_eggs(attrs.pop('setup_requires'))
      File "/usr/lib/python2.7/site-packages/setuptools/dist.py", line 289, in fetch_build_eggs
        parse_requirements(requires), installer=self.fetch_build_egg
      File "/usr/lib/python2.7/site-packages/pkg_resources.py", line 630, in resolve
        raise VersionConflict(dist,req) # XXX put more info here
    pkg_resources.VersionConflict: (setuptools 0.9.8 (/usr/lib/python2.7/site-packages), Requirement.parse('setuptools>=38.6.0'))
    ----------------------------------------
ERROR: Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.