Alawn/shadowsocks-libev
1
0
Fork 0
mirror of https://github.com/shadowsocks/shadowsocks-libev.git synced 2026-10-20 21:43:41 +00:00
Code Releases Activity
Files
dependabot/github_actions/actions/setup-python-7
shadowsocks-libev/doc/ss-manager.asciidoc
T
Max Lv 46791234c0 Add Shadowsocks 2022 (SIP022) ciphers 
shadowsocks-rust has supported the 2022 edition for years while libev was
stuck on the 2017 AEAD construction, the largest functional gap between
the two implementations. This adds the three SIP022 methods:

  2022-blake3-aes-128-gcm
  2022-blake3-aes-256-gcm
  2022-blake3-chacha20-poly1305

TCP uses BLAKE3 derive_key for session subkeys, standalone header chunks
carrying a type byte and timestamp, request padding, and a response header
echoing the request salt. Replay protection uses an exact-match salt pool
with 60s retention rather than the bloom filter, which SIP022 forbids
because false positives are unacceptable there.

UDP is session-based: an AES-ECB separate header for the AES methods and a
merged XChaCha20-Poly1305 construction for ChaCha, with a per-session
sliding window replay filter. Servers must route by client session ID,
which is only known after decryption, so the crypto layer owns the
server-side session table and hands the session back to udprelay for the
reply path.

The 2022 code lives in aead2022.c and aead2022_udp.c so aead.c keeps its
current size, with aead_internal.h carrying what they share. BLAKE3 is
vendored (portable backend only) as its own build target.

Keys are base64 pre-shared keys of exactly the cipher's key size; per
SIP022 a password is never stretched into a key.

Verified interoperable in both directions against shadowsocks-rust 1.24.0
for all three ciphers over TCP and UDP, including an 8MB transfer checked
by digest, plus unit tests for header framing, partial delivery, tamper
detection, and UDP replay rejection.
2026-08-19 18:15:35 +08:00

197 lines
5.5 KiB
Plaintext
Raw Permalink Blame History

