'\" t
.\"     Title: ss-manager
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 09/07/2023
.\"    Manual: Shadowsocks-libev Manual
.\"    Source: Shadowsocks-libev 3.3.4
.\"  Language: English
.\"
.TH "SS\-MANAGER" "1" "09/07/2023" "Shadowsocks\-libev 3\&.3\&.4" "Shadowsocks\-libev Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ss-manager \- ss\-server controller for multi\-user management and traffic statistics
.SH "SYNOPSIS"
.sp
\fBss\-manager\fR [\-AuUv] [\-h|\-\-help] [\-s \fI<server_host>\fR] [\-p \fI<server_port>\fR] [\-l \fI<local_port>\fR] [\-k \fI<password>\fR] [\-m \fI<encrypt_method>\fR] [\-f \fI<pid_file>\fR] [\-t \fI<timeout>\fR] [\-c \fI<config_file>\fR] [\-i \fI<interface>\fR] [\-b \fI<local_addr>\fR] [\-a \fI<user_name>\fR] [\-D \fI<path>\fR] [\-\-manager\-address \fI<path_to_unix_domain>\fR] [\-\-executable \fI<path_to_server_executable>\fR] [\-\-fast\-open] [\-\-reuse\-port] [\-\-plugin \fI<plugin_name>\fR] [\-\-plugin\-opts \fI<plugin_options>\fR]
.SH "DESCRIPTION"
.sp
\fBShadowsocks\-libev\fR is a lightweight and secure socks5 proxy\&. It is a port of the original shadowsocks created by clowwindy\&. \fBShadowsocks\-libev\fR is written in pure C and takes advantage of libev to achieve both high performance and low resource consumption\&.
.sp
\fBShadowsocks\-libev\fR consists of five components\&. \fBss\-manager\fR(1) is a controller for multi\-user management and traffic statistics, using UNIX domain socket to talk with \fBss\-server\fR(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 \fIPROTOCOL\fR section\&.
.SH "OPTIONS"
.PP
\-s \fI<server_host>\fR
.RS 4
Set the server\(cqs hostname or IP\&.
.RE
.PP
\-k \fI<password>\fR
.RS 4
Set the password\&. The server and the client should use the same password\&.
.RE
.PP
\-m \fI<encrypt_method>\fR
.RS 4
Set the cipher\&.
.sp
\fBShadowsocks\-libev\fR
accepts 18 different ciphers:
.sp
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, salsa20, chacha20 and chacha20\-ietf\&.
.sp
The default cipher is
\fIchacha20\-ietf\-poly1305\fR\&.
.sp
If built with PolarSSL or custom OpenSSL libraries, some of these ciphers may not work\&.
.RE
.PP
\-a \fI<user_name>\fR
.RS 4
Run as a specific user\&.
.RE
.PP
\-f \fI<pid_file>\fR
.RS 4
Start shadowsocks as a daemon with specific pid file\&.
.RE
.PP
\-t \fI<timeout>\fR
.RS 4
Set the socket timeout in seconds\&. The default value is 60\&.
.RE
.PP
\-c \fI<config_file>\fR
.RS 4
Use a configuration file\&.
.sp
You may use "port_password" field inside this configuration file to bring up multiple ss\-server instances together\&.
.RE
.PP
\-i \fI<interface>\fR
.RS 4
Send traffic through specific network interface\&.
.sp
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
\fBss\-local\fR
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\&.
.RE
.PP
\-u
.RS 4
Enable UDP relay\&.
.RE
.PP
\-U
.RS 4
Enable UDP relay and disable TCP relay\&.
.RE
.PP
\-A
.RS 4
Enable onetime authentication\&.
.RE
.PP
\-d \fI<addr>\fR
.RS 4
Setup name servers for internal DNS resolver (libc\-ares)\&. The default server is fetched from
\fB/etc/resolv\&.conf\fR\&.
.RE
.PP
\-\-fast\-open
.RS 4
Enable TCP fast open\&.
.sp
Only available with Linux kernel > 3\&.7\&.0\&.
.RE
.PP
\-\-reuse\-port
.RS 4
Enable port reuse\&.
.sp
Only available with Linux kernel > 3\&.9\&.0\&.
.RE
.PP
\-\-acl \fI<acl_config>\fR
.RS 4
Enable ACL (Access Control List) and specify config file\&.
.RE
.PP
\-\-manager\-address \fI<path_to_unix_domain>\fR
.RS 4
Specify UNIX domain socket address for the communication between ss\-manager(1) and ss\-server(1)\&.
.sp
Only available in server and manager mode\&.
.RE
.PP
\-\-executable \fI<path_to_server_executable>\fR
.RS 4
Specify the executable path of ss\-server\&.
.sp
Only available in manager mode\&.
.RE
.PP
\-\-executable \fI<path_to_server_executable>\fR
.RS 4
Specify the working directory of ss\-manager\&.
.sp
Only available in manager mode\&.
.RE
.PP
\-\-plugin \fI<plugin_name>\fR
.RS 4
Enable SIP003 plugin\&. (Experimental)
.RE
.PP
\-\-plugin\-opts \fI<plugin_options>\fR
.RS 4
Set SIP003 plugin options\&. (Experimental)
.RE
.PP
\-v
.RS 4
Enable verbose mode\&.
.RE
.PP
\-h|\-\-help
.RS 4
Print help message\&.
.RE
.SH "PROTOCOL"
.sp
\fBss\-manager\fR(1) provides several APIs through UDP protocol:
.PP
Send UDP commands in the following format to the manager\-address provided to ss\-manager(1):
.RS 4
command: [JSON data]
.RE
.PP
To add a port:
.RS 4
add: {"server_port": 8001, "password":"7cd308cc059"}
.RE
.PP
To remove a port:
.RS 4
remove: {"server_port": 8001}
.RE
.PP
To receive the traffic statistics:
.RS 4
ping
.RE
.PP
The format of the traffic statistics:
.RS 4
stat: {"8001":11370}
.RE
.sp
There is no way to reset the traffic statistics, unless you remove the port and add it again
.SH "EXAMPLE"
.sp
To use \fBss\-manager\fR(1), First start it and specify necessary information\&.
.sp
Then communicate with \fBss\-manager\fR(1) through UNIX Domain Socket using UDP protocol:
.sp
.if n \{\
.RS 4
.\}
.nf
# 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
.fi
.if n \{\
.RE
.\}
.sp
After that, you may communicate with \fBss\-manager\fR(1) as described above in the \fIPROTOCOL\fR section\&.
.SH "SEE ALSO"
.sp
\fBss\-local\fR(1), \fBss\-server\fR(1), \fBss\-tunnel\fR(1), \fBss\-redir\fR(1), \fBshadowsocks\-libev\fR(8), \fBiptables\fR(8), /etc/shadowsocks\-libev/config\&.json
