Shadowsocks Hub (v0.3.0)
It is a web app for managing shadowsocks users, servers, nodes (a.k.a. exit points), products, accounts, and traffic. It is best suitable for companies, organizations, and groups of friends to manage their internal shadowsocks infrastructures.
Installation (Docker)
-
Install Docker.
-
Install Docker Compose.
-
Download Shadowsocks Hub:
cd ~ git clone https://github.com/shadowsocks/shadowsocks-hub.git
-
Create an environment file
.env
:cd ~/shadowsocks-hub touch .env
-
Add the following configuration to
.env
:CODE_SECRET=changeThisSecret MYSQL_PASSWORD=changeThisPassword
Change the value of
CODE_SECRET
with a long and random string.
Change the value ofMYSQL_PASSWORD
with another long and random string. -
Create a directory for digital certificate:
cd ~/shadowsocks-hub mkdir ssl
-
Set up digital certificate
Shadowsocks Hub uses https for all web traffic. It requires you to set up a digital certificate. You may obtain your digital certificate and key pair from any Certificate Authority (e.g. Let's Encrypt). Then rename the certificate file to
server.cert
and the key file toserver.key
. Finally, copy bothserver.cert
andserver.key
to~/shadowsocks-hub/ssl
directory. -
Create and start Docker container:
cd ~/shadowsocks-hub docker-compose up -d
The first time will take a while (a few seconds ~ few minutes), in order to download docker images from Docker Hub and run them. So be patient. ;-)
-
Shadowsocks Hub uses shadowsocks-restful-api to manage shadowsocks node. Install it on every server acting as a shadowsocks node.
Non-Docker Installation (deprecated)
This installation method has been deprecated and will be removed in the future. Please use the above mentioned docker installation method.
-
Install Nodejs 8 or above.
-
Install MySQL.
-
Download and install Shadowsocks Hub:
cd ~ git clone https://github.com/shadowsocks/shadowsocks-hub.git cd ~/shadowsocks-hub npm i sudo npm i -g knex sudo npm i -g pm2
-
Create a MySQL database
sshub
:CREATE DATABASE sshub;
-
Edit PM2 config file
~/shadowsocks-hub/ecosystem.config.js
, change the following configurations to your local settings :JWT_SECRET: '2wk0M@ow094B^&9k3==~o2soejd$sEEo@2(', DATABASE_HOST: 'localhost', DATABASE_PORT: '3306', DATABASE_USER: 'root', DATABASE_PASSWORD: 'd4f889df22769f54', Change the value of `JWT_SECRET` with a long and random string. Change the values about the MySQL database connection to your local configurations.
-
Initialize database:
cd ~/shadowsocks-hub knex migrate:latest --env production
-
Set up digital certificate
Shadowsocks Hub uses https for all web traffic. It requires you to set up a digital certificate. You may obtain your digital certificate and key pair from any Certificate Authority (e.g. Let's Encrypt). Then rename the certificate file as
server.cert
and the key file asserver.key
. Finally, copy bothserver.cert
andserver.key
to~/shadowsocks-hub
. -
Give non-root user permission to use port 80, 443
Shadowsocks Hub requires listenning to port 80 and 443. The following commands allow a non-root user to use both ports. This is the best practice from security point of view.
sudo apt-get install libcap2-bin sudo setcap cap_net_bind_service=+ep /usr/bin/node
-
Shadowsocks Hub uses shadowsocks-restful-api to manage shadowsocks node. Install it on every server acting as a shadowsocks node.
Update from non-Docker installation to Docker installation
-
Make above mentioned docker version installation.
-
Backup existing database:
cd ~/shadowsocks-hub mysqldump -u root -p sshub > backup.sql
-
Restore the backup to docker MySQL container:
cd ~/shadowsocks-hub docker-compose up -d cat backup.sql | docker exec -i shadowsocks-hub_db_1 mysql -u root --password=MYSQL_PASSWORD sshub
Note replace
MYSQL_PASSWORD
with your configration in.env
file.
Run
-
Run Shadowsocks Hub:
cd ~/shadowsocks-hub docker-compose up -d
-
Visiting Shadowsocks Hub:
Visiting your Shadowsocks Hub website using your server domain name in a web browser.
-
Change admin credential
For the sake of security, you should immeidately change the default admin user username and password upon installation. This can be done by
login
as the admin user and thenupdate
the username and password. The default username and password for the admin user are[email protected]
andpleaseChangePassword
, respectively. -
Run shadowsocks-restful-api on every server acting as a shadowsocks node.
Stop
cd ~/shadowsocks-hub
docker-compose stop
Restart
cd ~/shadowsocks-hub
docker-compose restart
Usage
Admin
Once logged in as the admin, the menu looks like:
The admin may choose to navigate to:
-
Managing servers. A
server
is a machine acting as a shadowsocks exit point. Aserver
may have more than onenode
. Admin has to provide its IP address or domain name when adding aserver
. Admin may add, edit, and delete aserver
. Note that aserver
cannot be deleted if anode
has been created using thisserver
. Admin has to delete all itsnodes
before successfully deleting theserver
.The admin may also check and navigate to any
nodes
,accounts
, orusers
using aserver
, and check totaltraffic
that aserver
has served. -
Managing nodes. A
node
is a virtual shadowsocks exit point. The difference betweenserver
andnode
is that aserver
is an indpendent machine where anode
is a logical machine whose functionality relies onserver
. There can be multiplenodes
residing on a singleserver
. From users' perspective,nodes
using the sameserver
are different shadowsocks exit points. Before adding anode
, the underlyingserver
has to be added into the system first. When adding a newnode
, the admin has to select a server, give it a descriptive name, and provide its managing port, and managing password. Admin may also edit and delete anode
. Note that anode
cannot be deleted if anaccount
has been created using thisnode
. Admin has to delete all itsaccounts
before successfully deleting thenode
.The admin may also check and navigate to the
server
that anode
belongs to, anyaccounts
orusers
using anode
, and check totaltraffic
that anode
has serverd. -
Managing products. A
product
is a shadowsocks service subscription. When adding a newproduct
, the admin has to give it a descriptive name, select a period of subscription, and provide traffic allowance for the period. The admin may also edit and delete aproduct
. Note that aproduct
cannot be deleted if arequest
has been created on thisproduct
(regardless of whether therequest
is aproved or not).The admin may also check and navigate to any
accounts
,users
, orrequests
relating to aproduct
. -
Managing users. A
user
is a person using the shadowsocks service provided. The system is not open for registration, due to its nature of internal use. A newuser
has to be added by the admin into the system. When adding a newuser
, the admin has to provide an email and initial password. The admin may also edit and delete auser
. Note that auser
cannot be deleted if arequest
has been created for this thisuser
(regardless of whether therequest
is aproved or not).The admin may also check and navigate to any
accounts
,requests
,products
,nodes
, orservers
relating to auser
. -
Managing requests. A
request
is made by the admin for auser
on aproduct
, or is made by auser
on aproduct
. Before making arequest
, its underlyinguser
andproduct
have been added into the system. It requests for a shadowsocks service. The admin may choose to approve arequest
. Upon approval, the system will create oneaccount
on everynode
that the system has. Theseaccounts
will allow theuser
to use the specified shadowsocks service. Theaccount
information will be shown when theuser
login the system.The admin may also check and navigate to any
accounts
,product
, oruser
, and check totaltraffic
relating to arequest
. -
Managing accounts. An
account
is a shadowsocks account containing all information needed for itsuser
to use the shadowsocks service. The admin may manually add a newaccount
by selecting auser
and arequest
. Before adding anaccount
, its underlyinguser
andrequest
have to be added into the system first. The admin may also delete anaccount
. Note that anaccount
cannot be deleted iftraffic
information of theaccount
has been created by the system.The admin may also check and navigate to the
server
,node
,product
,user
,request
, and check totaltraffic
relating to anaccount
. In addition, the admin may choose to show a QR code encoding the account information.
Users
Once logged in as a user, the menu looks like:
A user may choose to navigate to:
-
Showing their accounts. A
user
check the latesttraffic
of any of their ownaccounts
. They may also get the QR code displayed for any of theiraccounts
. -
Showing all products. A
user
may choose the make arequest
on aproduct
. Once arequest
is created, it has to be approved by the admin beforeaccounts
created by the system. -
Showing their requests. A
user
may check and navigate to anyaccounts
, and check thetraffic
relating to arequest
.
Rate limit
You may enforce a rate limit by setting the maximum number of requests allowed within 15-minute window from the same ip address. Requests exceeding the limit will be refused with HTTP status code 429 Too Many Requests
. This setting can be done by add the following config to the .env
file.
RATE_LIMIT = 50
Change the number to your choice.
Bug report, feature request, and feedback
Bug report, feature request, and feedback is welcome. Bugs have a high priority to get addressed. Feature requests and improvement feedback will be considered depending on their popularity and importance.