Skip to content

How to Run

Jump to bottom
ihc童鞋@提不起劲 edited this page Mar 9, 2023 · 10 revisions

Supported Platforms

We support Linux and MacOS now(including android). On windows you can use our implementation via WSL.

Also, you can try other implementations like sing-box.

Comparing to other implementations, we can provide best performance(on Linux and MacOS) and newest features.

How to Run

There are 2 ways to run, run with docker or run binary directly.

Parameters

Global parameters(shadow-tls --help):

  • -t, --threads <THREADS>: (optional)Set thread count manually. Normally you don't have to set it.
  • -d, --disable-nodelay: (optional)Disable TCP_NODELAY. Unless you know what you are doing, do not use this parameter.
  • --v3: (optional)Enable V3 protocol. If you enable it, it must be enabled on both sides. On next major version, this parameter will be removed, and v3 will be enabled by default.

Client Mode(shadow-tls client --help):

  • --listen <LISTEN>: Listen address(with port). Usually this port is used by shadowsocks client.
  • --server <SERVER_ADDR>: ShadowTLS server address(with port).
  • --sni <TLS_NAMES>: SNI list. You can provide multiple SNIs like captive.apple.com;cloud.tencent.com. Different SNIs are seprated by ;.
  • --password <PASSWORD>: Must be the same as the ShadowTLS server.
  • --alpn <ALPN>: (optional)Set ALPN ext. You can set multiple ALPN seprated by ;. Unless you know what you are doing, do not use this parameter.

Server Mode(shadow-tls server --help):

  • --listen <LISTEN>: Listen address(with port).
  • --server <SERVER_ADDR>: Data server address(with port). Usually this port is listened by shadowsocks server.
  • --tls <TLS_ADDR>: TLS names. There must be a fallback server name at the last, and there can be multiple mappings. Mappings can be represented as ServerName:Host:Port. Host can be omitted, in this case ServerName is used as Host. Port can be omitted too, which is 443 by default. Parts are seprated by ;. For example, all of these are valid: cloud.tencent.com, cloud.tencent.com:443, cloudflare.com:1.1.1.1:443;captive.apple.com;cloud.tencent.com.
  • --password <PASSWORD>: Must be the same as the ShadowTLS client.

Pass global parameters first(if any), then mode, then mode parameters. For example: shadow-tls --threads 1 server --listen 0.0.0.0:4430 --server 127.0.0.1:8888 --tls captive.apple.com --password 1.

Recommended Practice

Server Side

On server side you need to run both shadowsocks and shadow-tls. You can start both of them manually, or with systemd.

The easiest way is running them with docker-compose. Install docker and docker-compose if you don't have them.

Then copy the example file to your server and edit it. Then run it with docker-compose up -d.

Client Side

You need to run both shadow-tls and shadowsocks client. There are serveal ways to start them.

Generic Way

  1. Start shadow-tls client on a server inside the firewall, then connect it on any device with shadowsocks protocol. This requires you to have an additional server with public ip and sufficient bandwidth, you may have to pay for additional traffic.

For Linux Users

  1. (Recommended)Run shadow-tls client with docker-compose.
  2. Manually start the binary.

For MacOS Users

  1. (Recommended)Start the binary automatially.
  2. Manually start the binary.
  3. Run shadow-tls client with docker-compose. Note: you have to modify the network mode because docker on MacOS does not support host mode. It is not efficient enough since docker started a linux kernel in vm and forward the traffic.
  4. Use supported client:
    1. Surge for Mac: Only support v2 now(doc). Works correctly and easy to configure.
    2. Clash.Meta: But I haven't tried it.
    3. v2ray_simple: I haven't tried either.
    4. sing-box: A good implementation. I haven't tried either.

For Windows Users

  1. We don't have windows support since our runtime Monoio does not support it yet. So you can only use WSL or docker on windows to run our binary.
  2. (Recommended)Use supported client mentioned in the previous paragraph(other implementations).

For Android Users

  1. (Recommended)Use supported client.
  2. Run our binary with terminal and use any client that support shadowsocks.

For iOS Users

  1. (Recommended)Use supported client.
    1. ShadowRocket: It works but maybe with bugs. Under my testing, using SNI like www-jp.feishu.cn cannot work properly, but with captive.apple.com works.
    2. Surge: Only support v2 now(doc). Works correctly and easy to configure.

How to Choose TLS Handshake Server

  1. Low latency: Test on your vps to make sure the destination is with low latency. You can do the checking with ping for simple, but with curl will be more accurate.
  2. Trusted by the firewall: It must be a legal service, and widely used.
  3. Using TLS servers that support tls1.3 can reduce latency. You can test it will curl setting tls version: curl -I --tlsv1.3 --tls-max 1.3 -vvv https://example.com.

Not much servers support tls1.3. But you can alway trust services by 宇宙厂 :)

Better Performance

Change Log Level

By default, shadow-tls use INFO log level.

For io performance, you can change it to ERROR by setting an environment variable RUST_LOG=error.

It is recommended after you make sure everything works fine. It will only print error info if you change it this way.

Disable seccomp

If you use docker, seccomp will be enabled by default. You can disable it for better performance by adding these into docker-compose.yml:

    security_opt:
      - seccomp:unconfined

Common Issues

  1. unable to build monoio runtime, OutOfMemory: Since we use io-uring when available, we need lock some memory. But on some linux the default lock memory limitation is far from enough. There are 2 ways to solve it:

    1. (Recommended)Set a larger limitation: Link | 中文链接 | Another related issue
    2. Disable io-uring and use epoll: Set env MONOIO_FORCE_LEGACY_DRIVER=1. With this env, the cpu usage may become a little bit higher.

  2. I want to use port 443, but it is already used by nginx: Shadow-tls support multiple SNI now, so it can be used as a SNI proxy. Let your nginx listen on 127.0.0.1:8443, and use tls settings like your.domain:127.0.0.1:8443;captive.apple.com;www.feishu.cn.

  3. Pull image too slow: You can try to use another registry. We have pushed image to 3 registries:

    1. ghcr.io/ihciah/shadow-tls
    2. ihciah/shadow-tls
    3. registry.gitlab.com/ihciah/shadow-tls

    Also, you can use docker hub mirrors.

Clone this wiki locally