Release of V3.1.0

Firewall and API updates

README.md

@@ -1,25 +1,34 @@
 About shadowsocks-python manyuser
 =================================
-This is a multi-user version of shadowsocks-python. Requires a mysql database.
+This is a multi-user version of shadowsocks-python. Requires a mysql database or a panel support SS MU API.
 
-Install
--------
-1. install MySQL 5.x.x
+Install instruction for database user
+-------------------------------------
+1. install MySQL Server 5.x.x
 2. install cymysql library by `pip install cymysql`
 3. create a database named `shadowsocks`
 4. import `shadowsocks.sql` into `shadowsocks`
 5. copy `config_example.py` to `config.py` and edit it following the notes inside (but DO NOT delete the example file)
 6. TestRun `cd shadowsocks && python servers.py` (not server.py)
 
+Install instruction for MU API user
+-----------------------------------
+1. install a panel which supports MU API (the known one is [SS-Panel V3](https://github.com/orvice/ss-panel))
+2. copy `config_example.py` to `config.py` and edit it following the notes inside (but DO NOT delete the example file)
+3. TestRun `cd shadowsocks && python servers.py` (not server.py)
+
+
 if no exception the server will startup. By default logging is enabled.
 You should be able to see this kind of thing in `shadowsocks.log`(default log file name)
 ```
-May 25 23:03:16 INFO Multi-User Shadowsocks Server Starting...
-May 25 23:03:17 INFO Current Server Version: 2.8.3-83-gf8dd2f8
-
-May 25 23:03:18 INFO db skipped port 443
-May 25 23:03:19 INFO db downloaded
-May 25 23:03:19 INFO Server Added:   P[XXXX], M[aes-256-cfb], E[[email protected]]
+Jun 24 01:06:08 INFO -----------------------------------------
+Jun 24 01:06:08 INFO Multi-User Shadowsocks Server Starting...
+Jun 24 01:06:08 INFO Current Server Version: 3.1.0-1-gc2ac618
+
+Jun 24 01:10:11 INFO api downloaded
+Jun 24 01:10:13 INFO api skipped port 443
+Jun 24 01:10:13 INFO Server Added:   P[XXXXX], M[rc4-md5], E[[email protected]]
+Jun 24 01:10:13 INFO Server Added:   P[XXXXX], M[rc4-md5], E[[email protected]]
 ```
 
 Explanation of the log output
@@ -58,7 +67,7 @@ Database user table column
 
 Compatibility with other frontend UIs
 -------------------------------------
-It is compatible with [ss-panel](https://github.com/orvice/ss-panel).
+It is fully compatible (SS MU API) with [ss-panel V3](https://github.com/orvice/ss-panel).
 
 Open source license
 -------------------

shadowsocks/config_example.py

@@ -1,40 +1,58 @@
-# !!! Please rename this file as config.py BEFORE editing it !!!
+# !!! Please rename config_example.py as config.py BEFORE editing it !!!
 
 import logging
-# !!! Do NOT touch this line !!!
-CONFIG_VERSION = '20160618-1'
+# !!! Only edit this line when you update your configuration file !!!
+# After you update, the value of CONFIG_VERSION in config.py and
+# config_example.py should be the same in order to start the server
+CONFIG_VERSION = '20160623-2'
+
+
+# Manyuser Interface Settings
+# ---------------------------
+# If API is enabled, database will be no longer used
+# The known app that supports API is SS-Panel V3
+# Be careful and check whether your app supports this API BEFORE you enable this feature
+API_ENABLED = False
 
 # Database Config
 MYSQL_HOST = 'mengsky.net'
 MYSQL_PORT = 3306
 MYSQL_USER = 'root'
 MYSQL_PASS = 'root'
 MYSQL_DB = 'shadowsocks'
+# USUALLY this variable do not need to be changed
 MYSQL_USER_TABLE = 'user'
+# This is also the timeout of connecting to the API
 MYSQL_TIMEOUT = 30
 
-# It is not necessary to change the password if you only listen on 127.0.0.1
-MANAGE_PASS = 'passwd'
-# if you want manage in other server you should set this value to global ip
-MANAGE_BIND_IP = '127.0.0.1'
-# make sure this port is idle
-MANAGE_PORT = 23333
-
-# SS Panel API Setting
-# Version of Panel: V2 or V3. V2 not support API thus no need to change
-# anything in the following settings
-PANEL_VERSION = 'V2'
+# Shadowsocks MultiUser API Settings
 API_URL = 'http://domain/mu'
-# API Key of SS-Panel V3 (you can find this in the .env file)
+# API Key (you can find this in the .env file if you are using SS-Panel V3)
 API_PASS = 'mupass'
 NODE_ID = '1'
+
+# Time interval between 2 pulls from the database
 CHECKTIME = 15
+# Time interval between 2 pushes from the database
 SYNCTIME = 600
-
-# Choose True if you want to use custom method
+# Choose True if you want to use custom method and False if you don't
 CUSTOM_METHOD = True
 
-# BIND IP
+
+# Manager Settings
+# ----------------
+# USUALLY you can just keep this section unchanged
+# It is not necessary to change the password if you only listen on 127.0.0.1
+MANAGE_PASS = 'passwd'
+# if you want manage in other server you should set this value to global ip
+MANAGE_BIND_IP = '127.0.0.1'
+# make sure this port is idle
+MANAGE_PORT = 65000
+
+
+# Network Settings
+# ----------------
+# Address binding settings
 # if you want to bind ipv4 and ipv6 please use '::'
 # if you want to bind only all of ipv4 please use '0.0.0.0'
 # if you want to bind a specific IP you may use something like '4.4.4.4'
@@ -45,23 +63,35 @@
 # OTA will still be enabled for the client if it sends an AUTH Address type(0x10)
 SS_OTA = False
 # Skip listening these ports
-SS_SKIP_PORTS = ['80']
-# Ban these outbound ports
-# Members should be INTEGERS
-SS_BAN_PORTS = [22, 23, 25]
-
+SS_SKIP_PORTS = [80]
+# TCP Fastopen (Some OS may not support this, Eg.: Windows)
+SS_FASTOPEN = False
 # Shadowsocks Time Out
 # It should > 180s as some protocol has keep-alive packet of 3 min, Eg.: bt
 SS_TIMEOUT = 185
-# Shadowsocks TCP Fastopen (Some OS may not support this, Eg.: Windows)
-SS_FASTOPEN = False
-# Shadowsocks verbose
-SS_VERBOSE = False
+
+
+# Firewall Settings
+# -----------------
+# These settings are to prevent user from abusing your service
+SS_FIREWALL_ENABLED = True
+# Mode = whitelist or blacklist
+SS_FIREWALL_MODE = 'blacklist'
+# Member ports should be INTEGERS
+# Only Ban these target ports (for blacklist mode)
+SS_BAN_PORTS = [22, 23, 25]
+# Only Allow these target ports (for whitelist mode)
+SS_ALLOW_PORTS = [53, 80, 443, 8080, 8081]
+# Trusted users (all target ports will be not be blocked for these users)
+SS_FIREWALL_TRUSTED = [443]
 # Banned Target IP List
 SS_FORBIDDEN_IP = []
 
-# LOG CONFIG
+
+# Logging and Debugging Settings
+# --------------------------
 LOG_ENABLE = True
+SS_VERBOSE = False
 # Available Log Level: logging.NOTSET|DEBUG|INFO|WARNING|ERROR|CRITICAL
 LOG_LEVEL = logging.INFO
 LOG_FILE = 'shadowsocks.log'