mirrors/shadowsocks-libev
0
0 Fork 0
mirror of https://github.com/shadowsocks/shadowsocks-libev.git synced 2026-10-28 10:44:43 +08:00
Code Activity

Generate CLI manual sections from source option declarations

Browse Source
This commit is contained in:
Max Lv committed 2026-09-12 10:51:25 +08:00
1 parent 463ff72ca0
commit 146818c182
19 files changed
+1129 -657
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.github/workflows/tests.yml
+21
View File
@@ -26,6 +26,27 @@ jobs:
run: actionlint -shellcheck= -pyflakes=
- name: Lint Python scripts and tests
run: ruff check --select E9,F63,F7,F82 tests scripts
- name: Check generated CLI documentation
run: |
python3 scripts/gen_cli_docs.py --check
python3 -m unittest discover -s tests -p test_gen_cli_docs.py
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Install documentation tools
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends asciidoc xmlto docbook-xml docbook-xsl
- name: Build man pages and HTML from source
run: |
cmake -S . -B build-docs -DWITH_DOC_MAN=ON -DWITH_DOC_HTML=ON
cmake --build build-docs --target doc-man doc-html --parallel 2
test -s build-docs/man/ss-local.1
test -s build-docs/man/ss-nat.1
test -s build-docs/man/shadowsocks-c.8
test -s build-docs/html/ss-local.html
tests:
strategy:
CONTRIBUTION.md
+32
View File
@@ -73,6 +73,38 @@ unless a change has been discussed. For bundled dependency updates, follow
[the update procedure](third_party/README.md) and preserve upstream licenses and
notices.
## CLI and manual documentation
The SYNOPSIS and OPTIONS sections of the manual pages are generated from the
literal `getopt_long` declarations in `src/{local,server,tunnel,redir,manager}.c`
and the `getopts` declaration in `src/ss-nat`. Descriptions and argument names live
in `CLI_DOC` source comments: common C options in `src/utils.c`, program-specific
overrides in the corresponding C file, and shell options in `src/ss-nat`.
Each entry has an AsciiDoc term such as `--mtu <MTU>::` followed by its description.
The generator checks option coverage and argument arity across platform variants;
describe platform or feature restrictions in the comment. Cipher lists come from
the C cipher tables. Keep explanatory sections and examples in `doc/*.asciidoc`.
After changing a parser or its documentation comments, regenerate the checked-in
pages and run the generator tests:
```sh
python3 scripts/gen_cli_docs.py
python3 scripts/gen_cli_docs.py --check
python3 -m unittest discover -s tests -p test_gen_cli_docs.py
```
To render the manuals, install Python 3, AsciiDoc, and xmlto, then run:
```sh
cmake -S . -B build-docs -DWITH_DOC_MAN=ON -DWITH_DOC_HTML=ON
cmake --build build-docs --target doc-man doc-html --parallel
```
The build generates pages in the build directory without modifying source files
or executing target binaries, so it also works when cross-compiling. CI checks
that committed pages are current and renders both man and HTML output.
## Pull requests
Open your pull request against `master`. Explain the problem, what changes for
README.md
+5 -1
View File
@@ -145,7 +145,7 @@ client mode and build options. Existing Snap packages still use the
The default build uses pinned sources included in this repository. It needs a
C11 compiler, CMake 3.20+, and Make or Ninja. No Git submodules, dependency
package installations, or network access are needed for configuration/build.
Python is used only by integration tests; documentation generation is optional.
Python is used by integration tests and optional documentation generation.
```sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
@@ -157,6 +157,10 @@ cmake --install build --prefix /your/install/prefix
Programs are in `build/bin/`. Bundled binaries link to platform runtime
libraries; they do not require separately installed third-party libraries.
Man pages and HTML documentation derive their CLI sections from the source
option parsers. See [the documentation workflow](CONTRIBUTION.md#cli-and-manual-documentation)
for regeneration and rendering commands.
For a smaller build, use `-DSS_MINIMAL=ON`. It excludes PCRE2 regex, plugin
subprocesses, the manager, and legacy stream ciphers. Minimal ACLs support
IPv4/IPv6 CIDRs, `full:example.com` for exact domains, and
doc/CMakeLists.txt
+49 -9
View File
@@ -10,18 +10,53 @@ if(WITH_DOC_MAN AND NOT XMLTO_EXECUTABLE)
message(FATAL_ERROR "Manpage generation requires xmlto")
endif()
# NOTE For brew user, we have to setup this env var. see `brew info asciidoc'
# Homebrew catalogs are outside libxml's default search path. Respect an
# explicitly configured catalog and support both Apple Silicon and Intel Macs.
set(XMLTO_ENV)
set(XMLTO_CATALOG_DIR_MACOS /usr/local/etc/xml/catalog)
if (EXISTS ${XMLTO_CATALOG_DIR_MACOS})
set(XMLTO_ENV XML_CATALOG_FILES=${XMLTO_CATALOG_DIR_MACOS})
message(STATUS "Detect xmlto catalog dir ${XMLTO_CATALOG_DIR_MACOS}")
endif ()
if(APPLE AND "$ENV{XML_CATALOG_FILES}" STREQUAL "")
foreach(catalog /opt/homebrew/etc/xml/catalog /usr/local/etc/xml/catalog)
if(EXISTS ${catalog})
set(XMLTO_ENV XML_CATALOG_FILES=${catalog})
break()
endif()
endforeach()
endif()
set(CMAKE_MANPAGE_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/man)
set(CMAKE_HTML_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/html)
set(DOC_DIR ${PROJECT_SOURCE_DIR}/doc)
find_package(Python3 COMPONENTS Interpreter QUIET)
if((WITH_DOC_MAN OR WITH_DOC_HTML) AND NOT Python3_Interpreter_FOUND)
message(FATAL_ERROR "Documentation generation requires Python 3")
endif()
# Read source declarations, never execute target binaries (including cross builds).
# Keep checked-in pages for readers and for builds with documentation disabled.
set(CLI_DOC_DIR ${DOC_DIR})
set(CLI_DOC_FILES)
if(Python3_Interpreter_FOUND)
set(CLI_DOC_DIR ${CMAKE_CURRENT_BINARY_DIR}/generated)
set(CLI_DOC_INPUTS ${PROJECT_SOURCE_DIR}/src/utils.c
${PROJECT_SOURCE_DIR}/src/aead.c ${PROJECT_SOURCE_DIR}/src/stream.c
${PROJECT_SOURCE_DIR}/src/ss-nat)
foreach(module local server tunnel redir manager)
list(APPEND CLI_DOC_INPUTS ${PROJECT_SOURCE_DIR}/src/${module}.c)
endforeach()
foreach(name ss-local ss-server ss-tunnel ss-redir ss-manager ss-nat shadowsocks-c)
list(APPEND CLI_DOC_INPUTS ${DOC_DIR}/${name}.asciidoc)
list(APPEND CLI_DOC_FILES ${CLI_DOC_DIR}/${name}.asciidoc)
endforeach()
add_custom_command(OUTPUT ${CLI_DOC_FILES}
COMMAND ${Python3_EXECUTABLE} ${PROJECT_SOURCE_DIR}/scripts/gen_cli_docs.py
--output-dir ${CLI_DOC_DIR}
COMMAND ${CMAKE_COMMAND} -E touch ${CLI_DOC_FILES}
DEPENDS ${CLI_DOC_INPUTS} ${PROJECT_SOURCE_DIR}/scripts/gen_cli_docs.py
COMMENT "Generating CLI documentation from source"
VERBATIM)
add_custom_target(doc-cli DEPENDS ${CLI_DOC_FILES})
endif()
set(XMLTO_OPTS -m ${DOC_DIR}/manpage-normal.xsl -m ${DOC_DIR}/manpage-bold-literal.xsl man)
set(ASCIIDOC_XML_OPTS -b docbook -d manpage -f ${DOC_DIR}/asciidoc.conf -aversion=${PROJECT_VERSION})
set(ASCIIDOC_HTML_OPTS -b html4 -d article -f ${DOC_DIR}/asciidoc.conf -aversion=${PROJECT_VERSION})
@@ -38,14 +73,15 @@ foreach (manfile IN LISTS MAN_NAMES)
set(manfile ${CMAKE_MANPAGE_OUTPUT_DIRECTORY}/${manfile})
set(htmlfile ${CMAKE_HTML_OUTPUT_DIRECTORY}/${htmlfile})
set(docfile ${DOC_DIR}/${docfile})
set(docfile ${CLI_DOC_DIR}/${docfile})
add_custom_command(OUTPUT ${manfile}
COMMAND ${ASCIIDOC_EXECUTABLE} ${ASCIIDOC_XML_OPTS} -o ${xmlfile} ${docfile}
COMMAND ${CMAKE_COMMAND} -E env ${XMLTO_ENV} ${XMLTO_EXECUTABLE} ${XMLTO_OPTS} ${xmlfile}
# After we built the manpage, the xmlfile is nolongger needed
COMMAND ${CMAKE_COMMAND} -E remove ${xmlfile}
DEPENDS ${docfile}
DEPENDS ${docfile} ${DOC_DIR}/asciidoc.conf
${DOC_DIR}/manpage-normal.xsl ${DOC_DIR}/manpage-bold-literal.xsl
WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/man
COMMENT "Building manpage ${manfile}"
VERBATIM)
@@ -53,7 +89,7 @@ foreach (manfile IN LISTS MAN_NAMES)
add_custom_command(OUTPUT ${htmlfile}
COMMAND ${ASCIIDOC_EXECUTABLE} ${ASCIIDOC_HTML_OPTS} -o ${htmlfile} ${docfile}
DEPENDS ${docfile}
DEPENDS ${docfile} ${DOC_DIR}/asciidoc.conf
WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/html
COMMENT "Building htmlfile ${htmlfile}"
VERBATIM)
@@ -62,6 +98,10 @@ endforeach ()
add_custom_target(doc-man ALL DEPENDS ${MAN_FILES})
add_custom_target(doc-html ALL DEPENDS ${HTML_FILES})
if(TARGET doc-cli)
add_dependencies(doc-man doc-cli)
add_dependencies(doc-html doc-cli)
endif()
if (NOT WITH_DOC_MAN)
doc/asciidoc.conf
+2 -2
View File
@@ -24,9 +24,9 @@ template::[header-declarations]
<refmeta>
<refentrytitle>{mantitle}</refentrytitle>
<manvolnum>{manvolnum}</manvolnum>
<refmiscinfo class="source">Shadowsocks-libev</refmiscinfo>
<refmiscinfo class="source">shadowsocks-c</refmiscinfo>
<refmiscinfo class="version">{version}</refmiscinfo>
<refmiscinfo class="manual">Shadowsocks-libev Manual</refmiscinfo>
<refmiscinfo class="manual">shadowsocks-c Manual</refmiscinfo>
</refmeta>
<refnamediv>
<refname>{manname}</refname>
doc/shadowsocks-c.asciidoc
+27 -174
View File
@@ -7,15 +7,25 @@ shadowsocks-c - a lightweight and secure socks5 proxy
SYNOPSIS
--------
*ss-local*|*ss-redir*|*ss-server*|*ss-tunnel*|*ss-manager*
[-s <server_host>] [-p <server_port>] [-l <local_port>] [-k <password>]
[-m <encrypt_method>] [-f <pid_file>] [-t <timeout>] [-c <config_file>]
// Generated by scripts/gen_cli_docs.py; do not edit this section.
*ss-local* [options]
*ss-server* [options]
*ss-tunnel* [options]
*ss-redir* [options]
*ss-manager* [options]
*ss-nat* [options]
DESCRIPTION
-----------
*shadowsocks-c* is a lightweight and secure socks5 proxy.
It is a port of the original shadowsocks created by clowwindy.
*shadowsocks-c* is written in pure C and takes advantage of *libev*
*shadowsocks-c* is written in pure C and takes advantage of *libuv*
to achieve both high performance and low resource consumption.
*shadowsocks-c* consists of five components. One is `ss-server`(1)
@@ -35,182 +45,25 @@ About the details of this API, please refer to the 'PROTOCOL' section.
OPTIONS
-------
// Generated by scripts/gen_cli_docs.py; do not edit this section.
-s <server_host>::
Set the server's hostname or IP.
`ss-local`(1)::
See this command's generated SYNOPSIS and OPTIONS for its accepted arguments.
-l <local_port>::
Set the local port number.
+
Not available in server nor manager mode.
`ss-server`(1)::
See this command's generated SYNOPSIS and OPTIONS for its accepted arguments.
-k <password>::
--password <password>::
Set the password. The server and the client should use the same password.
`ss-tunnel`(1)::
See this command's generated SYNOPSIS and OPTIONS for its accepted arguments.
--key <key_in_base64>::
Set the key directly. The key should be encoded with URL-safe Base64.
+
Not available in manager mode.
`ss-redir`(1)::
See this command's generated SYNOPSIS and OPTIONS for its accepted arguments.
-m <encrypt_method>::
Set the cipher.
+
*shadowsocks-c* 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.
`ss-manager`(1)::
See this command's generated SYNOPSIS and OPTIONS for its accepted arguments.
-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.
-n <number>::
Specify max number of open files.
+
Not available in manager mode.
+
Only available on Linux.
-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 *shadowsocks-libev* 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.
+
Not available in redir mode.
-b <local_address>::
Specify the local address to bind.
+
For servers: Specify the local address to use while this server is making
outbound connections to remote servers on behalf of the clients.
+
For clients: Specify the local address to use while this client is making
outbound connections to the server.
+
Not available in manager mode.
-u::
Enable UDP relay.
+
TPROXY is required in redir mode. You may need root permission.
-U::
Enable UDP relay and disable TCP relay.
+
Not available in local mode.
-T::
Use tproxy instead of redirect (for tcp).
+
Only available in redir mode.
-L <addr:port>::
Specify destination server address and port for local port forwarding.
+
Only available in tunnel mode.
-d <addr>::
Setup name servers for internal DNS resolver (libc-ares).
The default server is fetched from /etc/resolv.conf.
+
Only available in server and manager mode.
--fast-open::
Enable TCP fast open.
+
Not available in redir nor tunnel mode, with Linux kernel > 3.7.0.
--reuse-port::
Enable port reuse.
+
Only available with Linux kernel > 3.9.0.
--no-delay::
Enable TCP_NODELAY.
--tcp-incoming-sndbuf <size>::
Set TCP send buffer size for incoming connections.
+
Not available in manager mode.
--tcp-incoming-rcvbuf <size>::
Set TCP receive buffer size for incoming connections.
+
Not available in manager mode.
--tcp-outgoing-sndbuf <size>::
Set TCP send buffer size for outgoing connections.
+
Not available in manager mode.
--tcp-outgoing-rcvbuf <size>::
Set TCP receive buffer size for outgoing connections.
+
Not available in manager mode.
--acl <acl_config>::
Enable ACL (Access Control List) and specify config file.
+
Not available in redir nor tunnel mode.
--manager-address <path_to_unix_domain>::
Specify UNIX domain socket address.
+
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.
--nftables-sets <family:table:set>::
Specify nftables sets for reporting malicious IPs.
+
Only available in server mode, when built with nftables support.
-v::
Enable verbose mode.
-h|--help::
Print help message.
`ss-nat`(1)::
See this command's generated SYNOPSIS and OPTIONS for its accepted arguments.
CONFIG FILE
-----------
doc/ss-local.asciidoc
+123 -128
View File
@@ -3,35 +3,42 @@ ss-local(1)
NAME
----
ss-local - shadowsocks client as socks5 proxy, libev port
ss-local - shadowsocks client as socks5 proxy, C implementation
SYNOPSIS
--------
*ss-local*
[-uv6] [-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>]
[-a <user_name>] [-b <local_address>] [-n <nofile>]
[--fast-open] [--reuse-port] [--acl <acl_config>]
[--mtu <MTU>] [--no-delay]
[--plugin <plugin_name>] [--plugin-opts <plugin_options>]
[--password <password>] [--key <key_in_base64>]
[--server-url <ss_url>]
// Generated by scripts/gen_cli_docs.py from src/local.c; do not edit this section.
*ss-local* [-f <pid_file>] [-s <server_host>] [-p <server_port>] [-l
<local_port>] [-k <password>] [-t <timeout>] [-m <encrypt_method>] [-i
<interface>] [-c <config_file>] [-b <local_address>] [-a <user_name>] [-n
<number>] [-S <path>] [-h] [-u] [-U] [-v] [-V] [-6] [-A] [--reuse-port]
[--tcp-incoming-sndbuf <size>] [--tcp-incoming-rcvbuf <size>]
[--tcp-outgoing-sndbuf <size>] [--tcp-outgoing-rcvbuf <size>] [--fast-open]
[--no-delay] [--acl <acl_config>] [--mtu <MTU>] [--mptcp] [--plugin
<plugin_name>] [--plugin-opts <plugin_options>] [--password <password>]
[--key <key_in_base64>] [--server-url <ss_url>] [--help]
DESCRIPTION
-----------
*Shadowsocks-libev* is a lightweight and secure socks5 proxy.
*shadowsocks-c* 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
*shadowsocks-c* is written in pure C and takes advantage of libuv to
achieve both high performance and low resource consumption.
*Shadowsocks-libev* consists of five components. `ss-local`(1) works as a standard
*shadowsocks-c* consists of five components. `ss-local`(1) works as a standard
socks5 proxy on local machines to proxy TCP traffic.
For more information, check out `shadowsocks-libev`(8).
OPTIONS
-------
// Generated by scripts/gen_cli_docs.py from src/local.c; do not edit this section.
This section lists options across supported builds. Platform and feature
restrictions are noted below; not every option is effective on every platform.
-f <pid_file>::
Start shadowsocks as a daemon with specific pid file.
-s <server_host>::
Set the server's hostname or IP.
@@ -43,6 +50,106 @@ Set the server's port number.
Set the local port number.
-k <password>::
Set the password. The server and the client should use the same password.
-t <timeout>::
Set the socket timeout in seconds. The default value is 60.
-m <encrypt_method>::
Set the cipher. The default is 'chacha20-ietf-poly1305'.
+
AEAD cipher names from the source (availability depends on the build):
aes-128-gcm, aes-192-gcm, aes-256-gcm, 2022-blake3-aes-128-gcm, 2022-blake3-aes-256-gcm, chacha20-ietf-poly1305, 2022-blake3-chacha20-poly1305, xchacha20-ietf-poly1305.
+
Legacy stream cipher names recognized by the source (disabled in minimal builds;
some require backend support): table, rc4, 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, cast5-cfb, des-cfb, idea-cfb, rc2-cfb, seed-cfb, salsa20, chacha20, chacha20-ietf.
+
The '2022-blake3-*' ciphers implement Shadowsocks 2022 (SIP022). They require
a base64-encoded pre-shared key supplied with *-k*: 16 bytes for
2022-blake3-aes-128-gcm and 32 bytes for the other 2022 ciphers.
Generate a 32-byte key with `openssl rand -base64 32`.
Passwords are not stretched into keys for these ciphers.
-i <interface>::
Send outbound traffic through the specified network interface where supported by the platform.
-c <config_file>::
Use a configuration file.
+
Refer to `shadowsocks-c`(8) 'CONFIG FILE' section for more details.
-b <local_address>::
Specify the local address to use while this client is making outbound
connections to the server.
-a <user_name>::
Run as a specific user.
-n <number>::
Specify the maximum number of open files. Requires a platform with setrlimit support.
-S <path>::
Android only: UNIX socket path for traffic statistics.
-h::
Print help message.
-u::
Enable UDP relay.
-U::
Enable UDP relay and disable TCP relay.
-v::
Enable verbose mode.
-V::
Android only: enable VPN socket protection.
-6::
Resolve hostname to IPv6 address first.
-A::
Deprecated one-time authentication option. Exits with an error; use AEAD ciphers instead.
--reuse-port::
Enable port reuse where supported by the operating system.
--tcp-incoming-sndbuf <size>::
Set TCP send buffer size for incoming connections.
--tcp-incoming-rcvbuf <size>::
Set TCP receive buffer size for incoming connections.
--tcp-outgoing-sndbuf <size>::
Set TCP send buffer size for outgoing connections.
--tcp-outgoing-rcvbuf <size>::
Set TCP receive buffer size for outgoing connections.
--fast-open::
Enable TCP Fast Open where supported by the operating system.
--no-delay::
Enable TCP_NODELAY.
--acl <acl_config>::
Enable ACL (Access Control List) and specify config file.
--mtu <MTU>::
Specify the MTU of your network interface.
--mptcp::
Enable Multipath TCP.
+
Only available with MPTCP enabled Linux kernel.
--plugin <plugin_name>::
Enable SIP003 plugin. (Experimental)
--plugin-opts <plugin_options>::
Set SIP003 plugin options. (Experimental)
--password <password>::
Set the password. The server and the client should use the same password.
@@ -57,119 +164,7 @@ from a single 'ss://' URL, as produced by most clients and by
'ss://base64(method:password@host:port)' form are accepted. Options given
later on the command line override the values taken from the URL.
-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.
+
Refer to `shadowsocks-libev`(8) 'CONFIG FILE' section for more details.
-n <number>::
Specify max number of open files.
+
Only available on Linux.
-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.
-b <local_address>::
Specify the local address to use while this client is making outbound
connections to the server.
-u::
Enable UDP relay.
-U::
Enable UDP relay and disable TCP relay.
-6::
Resolve hostname to IPv6 address first.
--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.
--mtu <MTU>::
Specify the MTU of your network interface.
--mptcp::
Enable Multipath TCP.
+
Only available with MPTCP enabled Linux kernel.
--no-delay::
Enable TCP_NODELAY.
--tcp-incoming-sndbuf <size>::
Set TCP send buffer size for incoming connections.
--tcp-incoming-rcvbuf <size>::
Set TCP receive buffer size for incoming connections.
--tcp-outgoing-sndbuf <size>::
Set TCP send buffer size for outgoing connections.
--tcp-outgoing-rcvbuf <size>::
Set TCP receive buffer size for outgoing connections.
--plugin <plugin_name>::
Enable SIP003 plugin. (Experimental)
--plugin-opts <plugin_options>::
Set SIP003 plugin options. (Experimental)
-v::
Enable verbose mode.
-h|--help::
--help::
Print help message.
EXAMPLE
doc/ss-manager.asciidoc
+81 -85
View File
@@ -7,25 +7,24 @@ ss-manager - ss-server controller for multi-user management and traffic statisti
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>]
// Generated by scripts/gen_cli_docs.py from src/manager.c; do not edit this section.
*ss-manager* [-f <pid_file>] [-s <server_host>] [-l <local_port>] [-k
<password>] [-t <timeout>] [-m <encrypt_method>] [-c <config_file>] [-i
<interface>] [-d <addr>] [-a <user_name>] [-n <number>] [-D <path>] [-6] [-h]
[-u] [-U] [-v] [-A] [--fast-open] [--no-delay] [--reuse-port] [--acl
<acl_config>] [--manager-address <address>] [--executable <path>] [--mtu
<MTU>] [--plugin <plugin_name>] [--plugin-opts <plugin_options>] [--password
<password>] [--workdir <path>] [--help]
DESCRIPTION
-----------
*Shadowsocks-libev* is a lightweight and secure socks5 proxy.
*shadowsocks-c* 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
*shadowsocks-c* is written in pure C and takes advantage of libuv to
achieve both high performance and low resource consumption.
*Shadowsocks-libev* consists of five components.
*shadowsocks-c* 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.
@@ -34,103 +33,97 @@ section.
OPTIONS
-------
-s <server_host>::
Set the server's hostname or IP.
// Generated by scripts/gen_cli_docs.py from src/manager.c; do not edit this section.
-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.
This section lists options across supported builds. Platform and feature
restrictions are noted below; not every option is effective on every platform.
-f <pid_file>::
Start shadowsocks as a daemon with specific pid file.
-s <server_host>::
Set a server listening hostname or IP address. May be repeated.
-l <local_port>::
Accepted for compatibility but ignored by this program; it does not configure a local listener.
-k <password>::
Set the password. The server and the client should use the same password.
-t <timeout>::
Set the socket timeout in seconds. The default value is 60.
-c <config_file>::
Use a configuration file.
-m <encrypt_method>::
Set the cipher. The default is 'chacha20-ietf-poly1305'.
+
You may use "port_password" field inside this configuration file to bring up
multiple ss-server instances together.
AEAD cipher names from the source (availability depends on the build):
aes-128-gcm, aes-192-gcm, aes-256-gcm, 2022-blake3-aes-128-gcm, 2022-blake3-aes-256-gcm, chacha20-ietf-poly1305, 2022-blake3-chacha20-poly1305, xchacha20-ietf-poly1305.
+
Legacy stream cipher names recognized by the source (disabled in minimal builds;
some require backend support): table, rc4, 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, cast5-cfb, des-cfb, idea-cfb, rc2-cfb, seed-cfb, salsa20, chacha20, chacha20-ietf.
+
The '2022-blake3-*' ciphers implement Shadowsocks 2022 (SIP022). They require
a base64-encoded pre-shared key supplied with *-k*: 16 bytes for
2022-blake3-aes-128-gcm and 32 bytes for the other 2022 ciphers.
Generate a 32-byte key with `openssl rand -base64 32`.
Passwords are not stretched into keys for these ciphers.
-c <config_file>::
Use a JSON configuration file. The "port_password" field can start multiple ss-server instances.
-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.
Send outbound traffic through the specified network interface where supported by the platform.
-d <addr>::
Configure name servers for the internal c-ares DNS resolver. By default it uses the system resolver configuration.
-a <user_name>::
Run as a specific user.
-n <number>::
Specify the maximum number of open files. Requires a platform with setrlimit support.
-D <path>::
Set the working directory of ss-manager.
-6::
Resolve hostname to IPv6 address first.
-h::
Print help message.
-u::
Enable UDP relay.
Enable UDP relay.
-U::
Enable UDP relay and disable TCP relay.
-A::
Enable onetime authentication.
-v::
Enable verbose mode.
-d <addr>::
Setup name servers for internal DNS resolver (libc-ares).
The default server is fetched from `/etc/resolv.conf`.
-A::
Deprecated one-time authentication option. Exits with an error; use AEAD ciphers instead.
--fast-open::
Enable TCP fast open.
+
Only available with Linux kernel > 3.7.0.
Enable TCP Fast Open where supported by the operating system.
--no-delay::
Enable TCP_NODELAY.
--reuse-port::
Enable port reuse.
+
Only available with Linux kernel > 3.9.0.
Enable port reuse where supported by the operating system.
--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.
--manager-address <address>::
Set the manager control address: a UNIX domain socket path or an IP address and port.
--executable <path_to_server_executable>::
Specify the executable path of ss-server.
+
Only available in manager mode.
--executable <path>::
Set the executable path of ss-server used by ss-manager.
-D <path>::
--workdir <path>::
Specify the working directory of ss-manager.
+
Only available in manager mode.
--mtu <MTU>::
Specify the MTU of your network interface.
--plugin <plugin_name>::
Enable SIP003 plugin. (Experimental)
@@ -138,10 +131,13 @@ Enable SIP003 plugin. (Experimental)
--plugin-opts <plugin_options>::
Set SIP003 plugin options. (Experimental)
-v::
Enable verbose mode.
--password <password>::
Set the password. The server and the client should use the same password.
-h|--help::
--workdir <path>::
Set the working directory of ss-manager (alias for *-D*).
--help::
Print help message.
PROTOCOL
doc/ss-nat.asciidoc
+18 -10
View File
@@ -7,17 +7,17 @@ ss-nat - helper script to setup NAT rules for transparent proxy
SYNOPSIS
--------
*ss-nat*
[-ouUfh]
[-s <server_ip>] [-S <server_ip>] [-l <local_port>]
[-L <local_port>] [-i <ip_list_file>] [-a <lan_ips>]
[-b <wan_ips>] [-w <wan_ips>] [-e <extra_options>]
// Generated by scripts/gen_cli_docs.py from src/ss-nat; do not edit this section.
*ss-nat* [-s <server_ip>] [-l <local_port>] [-S <server_ip>] [-L <local_port>]
[-i <ip_list_file>] [-I <interface>] [-e <extra_options>] [-a <lan_ips>] [-b
<wan_ips>] [-w <wan_ips>] [-o] [-u] [-U] [-f] [-h]
DESCRIPTION
-----------
*Shadowsocks-libev* is a lightweight and secure socks5 proxy.
*shadowsocks-c* 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
*shadowsocks-c* is written in pure C and takes advantage of libuv to
achieve both high performance and low resource consumption.
`ss-nat`(1) sets up NAT rules for `ss-redir`(1) to provide traffic redirection.
@@ -27,6 +27,11 @@ For more information, check out `shadowsocks-libev`(8) and the following
OPTIONS
-------
// Generated by scripts/gen_cli_docs.py from src/ss-nat; do not edit this section.
This section lists options across supported builds. Platform and feature
restrictions are noted below; not every option is effective on every platform.
-s <server_ip>::
IP address of shadowsocks remote server
@@ -42,6 +47,12 @@ Port number of shadowsocks local UDP server
-i <ip_list_file>::
a file whose content is bypassed ip list
-I <interface>::
Set the LAN interface for NAT rules. The default is eth0.
-e <extra_options>::
Extra options for iptables
-a <lan_ips>::
LAN IP of access control, need a prefix to define access control mode
@@ -51,9 +62,6 @@ WAN IP of will be bypassed
-w <wan_ips>::
WAN IP of will be forwarded
-e <extra_options>::
Extra options for iptables
-o::
Apply the rules to the OUTPUT chain
doc/ss-redir.asciidoc
+73 -72
View File
@@ -3,27 +3,29 @@ ss-redir(1)
NAME
----
ss-redir - shadowsocks client as transparent proxy, libev port
ss-redir - shadowsocks client as transparent proxy, C implementation
SYNOPSIS
--------
*ss-redir*
[-uUv6] [-h|--help]
[-s <server_host>] [-p <server_port>] [-l <local_port>]
[-k <password>] [-m <encrypt_method>] [-f <pid_file>]
[-t <timeout>] [-c <config_file>] [-b <local_address>]
[-a <user_name>] [-n <nofile>] [--mtu <MTU>] [--no-delay]
[--plugin <plugin_name>] [--plugin-opts <plugin_options>]
[--password <password>] [--key <key_in_base64>]
// Generated by scripts/gen_cli_docs.py from src/redir.c; do not edit this section.
*ss-redir* [-f <pid_file>] [-s <server_host>] [-p <server_port>] [-l
<local_port>] [-k <password>] [-t <timeout>] [-m <encrypt_method>] [-c
<config_file>] [-b <local_address>] [-a <user_name>] [-n <number>] [-h] [-u]
[-U] [-T] [-v] [-6] [-A] [--fast-open] [--mtu <MTU>] [--mptcp] [--plugin
<plugin_name>] [--plugin-opts <plugin_options>] [--reuse-port]
[--tcp-incoming-sndbuf <size>] [--tcp-incoming-rcvbuf <size>]
[--tcp-outgoing-sndbuf <size>] [--tcp-outgoing-rcvbuf <size>] [--no-delay]
[--password <password>] [--key <key_in_base64>] [--help]
DESCRIPTION
-----------
*Shadowsocks-libev* is a lightweight and secure socks5 proxy.
*shadowsocks-c* 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
*shadowsocks-c* is written in pure C and takes advantage of libuv to
achieve both high performance and low resource consumption.
*Shadowsocks-libev* consists of five components.
*shadowsocks-c* consists of five components.
`ss-redir`(1) works as a transparent proxy on local machines to proxy TCP
traffic and requires netfilter's NAT module.
For more information, check out `shadowsocks-libev`(8) and the following
@@ -31,6 +33,14 @@ For more information, check out `shadowsocks-libev`(8) and the following
OPTIONS
-------
// Generated by scripts/gen_cli_docs.py from src/redir.c; do not edit this section.
This section lists options across supported builds. Platform and feature
restrictions are noted below; not every option is effective on every platform.
-f <pid_file>::
Start shadowsocks as a daemon with specific pid file.
-s <server_host>::
Set the server's hostname or IP.
@@ -41,75 +51,65 @@ Set the server's port number.
Set the local port number.
-k <password>::
--password <password>::
Set the password. The server and the client should use the same password.
--key <key_in_base64>::
Set the key directly. The key should be encoded with URL-safe Base64.
-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.
-m <encrypt_method>::
Set the cipher. The default is 'chacha20-ietf-poly1305'.
+
AEAD cipher names from the source (availability depends on the build):
aes-128-gcm, aes-192-gcm, aes-256-gcm, 2022-blake3-aes-128-gcm, 2022-blake3-aes-256-gcm, chacha20-ietf-poly1305, 2022-blake3-chacha20-poly1305, xchacha20-ietf-poly1305.
+
Legacy stream cipher names recognized by the source (disabled in minimal builds;
some require backend support): table, rc4, 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, cast5-cfb, des-cfb, idea-cfb, rc2-cfb, seed-cfb, salsa20, chacha20, chacha20-ietf.
+
The '2022-blake3-*' ciphers implement Shadowsocks 2022 (SIP022). They require
a base64-encoded pre-shared key supplied with *-k*: 16 bytes for
2022-blake3-aes-128-gcm and 32 bytes for the other 2022 ciphers.
Generate a 32-byte key with `openssl rand -base64 32`.
Passwords are not stretched into keys for these ciphers.
-c <config_file>::
Use a configuration file.
+
Refer to `shadowsocks-libev`(8) 'CONFIG FILE' section for more details.
-n <number>::
Specify max number of open files.
+
Only available on Linux.
Refer to `shadowsocks-c`(8) 'CONFIG FILE' section for more details.
-b <local_address>::
Specify the local address to use while this client is making outbound
Specify the local address to use while this client is making outbound
connections to the server.
-a <user_name>::
Run as a specific user.
-n <number>::
Specify the maximum number of open files. Requires a platform with setrlimit support.
-h::
Print help message.
-u::
Enable UDP relay.
+
TPROXY is required in redir mode. You may need root permission.
Enable UDP relay. Requires Linux TPROXY support and permission to configure transparent proxying.
-U::
Enable UDP relay and disable TCP relay.
-T::
Use tproxy instead of redirect. (for tcp)
Use TPROXY instead of REDIRECT for TCP traffic. Requires Linux TPROXY support.
-v::
Enable verbose mode.
-6::
Resolve hostname to IPv6 address first.
-A::
Deprecated one-time authentication option. Exits with an error; use AEAD ciphers instead.
--fast-open::
Enable TCP Fast Open where supported by the operating system.
--mtu <MTU>::
Specify the MTU of your network interface.
@@ -118,13 +118,14 @@ Enable Multipath TCP.
+
Only available with MPTCP enabled Linux kernel.
--reuse-port::
Enable port reuse.
+
Only available with Linux kernel > 3.9.0.
--plugin <plugin_name>::
Enable SIP003 plugin. (Experimental)
--no-delay::
Enable TCP_NODELAY.
--plugin-opts <plugin_options>::
Set SIP003 plugin options. (Experimental)
--reuse-port::
Enable port reuse where supported by the operating system.
--tcp-incoming-sndbuf <size>::
Set TCP send buffer size for incoming connections.
@@ -138,16 +139,16 @@ Set TCP send buffer size for outgoing connections.
--tcp-outgoing-rcvbuf <size>::
Set TCP receive buffer size for outgoing connections.
--plugin <plugin_name>::
Enable SIP003 plugin. (Experimental)
--no-delay::
Enable TCP_NODELAY.
--plugin-opts <plugin_options>::
Set SIP003 plugin options. (Experimental)
--password <password>::
Set the password. The server and the client should use the same password.
-v::
Enable verbose mode.
--key <key_in_base64>::
Set the key directly. The key should be encoded with URL-safe Base64.
-h|--help::
--help::
Print help message.
EXAMPLE
doc/ss-server.asciidoc
+87 -93
View File
@@ -3,103 +3,95 @@ ss-server(1)
NAME
----
ss-server - shadowsocks server, libev port
ss-server - shadowsocks server, C implementation
SYNOPSIS
--------
*ss-server*
[-uUv] [-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>]
[-a <user_name>] [-d <addr>] [-n <nofile>]
[-b <local_address>] [--fast-open] [--reuse-port]
[--mptcp] [--acl <acl_config>] [--mtu <MTU>] [--no-delay]
[--manager-address <path_to_unix_domain>]
[--plugin <plugin_name>] [--plugin-opts <plugin_options>]
[--password <password>] [--key <key_in_base64>]
// Generated by scripts/gen_cli_docs.py from src/server.c; do not edit this section.
*ss-server* [-f <pid_file>] [-s <server_host>] [-p <server_port>] [-l
<local_port>] [-k <password>] [-t <timeout>] [-m <encrypt_method>] [-b
<local_address>] [-c <config_file>] [-i <interface>] [-d <addr>] [-a
<user_name>] [-n <number>] [-h] [-u] [-U] [-v] [-6] [-A] [--fast-open]
[--reuse-port] [--tcp-incoming-sndbuf <size>] [--tcp-incoming-rcvbuf <size>]
[--tcp-outgoing-sndbuf <size>] [--tcp-outgoing-rcvbuf <size>] [--no-delay]
[--acl <acl_config>] [--manager-address <address>] [--mtu <MTU>] [--help]
[--plugin <plugin_name>] [--plugin-opts <plugin_options>] [--password
<password>] [--key <key_in_base64>] [--mptcp] [--nftables-sets <sets>]
DESCRIPTION
-----------
*Shadowsocks-libev* is a lightweight and secure socks5 proxy.
*shadowsocks-c* 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
*shadowsocks-c* is written in pure C and takes advantage of libuv to
achieve both high performance and low resource consumption.
*Shadowsocks-libev* consists of five components.
*shadowsocks-c* consists of five components.
`ss-server`(1) runs on a remote server to provide secured tunnel service.
For more information, check out `shadowsocks-libev`(8).
OPTIONS
-------
-s <server_host>::
Set the server's hostname or IP.
// Generated by scripts/gen_cli_docs.py from src/server.c; do not edit this section.
-p <server_port>::
Set the server's port number.
-k <password>::
--password <password>::
Set the password. The server and the client should use the same password.
--key <key_in_base64>::
Set the key directly. The key should be encoded with URL-safe Base64.
-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 '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.
This section lists options across supported builds. Platform and feature
restrictions are noted below; not every option is effective on every platform.
-f <pid_file>::
Start shadowsocks as a daemon with specific pid file.
-s <server_host>::
Set a server listening hostname or IP address. May be repeated.
-p <server_port>::
Set the server listening port.
-l <local_port>::
Accepted for compatibility but ignored by this program; it does not configure a local listener.
-k <password>::
Set the password. The server and the client should use the same password.
-t <timeout>::
Set the socket timeout in seconds. The default value is 60.
-m <encrypt_method>::
Set the cipher. The default is 'chacha20-ietf-poly1305'.
+
AEAD cipher names from the source (availability depends on the build):
aes-128-gcm, aes-192-gcm, aes-256-gcm, 2022-blake3-aes-128-gcm, 2022-blake3-aes-256-gcm, chacha20-ietf-poly1305, 2022-blake3-chacha20-poly1305, xchacha20-ietf-poly1305.
+
Legacy stream cipher names recognized by the source (disabled in minimal builds;
some require backend support): table, rc4, 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, cast5-cfb, des-cfb, idea-cfb, rc2-cfb, seed-cfb, salsa20, chacha20, chacha20-ietf.
+
The '2022-blake3-*' ciphers implement Shadowsocks 2022 (SIP022). They require
a base64-encoded pre-shared key supplied with *-k*: 16 bytes for
2022-blake3-aes-128-gcm and 32 bytes for the other 2022 ciphers.
Generate a 32-byte key with `openssl rand -base64 32`.
Passwords are not stretched into keys for these ciphers.
-b <local_address>::
Set the local address for outbound connections to destination servers.
-c <config_file>::
Use a configuration file.
+
Refer to `shadowsocks-libev`(8) 'CONFIG FILE' section for more details.
-n <number>::
Specify max number of open files.
+
Only available on Linux.
Refer to `shadowsocks-c`(8) 'CONFIG FILE' section for more details.
-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-server` 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.
Send outbound traffic through the specified network interface where supported by the platform.
-b <local_address>::
Specify the local address to use while this server is making outbound
connections to remote servers on behalf of the clients.
-d <addr>::
Configure name servers for the internal c-ares DNS resolver. By default it uses the system resolver configuration.
-a <user_name>::
Run as a specific user.
-n <number>::
Specify the maximum number of open files. Requires a platform with setrlimit support.
-h::
Print help message.
-u::
Enable UDP relay.
@@ -107,25 +99,20 @@ Enable UDP relay.
-U::
Enable UDP relay and disable TCP relay.
-v::
Enable verbose mode.
-6::
Resolve hostname to IPv6 address first.
-d <addr>::
Setup name servers for internal DNS resolver (libc-ares).
The default server is fetched from '/etc/resolv.conf'.
-A::
Deprecated one-time authentication option. Exits with an error; use AEAD ciphers instead.
--fast-open::
Enable TCP fast open.
+
Only available with Linux kernel > 3.7.0.
Enable TCP Fast Open where supported by the operating system.
--reuse-port::
Enable port reuse.
+
Only available with Linux kernel > 3.9.0.
--no-delay::
Enable TCP_NODELAY.
Enable port reuse where supported by the operating system.
--tcp-incoming-sndbuf <size>::
Set TCP send buffer size for incoming connections.
@@ -139,21 +126,20 @@ Set TCP send buffer size for outgoing connections.
--tcp-outgoing-rcvbuf <size>::
Set TCP receive buffer size for outgoing connections.
--no-delay::
Enable TCP_NODELAY.
--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.
--manager-address <address>::
Set the manager control address: a UNIX domain socket path or an IP address and port.
--mtu <MTU>::
Specify the MTU of your network interface.
--mptcp::
Enable Multipath TCP.
+
Only available with MPTCP enabled Linux kernel.
--help::
Print help message.
--plugin <plugin_name>::
Enable SIP003 plugin. (Experimental)
@@ -161,11 +147,19 @@ Enable SIP003 plugin. (Experimental)
--plugin-opts <plugin_options>::
Set SIP003 plugin options. (Experimental)
-v::
Enable verbose mode.
--password <password>::
Set the password. The server and the client should use the same password.
-h|--help::
Print help message.
--key <key_in_base64>::
Set the key directly. The key should be encoded with URL-safe Base64.
--mptcp::
Enable Multipath TCP.
+
Only available with MPTCP enabled Linux kernel.
--nftables-sets <sets>::
Linux builds with USE_NFTABLES only: add malicious IP addresses to nftables sets. Format: `[<table1>:]<set1>[,[<table2>:]<set2>...]`.
EXAMPLE
-------
doc/ss-tunnel.asciidoc
+81 -83
View File
@@ -3,34 +3,44 @@ ss-tunnel(1)
NAME
----
ss-tunnel - shadowsocks tools for local port forwarding, libev port
ss-tunnel - shadowsocks tools for local port forwarding, C implementation
SYNOPSIS
--------
*ss-tunnel*
[-uUv6] [-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_address>] [-a <user_name>] [-n <nofile>]
[-L addr:port] [--mtu <MTU>] [--mptcp] [--reuse-port] [--no-delay]
[--plugin <plugin_name>] [--plugin-opts <plugin_options>]
[--key <key_in_base64>]
// Generated by scripts/gen_cli_docs.py from src/tunnel.c; do not edit this section.
*ss-tunnel* [-f <pid_file>] [-s <server_host>] [-p <server_port>] [-l
<local_port>] [-k <password>] [-t <timeout>] [-m <encrypt_method>] [-i
<interface>] [-c <config_file>] [-b <local_address>] [-L <addr:port>] [-a
<user_name>] [-n <number>] [-h] [-u] [-U] [-v] [-V] [-6] [-A] [--fast-open]
[--mtu <MTU>] [--no-delay] [--mptcp] [--plugin <plugin_name>] [--plugin-opts
<plugin_options>] [--reuse-port] [--tcp-incoming-sndbuf <size>]
[--tcp-incoming-rcvbuf <size>] [--tcp-outgoing-sndbuf <size>]
[--tcp-outgoing-rcvbuf <size>] [--password <password>] [--key
<key_in_base64>] [--help]
DESCRIPTION
-----------
*Shadowsocks-libev* is a lightweight and secure socks5 proxy.
*shadowsocks-c* 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
*shadowsocks-c* is written in pure C and takes advantage of libuv to
achieve both high performance and low resource consumption.
*Shadowsocks-libev* consists of five components.
*shadowsocks-c* consists of five components.
`ss-tunnel`(1) is a tool for local port forwarding.
See 'OPTIONS' section for special option needed by `ss-tunnel`(1).
For more information, check out `shadowsocks-libev`(8).
OPTIONS
-------
// Generated by scripts/gen_cli_docs.py from src/tunnel.c; do not edit this section.
This section lists options across supported builds. Platform and feature
restrictions are noted below; not every option is effective on every platform.
-f <pid_file>::
Start shadowsocks as a daemon with specific pid file.
-s <server_host>::
Set the server's hostname or IP.
@@ -41,99 +51,90 @@ Set the server's port number.
Set the local port number.
-k <password>::
--password <password>::
Set the password. The server and the client should use the same password.
--key <key_in_base64>::
Set the key directly. The key should be encoded with URL-safe Base64.
-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.
-m <encrypt_method>::
Set the cipher. The default is 'chacha20-ietf-poly1305'.
+
AEAD cipher names from the source (availability depends on the build):
aes-128-gcm, aes-192-gcm, aes-256-gcm, 2022-blake3-aes-128-gcm, 2022-blake3-aes-256-gcm, chacha20-ietf-poly1305, 2022-blake3-chacha20-poly1305, xchacha20-ietf-poly1305.
+
Legacy stream cipher names recognized by the source (disabled in minimal builds;
some require backend support): table, rc4, 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, cast5-cfb, des-cfb, idea-cfb, rc2-cfb, seed-cfb, salsa20, chacha20, chacha20-ietf.
+
The '2022-blake3-*' ciphers implement Shadowsocks 2022 (SIP022). They require
a base64-encoded pre-shared key supplied with *-k*: 16 bytes for
2022-blake3-aes-128-gcm and 32 bytes for the other 2022 ciphers.
Generate a 32-byte key with `openssl rand -base64 32`.
Passwords are not stretched into keys for these ciphers.
-i <interface>::
Send outbound traffic through the specified network interface where supported by the platform.
-c <config_file>::
Use a configuration file.
+
Refer to `shadowsocks-libev`(8) 'CONFIG FILE' section for more details.
-n <number>::
Specify max number of open files.
+
Only available on Linux.
-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-tunnel` 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.
Refer to `shadowsocks-c`(8) 'CONFIG FILE' section for more details.
-b <local_address>::
Specify the local address to use while this client is making outbound
Specify the local address to use while this client is making outbound
connections to the server.
-L <addr:port>::
Destination server address and port for local port forwarding.
-a <user_name>::
Run as a specific user.
-n <number>::
Specify the maximum number of open files. Requires a platform with setrlimit support.
-h::
Print help message.
-u::
Enable UDP relay.
-U::
Enable UDP relay and disable TCP relay.
-v::
Enable verbose mode.
-V::
Android only: enable VPN socket protection.
-6::
Resolve hostname to IPv6 address first.
-L <addr:port>::
Specify destination server address and port for local port forwarding.
+
Only used and available in tunnel mode.
-A::
Deprecated one-time authentication option. Exits with an error; use AEAD ciphers instead.
--fast-open::
Enable TCP Fast Open where supported by the operating system.
--mtu <MTU>::
Specify the MTU of your network interface.
--no-delay::
Enable TCP_NODELAY.
--mptcp::
Enable Multipath TCP.
+
Only available with MPTCP enabled Linux kernel.
--reuse-port::
Enable port reuse.
+
Only available with Linux kernel > 3.9.0.
--plugin <plugin_name>::
Enable SIP003 plugin. (Experimental)
--no-delay::
Enable TCP_NODELAY.
--plugin-opts <plugin_options>::
Set SIP003 plugin options. (Experimental)
--reuse-port::
Enable port reuse where supported by the operating system.
--tcp-incoming-sndbuf <size>::
Set TCP send buffer size for incoming connections.
@@ -147,16 +148,13 @@ Set TCP send buffer size for outgoing connections.
--tcp-outgoing-rcvbuf <size>::
Set TCP receive buffer size for outgoing connections.
--plugin <plugin_name>::
Enable SIP003 plugin. (Experimental)
--password <password>::
Set the password. The server and the client should use the same password.
--plugin-opts <plugin_options>::
Set SIP003 plugin options. (Experimental)
--key <key_in_base64>::
Set the key directly. The key should be encoded with URL-safe Base64.
-v::
Enable verbose mode.
-h|--help::
--help::
Print help message.
EXAMPLE
scripts/gen_cli_docs.py
+194
View File
@@ -0,0 +1,194 @@
#!/usr/bin/env python3
"""Generate man-page CLI sections from getopt declarations and CLI_DOC comments.
This intentionally parses a small, checked subset of C, not arbitrary expressions.
Unsupported parser declarations fail instead of silently dropping options. Source
is read without preprocessing so cross-builds document all platform variants.
"""
import argparse
from pathlib import Path
import re
import sys
import textwrap
ROOT = Path(__file__).resolve().parents[1]
PROGRAMS = ("local", "server", "tunnel", "redir", "manager", "nat")
C_COMMENT = re.compile(r'/\*.*?\*/|//[^\n]*', re.S)
TERM = re.compile(r'(-{1,2}[A-Za-z0-9][A-Za-z0-9-]*)(?: (<[^>]+>))?::')
def descriptions(source):
blocks = re.findall(r'/\* CLI_DOC\n(.*?)\*/', source, re.S)
for block in re.findall(r'^# CLI_DOC\n(.*?)^# END_CLI_DOC$', source, re.M | re.S):
blocks.append(re.sub(r'^# ?', '', block, flags=re.M))
result = {}
for block in blocks:
for entry in re.split(r'\n\s*\n(?=-)', block.strip()):
term, separator, body = entry.partition('\n')
match = TERM.fullmatch(term)
if not match or not separator or not body.strip():
raise ValueError(f"Invalid CLI_DOC entry: {term}")
flag, argument = match.groups()
if flag in result:
raise ValueError(f"Duplicate CLI_DOC entry: {flag}")
result[flag] = (argument, body.strip())
return result
def short_options(spec):
result = {}
spec = spec.lstrip(':+-')
while spec:
match = re.match(r'([A-Za-z0-9])(:?)', spec)
if not match:
raise ValueError(f"Unsupported getopt string: {spec}")
flag, argument = match.groups()
if '-' + flag in result:
raise ValueError(f"Duplicate short option: {flag}")
result['-' + flag] = bool(argument)
spec = spec[match.end():]
return result
def options(source, shell=False):
result = {}
if shell:
specs = re.findall(r'^while getopts "([^"]+)" \w+; do$', source, re.M)
if len(specs) != 1:
raise ValueError("Expected one literal shell getopts declaration")
else:
source = C_COMMENT.sub('', source)
specs = re.findall(r'getopt_long\(argc,\s*argv,\s*"([^"]+)"\s*,\s*long_options,\s*NULL\)', source)
if not specs or len(specs) != len(re.findall(r'\bgetopt_long\s*\(', source)):
raise ValueError("Expected literal getopt_long declarations")
for spec in specs:
for flag, argument in short_options(spec).items():
if flag in result and result[flag] != argument:
raise ValueError(f"Inconsistent argument across platform variants: {flag}")
result[flag] = argument
if shell:
return result
tables = re.findall(r'static struct option long_options\[\]\s*=\s*\{(.*?)\};', source, re.S)
if len(tables) != 1:
raise ValueError("Expected one long_options table")
table = re.sub(r'^\s*#.*$', '', tables[0], flags=re.M)
entry = re.compile(r'\{\s*"([a-z0-9-]+)"\s*,\s*(no_argument|required_argument)\s*,\s*NULL\s*,\s*GETOPT_VAL_[A-Z0-9_]+\s*\}\s*,', re.S)
for match in entry.finditer(table):
flag, argument = match.groups()
if '--' + flag in result:
raise ValueError(f"Duplicate long option: {flag}")
result['--' + flag] = argument == 'required_argument'
remainder = entry.sub('', table)
if not re.fullmatch(r'\s*\{\s*NULL\s*,\s*0\s*,\s*NULL\s*,\s*0\s*\}\s*', remainder):
raise ValueError(f"Unsupported long_options entry: {remainder.strip()}")
return result
def cipher_names(root, kind):
source = C_COMMENT.sub('', (root / f'src/{kind}.c').read_text())
match = re.search(r'const char \*supported_' + kind + r'_ciphers\[[^]]+\]\s*=\s*\{(.*?)\};', source, re.S)
if not match:
raise ValueError(f"Missing {kind} cipher table")
table = re.sub(r'^\s*#.*$', '', match[1], flags=re.M)
names = re.findall(r'"([a-z0-9-]+)"', table)
if not names or re.sub(r'"[a-z0-9-]+"|[\s,]', '', table):
raise ValueError(f"Unsupported {kind} cipher table")
return ', '.join(names)
def sections(program, declared, docs):
missing = declared.keys() - docs.keys()
if missing:
raise ValueError(f"{program}: missing CLI_DOC descriptions: {', '.join(sorted(missing))}")
synopsis = [f'*{program}*']
entries = []
for flag, takes_argument in declared.items():
argument, body = docs[flag]
if bool(argument) != takes_argument:
raise ValueError(f"{program}: argument mismatch for {flag}")
term = flag + (' ' + argument if argument else '')
synopsis.append(f'[{term}]')
entries.append(f'{term}::\n{body}')
return (textwrap.fill(' '.join(synopsis), width=78, subsequent_indent=' ',
break_long_words=False, break_on_hyphens=False),
'\n\n'.join(entries))
def replace_section(document, heading, body):
pattern = re.compile(r'(^' + heading + r'\n-+\n).*?(?=^[A-Z][A-Z /-]*\n-+\n|\Z)', re.M | re.S)
document, count = pattern.subn(lambda m: m[1] + body + '\n\n', document)
if count != 1:
raise ValueError(f"Expected one {heading} section")
return document
def generate(root):
shared = descriptions((root / 'src/utils.c').read_text())
replacements = {f'{{cli-{kind}-ciphers}}': cipher_names(root, kind)
for kind in ('aead', 'stream')}
result = {}
all_options = set()
summary = []
for module in PROGRAMS:
program = 'ss-' + module
path = 'src/ss-nat' if module == 'nat' else f'src/{module}.c'
source = (root / path).read_text()
declared = options(source, shell=module == 'nat')
local = descriptions(source)
if local.keys() - declared.keys():
raise ValueError(f"{program}: stale CLI_DOC descriptions: {local.keys() - declared.keys()}")
docs = local if module == 'nat' else {**shared, **local}
if module != 'nat':
all_options.update(declared)
synopsis, body = sections(program, declared, docs)
note = (f'// Generated by scripts/gen_cli_docs.py from {path}; do not edit this section.\n\n')
document = (root / f'doc/{program}.asciidoc').read_text()
document = replace_section(document, 'SYNOPSIS', note + synopsis)
body = ('This section lists options across supported builds. Platform and feature\n'
'restrictions are noted below; not every option is effective on every platform.\n\n' + body)
document = replace_section(document, 'OPTIONS', note + body)
for key, value in replacements.items():
document = document.replace(key, value)
result[f'{program}.asciidoc'] = document
summary.append(f'`{program}`(1)::\nSee this command\'s generated SYNOPSIS and OPTIONS for its accepted arguments.')
if shared.keys() - all_options:
raise ValueError(f"Stale shared CLI_DOC descriptions: {shared.keys() - all_options}")
document = (root / 'doc/shadowsocks-c.asciidoc').read_text()
note = '// Generated by scripts/gen_cli_docs.py; do not edit this section.\n\n'
document = replace_section(document, 'SYNOPSIS', note + '\n\n'.join(f'*ss-{p}* [options]' for p in PROGRAMS))
document = replace_section(document, 'OPTIONS', note + '\n\n'.join(summary))
result['shadowsocks-c.asciidoc'] = document
return result
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--root', type=Path, default=ROOT)
mode = parser.add_mutually_exclusive_group()
mode.add_argument('--check', action='store_true', help='fail if checked-in pages are stale')
mode.add_argument('--output-dir', type=Path, help='write assembled pages here instead of doc/')
args = parser.parse_args()
try:
generated = generate(args.root)
if args.check:
stale = [name for name, text in generated.items()
if (args.root / 'doc' / name).read_text() != text]
if stale:
raise ValueError('Stale CLI docs: ' + ', '.join(stale) +
'; run python3 scripts/gen_cli_docs.py')
else:
output = args.output_dir or args.root / 'doc'
output.mkdir(parents=True, exist_ok=True)
for name, text in generated.items():
path = output / name
if not path.exists() or path.read_text() != text:
path.write_text(text)
except (ValueError, OSError) as error:
parser.exit(1, f'{error}\n')
return 0
if __name__ == '__main__':
sys.exit(main())
src/manager.c
+10
View File
@@ -1271,6 +1271,16 @@ main(int argc, char **argv)
jconf_t *conf = NULL;
/* CLI_DOC
-s <server_host>::
Set a server listening hostname or IP address. May be repeated.
-l <local_port>::
Accepted for compatibility but ignored by this program; it does not configure a local listener.
-c <config_file>::
Use a JSON configuration file. The "port_password" field can start multiple ss-server instances.
*/
static struct option long_options[] = {
{ "fast-open", no_argument, NULL, GETOPT_VAL_FAST_OPEN },
{ "no-delay", no_argument, NULL, GETOPT_VAL_NODELAY },
src/redir.c
+4
View File
@@ -922,6 +922,10 @@ main(int argc, char **argv)
memset(remote_addr, 0, sizeof(ss_addr_t) * MAX_REMOTE_NUM);
/* CLI_DOC
-u::
Enable UDP relay. Requires Linux TPROXY support and permission to configure transparent proxying.
*/
static struct option long_options[] = {
{ "fast-open", no_argument, NULL, GETOPT_VAL_FAST_OPEN },
{ "mtu", required_argument, NULL, GETOPT_VAL_MTU },
src/server.c
+13
View File
@@ -1838,6 +1838,19 @@ main(int argc, char **argv)
memset(&local_addr_v4, 0, sizeof(struct sockaddr_storage));
memset(&local_addr_v6, 0, sizeof(struct sockaddr_storage));
/* CLI_DOC
-s <server_host>::
Set a server listening hostname or IP address. May be repeated.
-l <local_port>::
Accepted for compatibility but ignored by this program; it does not configure a local listener.
-p <server_port>::
Set the server listening port.
-b <local_address>::
Set the local address for outbound connections to destination servers.
*/
static struct option long_options[] = {
{ "fast-open", no_argument, NULL, GETOPT_VAL_FAST_OPEN },
{ "reuse-port", no_argument, NULL, GETOPT_VAL_REUSE_PORT },
src/ss-nat
+46
View File
@@ -168,6 +168,52 @@ EOF
return $?
}
# CLI_DOC
# -s <server_ip>::
# IP address of shadowsocks remote server
#
# -l <local_port>::
# Port number of shadowsocks local server
#
# -S <server_ip>::
# IP address of shadowsocks remote UDP server
#
# -L <local_port>::
# Port number of shadowsocks local UDP server
#
# -i <ip_list_file>::
# a file whose content is bypassed ip list
#
# -a <lan_ips>::
# LAN IP of access control, need a prefix to define access control mode
#
# -b <wan_ips>::
# WAN IP of will be bypassed
#
# -w <wan_ips>::
# WAN IP of will be forwarded
#
# -e <extra_options>::
# Extra options for iptables
#
# -o::
# Apply the rules to the OUTPUT chain
#
# -u::
# Enable udprelay mode, TPROXY is required
#
# -U::
# Enable udprelay mode, using different IP and ports for TCP and UDP
#
# -f::
# Flush the rules
#
# -h::
# Show this help message and exit
#
# -I <interface>::
# Set the LAN interface for NAT rules. The default is eth0.
# END_CLI_DOC
while getopts ":s:l:S:L:i:I:e:a:b:w:ouUfh" arg; do
case "$arg" in
s)
src/utils.c
+156
View File
@@ -317,6 +317,162 @@ ss_is_ipv6addr(const char *addr)
return strcmp(addr, ":") > 0;
}
/* CLI_DOC
-s <server_host>::
Set the server's hostname or IP.
-p <server_port>::
Set the server's port number.
-l <local_port>::
Set the local port number.
-k <password>::
Set the password. The server and the client should use the same password.
--password <password>::
Set the password. The server and the client should use the same password.
--key <key_in_base64>::
Set the key directly. The key should be encoded with URL-safe Base64.
--server-url <ss_url>::
Take the server address, port, cipher, password and any SIP003 plugin
from a single 'ss://' URL, as produced by most clients and by
*shadowsocks-rust*'s `ssurl`. Both the SIP002 form
('ss://base64(method:password)@host:port/?plugin=...#tag') and the older
'ss://base64(method:password@host:port)' form are accepted. Options given
later on the command line override the values taken from the URL.
-m <encrypt_method>::
Set the cipher. The default is 'chacha20-ietf-poly1305'.
+
AEAD cipher names from the source (availability depends on the build):
{cli-aead-ciphers}.
+
Legacy stream cipher names recognized by the source (disabled in minimal builds;
some require backend support): {cli-stream-ciphers}.
+
The '2022-blake3-*' ciphers implement Shadowsocks 2022 (SIP022). They require
a base64-encoded pre-shared key supplied with *-k*: 16 bytes for
2022-blake3-aes-128-gcm and 32 bytes for the other 2022 ciphers.
Generate a 32-byte key with `openssl rand -base64 32`.
Passwords are not stretched into keys for these ciphers.
-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.
+
Refer to `shadowsocks-c`(8) 'CONFIG FILE' section for more details.
-n <number>::
Specify the maximum number of open files. Requires a platform with setrlimit support.
-i <interface>::
Send outbound traffic through the specified network interface where supported by the platform.
-b <local_address>::
Specify the local address to use while this client is making outbound
connections to the server.
-u::
Enable UDP relay.
-U::
Enable UDP relay and disable TCP relay.
-6::
Resolve hostname to IPv6 address first.
--fast-open::
Enable TCP Fast Open where supported by the operating system.
--reuse-port::
Enable port reuse where supported by the operating system.
--acl <acl_config>::
Enable ACL (Access Control List) and specify config file.
--mtu <MTU>::
Specify the MTU of your network interface.
--mptcp::
Enable Multipath TCP.
+
Only available with MPTCP enabled Linux kernel.
--no-delay::
Enable TCP_NODELAY.
--tcp-incoming-sndbuf <size>::
Set TCP send buffer size for incoming connections.
--tcp-incoming-rcvbuf <size>::
Set TCP receive buffer size for incoming connections.
--tcp-outgoing-sndbuf <size>::
Set TCP send buffer size for outgoing connections.
--tcp-outgoing-rcvbuf <size>::
Set TCP receive buffer size for outgoing connections.
--plugin <plugin_name>::
Enable SIP003 plugin. (Experimental)
--plugin-opts <plugin_options>::
Set SIP003 plugin options. (Experimental)
-v::
Enable verbose mode.
-h::
Print help message.
--help::
Print help message.
-A::
Deprecated one-time authentication option. Exits with an error; use AEAD ciphers instead.
-S <path>::
Android only: UNIX socket path for traffic statistics.
-V::
Android only: enable VPN socket protection.
-L <addr:port>::
Destination server address and port for local port forwarding.
-T::
Use TPROXY instead of REDIRECT for TCP traffic. Requires Linux TPROXY support.
-d <addr>::
Configure name servers for the internal c-ares DNS resolver. By default it uses the system resolver configuration.
-D <path>::
Set the working directory of ss-manager.
--workdir <path>::
Set the working directory of ss-manager (alias for *-D*).
--manager-address <address>::
Set the manager control address: a UNIX domain socket path or an IP address and port.
--executable <path>::
Set the executable path of ss-server used by ss-manager.
--nftables-sets <sets>::
Linux builds with USE_NFTABLES only: add malicious IP addresses to nftables sets. Format: `[<table1>:]<set1>[,[<table2>:]<set2>...]`.
*/
void
usage()
{
tests/test_gen_cli_docs.py
+107
View File
@@ -0,0 +1,107 @@
"""Regression checks for parser/documentation drift and cross-platform extraction."""
import importlib.util
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile
import unittest
ROOT = Path(__file__).resolve().parents[1]
SPEC = importlib.util.spec_from_file_location('gen_cli_docs', ROOT / 'scripts/gen_cli_docs.py')
GEN = importlib.util.module_from_spec(SPEC)
SPEC.loader.exec_module(GEN)
class CliDocsTests(unittest.TestCase):
def setUp(self):
self.temp = tempfile.TemporaryDirectory()
self.addCleanup(self.temp.cleanup)
self.root = Path(self.temp.name)
for directory in ('src', 'doc'):
(self.root / directory).mkdir()
for name in ('utils.c', 'local.c', 'server.c', 'tunnel.c', 'redir.c',
'manager.c', 'ss-nat', 'aead.c', 'stream.c'):
shutil.copyfile(ROOT / 'src' / name, self.root / 'src' / name)
for path in (ROOT / 'doc').glob('*.asciidoc'):
shutil.copyfile(path, self.root / 'doc' / path.name)
def change(self, filename, old, new):
path = self.root / filename
source = path.read_text()
self.assertIn(old, source)
path.write_text(source.replace(old, new))
def test_checked_in_pages_and_idempotence(self):
generated = GEN.generate(self.root)
self.assertEqual(len(generated), 7)
for name, text in generated.items():
self.assertEqual(text, (self.root / 'doc' / name).read_text())
(self.root / 'doc' / name).write_text(text)
self.assertEqual(generated, GEN.generate(self.root))
def test_platform_options_aliases_and_program_specific_flags(self):
pages = GEN.generate(self.root)
self.assertIn('-S <path>::\nAndroid only', pages['ss-local.asciidoc'])
self.assertIn('-V::\nAndroid only', pages['ss-tunnel.asciidoc'])
self.assertIn('--nftables-sets <sets>::\nLinux builds', pages['ss-server.asciidoc'])
self.assertIn('-I <interface>::', pages['ss-nat.asciidoc'])
self.assertIn('--password <password>::', pages['ss-tunnel.asciidoc'])
self.assertIn('--workdir <path>::', pages['ss-manager.asciidoc'])
self.assertNotIn('[-p ', pages['ss-manager.asciidoc'])
self.assertNotIn('--tcp-incoming-sndbuf', pages['ss-manager.asciidoc'])
self.assertIn('-A::\nDeprecated', pages['ss-manager.asciidoc'])
def test_new_option_requires_description(self):
self.change('src/local.c', '"reuse-port",', '"new-option",')
with self.assertRaisesRegex(ValueError, 'missing CLI_DOC.*new-option'):
GEN.generate(self.root)
def test_argument_arity_is_checked(self):
self.change('src/local.c', '"reuse-port", no_argument',
'"reuse-port", required_argument')
with self.assertRaisesRegex(ValueError, 'argument mismatch.*reuse-port'):
GEN.generate(self.root)
def test_unknown_table_syntax_fails_closed(self):
self.change('src/local.c', '"reuse-port", no_argument',
'"reuse-port", optional_argument')
with self.assertRaisesRegex(ValueError, 'Unsupported long_options'):
GEN.generate(self.root)
def test_nonliteral_short_options_fail_closed(self):
self.change('src/local.c', '"f:s:p:l:k:t:m:i:c:b:a:n:huUv6A"', 'SHORT_OPTIONS')
with self.assertRaisesRegex(ValueError, 'literal getopt_long'):
GEN.generate(self.root)
def test_shell_arity_and_new_flags(self):
self.change('src/ss-nat', ':s:l:S:L:i:I:e:a:b:w:ouUfh', ':s:l:S:L:i:I:e:a:b:w:ouUfhz')
with self.assertRaisesRegex(ValueError, 'missing CLI_DOC.*-z'):
GEN.generate(self.root)
def test_stale_override_is_rejected(self):
self.change('src/server.c', '-p <server_port>::', '--unused <server_port>::')
with self.assertRaisesRegex(ValueError, 'stale CLI_DOC'):
GEN.generate(self.root)
def test_cipher_table_changes_propagate(self):
self.change('src/aead.c', '"aes-128-gcm",', '"new-aead-cipher",')
self.assertIn('new-aead-cipher', GEN.generate(self.root)['ss-local.asciidoc'])
def test_check_detects_stale_docs_and_build_output_preserves_source(self):
self.change('doc/ss-local.asciidoc', '--mtu <MTU>::', '--mtu <WRONG>::')
command = [sys.executable, str(ROOT / 'scripts/gen_cli_docs.py'),
'--root', str(self.root)]
checked = subprocess.run(command + ['--check'], capture_output=True, text=True)
self.assertNotEqual(checked.returncode, 0)
self.assertIn('Stale CLI docs', checked.stderr)
output = self.root / 'generated'
subprocess.run(command + ['--output-dir', str(output)], check=True)
self.assertIn('--mtu <MTU>::', (output / 'ss-local.asciidoc').read_text())
self.assertIn('--mtu <WRONG>::', (self.root / 'doc/ss-local.asciidoc').read_text())
if __name__ == '__main__':
unittest.main()