diff --git a/README.rst b/README.rst index 8b32c51..241e339 100644 --- a/README.rst +++ b/README.rst @@ -1,16 +1,17 @@ shadowsocks =========== -|Build Status| +Current version: 1.4.4 |Build Status| shadowsocks is a lightweight tunnel proxy which can help you get through -firewalls +firewalls. -Other ports and clients can be found -`here `__. +Both TCP CONNECT and UDP ASSOCIATE are implemented. -Usage ------ +`中文说明 `__ + +Install +------- First, make sure you have Python 2.6 or 2.7. @@ -19,40 +20,90 @@ First, make sure you have Python 2.6 or 2.7. $ python --version Python 2.6.8 -Install shadowsocks. +Install Shadowsocks. + +Debian / Ubuntu: +^^^^^^^^^^^^^^^^ + +:: + + apt-get install python-pip python-gevent python-m2crypto + pip install shadowsocks + +CentOS: +^^^^^^^ :: + yum install m2crypto python-setuptools + easy_install pip pip install shadowsocks -Create a file named ``config.json``, with the following content. +OS X: +^^^^^ + +:: + + git clone https://github.com/clowwindy/M2Crypto.git + cd M2Crypto + pip install . + pip install shadowsocks + +Windows: +^^^^^^^^ + +Choose a `GUI +client `__ + +Usage +----- + +Create a config file ``/etc/shadowsocks.json`` (or put it in other +path). Example: :: { "server":"my_server_ip", "server_port":8388, + "local_address": "127.0.0.1", "local_port":1080, - "password":"barfoo!", - "timeout":600, - "method":null + "password":"mypassword", + "timeout":300, + "method":"aes-256-cfb", + "fast_open": false, + "workers": 1 } Explanation of the fields: -:: - - server your server IP (IPv4/IPv6), notice that your server will listen to this IP - server_port server port - local_port local port - password a password used to encrypt transfer - timeout in seconds - method encryption method, "bf-cfb", "aes-256-cfb", "des-cfb", "rc4", etc. Default is table - -``cd`` into the directory of ``config.json``. Run ``ssserver`` on your -server. To run it in the background, run ``nohup ssserver > log &``. - -On your client machine, run ``sslocal``. ++------------------+-----------------------------------------------------------------------------------------------------+ +| Name | Explanation | ++==================+=====================================================================================================+ +| server | the address your server listens | ++------------------+-----------------------------------------------------------------------------------------------------+ +| server\_port | server port | ++------------------+-----------------------------------------------------------------------------------------------------+ +| local\_address | the address your local listens | ++------------------+-----------------------------------------------------------------------------------------------------+ +| local\_port | local port | ++------------------+-----------------------------------------------------------------------------------------------------+ +| password | password used for encryption | ++------------------+-----------------------------------------------------------------------------------------------------+ +| timeout | in seconds | ++------------------+-----------------------------------------------------------------------------------------------------+ +| method | encryption method, "aes-256-cfb" is recommended | ++------------------+-----------------------------------------------------------------------------------------------------+ +| fast\_open | use `TCP\_FASTOPEN `__, true / false | ++------------------+-----------------------------------------------------------------------------------------------------+ +| workers | number of workers, available on Unix/Linux | ++------------------+-----------------------------------------------------------------------------------------------------+ + +Run ``ssserver -c /etc/shadowsocks.json`` on your server. To run it in +the background, `use +supervisor `__. + +On your client machine, run ``sslocal -c /etc/shadowsocks.json``. Change the proxy settings in your browser to @@ -62,6 +113,12 @@ Change the proxy settings in your browser to hostname: 127.0.0.1 port: your local_port +**Notice: If you want to use encryption methods other than "table", +please install M2Crypto (See Encryption Section).** + +It's recommended to use shadowsocks with AutoProxy or Proxy +SwitchySharp. + Command line args ----------------- @@ -70,42 +127,30 @@ You can use args to override settings from ``config.json``. :: sslocal -s server_name -p server_port -l local_port -k password -m bf-cfb - ssserver -p server_port -k password -m bf-cfb + ssserver -p server_port -k password -m bf-cfb --workers 2 ssserver -c /etc/shadowsocks/config.json -Encryption ----------- - -If you want to use non-default encryption methods like "bf-cfb", please -install `M2Crypto `__. - -Ubuntu: - -:: - - sudo apt-get install python-m2crypto - -Others: +Salsa20 +------- -:: +Salsa20 is a fast stream cipher. - pip install M2Crypto +Use "salsa20-ctr" in shadowsocks.json. -Performance ------------ +And install these packages: -You may want to install gevent for better performance. +Debian / Ubuntu: +^^^^^^^^^^^^^^^^ :: - $ sudo apt-get install python-gevent + apt-get install python-numpy + pip install salsa20 -Or: +Wiki +---- -:: - - $ sudo apt-get install libevent-dev python-pip - $ sudo pip install gevent +https://github.com/clowwindy/shadowsocks/wiki License ------- @@ -118,5 +163,10 @@ Bugs and Issues Please visit `issue tracker `__ -.. |Build Status| image:: https://travis-ci.org/clowwindy/shadowsocks.png +Mailing list: http://groups.google.com/group/shadowsocks + +Also see +`troubleshooting `__ + +.. |Build Status| image:: https://travis-ci.org/clowwindy/shadowsocks.png?branch=master :target: https://travis-ci.org/clowwindy/shadowsocks