ss-manager(1)
=============
NAME
----
ss-manager - ss-server controller for multi-user management and traffic statistics
SYNOPSIS
--------
*ss-manager*
[-AuUv] [-h|--help]
[-s <server_host>] [-p <server_port>] [-l <local_port>]
[-k <password>] [-m <encrypt_method>] [-f <pid_file>]
[-t <timeout>] [-c <config_file>] [-i <interface>]
[-b <local_addr>] [-a <user_name>] [-D <path>]
[--manager-address <path_to_unix_domain>]
[--executable <path_to_server_executable>]
[--fast-open] [--reuse-port]
[--plugin <plugin_name>] [--plugin-opts <plugin_options>]
DESCRIPTION
-----------
*Shadowsocks-libev* is a lightweight and secure socks5 proxy.
It is a port of the original shadowsocks created by clowwindy.
*Shadowsocks-libev* is written in pure C and takes advantage of libev to
achieve both high performance and low resource consumption.
*Shadowsocks-libev* consists of five components.
`ss-manager`(1) is a controller for multi-user management and
traffic statistics, using UNIX domain socket to talk with `ss-server`(1).
Also, it provides a UNIX domain socket or IP based API for other software.
About the details of this API, please refer to the following 'PROTOCOL'
section.
OPTIONS
-------
-s <server_host>::
Set the server's hostname or IP.
-k <password>::
Set the password. The server and the client should use the same password.
-m <encrypt_method>::
Set the cipher.
+
*Shadowsocks-libev* accepts 22 different ciphers:
+
2022-blake3-aes-128-gcm, 2022-blake3-aes-256-gcm,
2022-blake3-chacha20-poly1305,
aes-128-gcm, aes-192-gcm, aes-256-gcm,
rc4-md5, aes-128-cfb, aes-192-cfb, aes-256-cfb,
aes-128-ctr, aes-192-ctr, aes-256-ctr, bf-cfb,
camellia-128-cfb, camellia-192-cfb, camellia-256-cfb,
chacha20-ietf-poly1305, xchacha20-ietf-poly1305,
salsa20, chacha20 and chacha20-ietf.
+
The default cipher is 'chacha20-ietf-poly1305'.
+
The '2022-blake3-*' ciphers implement Shadowsocks 2022 (SIP022) and are
the recommended choice: they provide full replay protection and
session-based UDP relay. They require a base64-encoded pre-shared key of
exactly the cipher's key size (16 bytes for 2022-blake3-aes-128-gcm, 32
bytes for the others) given with *-k*; passwords are not accepted and are
never stretched into a key. Generate one with `openssl rand -base64 32`.
+
If built with PolarSSL or custom OpenSSL libraries, some of
these ciphers may not work.
-a <user_name>::
Run as a specific user.
-f <pid_file>::
Start shadowsocks as a daemon with specific pid file.
-t <timeout>::
Set the socket timeout in seconds. The default value is 60.
-c <config_file>::
Use a configuration file.
+
You may use "port_password" field inside this configuration file to bring up
multiple ss-server instances together.
-i <interface>::
Send traffic through specific network interface.
+
For example, there are three interfaces in your device,
which is lo (127.0.0.1), eth0 (192.168.0.1) and eth1 (192.168.0.2).
Meanwhile, you configure `ss-local` to listen on 0.0.0.0:8388 and bind to eth1.
That results the traffic go out through eth1, but not lo nor eth0.
This option is useful to control traffic in multi-interface environment.
-u::
Enable UDP relay.
-U::
Enable UDP relay and disable TCP relay.
-A::
Enable onetime authentication.
-d <addr>::
Setup name servers for internal DNS resolver (libc-ares).
The default server is fetched from `/etc/resolv.conf`.
--fast-open::
Enable TCP fast open.
+
Only available with Linux kernel > 3.7.0.
--reuse-port::
Enable port reuse.
+
Only available with Linux kernel > 3.9.0.
--acl <acl_config>::
Enable ACL (Access Control List) and specify config file.
--manager-address <path_to_unix_domain>::
Specify UNIX domain socket address for the communication between ss-manager(1) and ss-server(1).
+
Only available in server and manager mode.
--executable <path_to_server_executable>::
Specify the executable path of ss-server.
+
Only available in manager mode.
-D <path>::
--workdir <path>::
Specify the working directory of ss-manager.
+
Only available in manager mode.
--plugin <plugin_name>::
Enable SIP003 plugin. (Experimental)
--plugin-opts <plugin_options>::
Set SIP003 plugin options. (Experimental)
-v::
Enable verbose mode.
-h|--help::
Print help message.
PROTOCOL
--------
`ss-manager`(1) provides several APIs through UDP protocol:
Send UDP commands in the following format to the manager-address provided to ss-manager(1): ::::
command: [JSON data]
To add a port: ::::
add: {"server_port": 8001, "password":"7cd308cc059"}
To remove a port: ::::
remove: {"server_port": 8001}
To receive the traffic statistics: ::::
ping
The format of the traffic statistics: ::::
stat: {"8001":11370}
There is no way to reset the traffic statistics, unless you remove the port and add it again
EXAMPLE
-------
To use `ss-manager`(1), First start it and specify necessary information.
Then communicate with `ss-manager`(1) through UNIX Domain Socket using UDP
protocol:
....
# Start the manager. Arguments for ss-server will be passed to generated
# ss-server process(es) respectively.
ss-manager --manager-address /tmp/manager.sock --executable $(which ss-server) -s example.com -m aes-256-cfb -c /path/to/config.json
# Connect to the socket. Using netcat-openbsd as an example.
# You should use scripts or other programs for further management.
nc -Uu /tmp/manager.sock
....
After that, you may communicate with `ss-manager`(1) as described above in the
'PROTOCOL' section.
SEE ALSO
--------
`ss-local`(1),
`ss-server`(1),
`ss-tunnel`(1),
`ss-redir`(1),
`shadowsocks-libev`(8),
`iptables`(8),
/etc/shadowsocks-libev/config.json
View Git Blame Copy Permalink