nutshells/ss-obfs repository overview

⁠SS-OBFS Docker Image

This image combines ss-libev⁠ and simple-obfs⁠ both with the server and client included.

⁠Variants:

Tag	Description	🐳
:latest	Shadowsocks-libev & simple-obfs on alpine:latest.

⁠Usage

⁠Synopsis

docker container run [OPTIONS] nutshells/ss-obfs [COMMAND] [ARG...]

• Learn more about docker container run and its OPTIONS here⁠;
• List all available COMMANDs: docker container run --rm --read-only nutshells/ss-obfs help
• List all ARGs (for configuring⁠ the containers):
  • For server mode: docker container run --rm --read-only nutshells/ss-obfs server --help
  • For client mode: docker container run --rm --read-only nutshells/ss-obfs client --help

⁠Getting Started

Let's create a server container on the remote server:

docker container run \
       -d -p <remote_port>:12345/tcp -p <remote_port>:12345/udp \
       --name=ss-obfs-server --restart=unless-stopped --read-only \
       -e PASSWORD=<password> \
       nutshells/ss-obfs \
       server

Then run a client container on your local machine with the same configuration:

docker container run \
       -d -p 127.0.0.1:12345:12345/tcp -p 127.0.0.1:12345:12345/udp \
       --name=ss-obfs-client --restart=unless-stopped --read-only \
       -e PASSWORD=<password> \
       -e SERVER_ADDRESS=<remote_address> -e SERVER_PORT=<remote_port> \
       nutshells/ss-obfs \
       client

See if it shows the correct IP address of your remote server.

curl -sSL https://ipinfo.io/ --socks5 127.0.0.1:12345

⁠Custom Configurations

As you can see from the examples of the previous sections: the container accepts original command-line options⁠ of ss-libev as arguments.

Here are a few more examples:

⁠Enabling verbose mode:

docker container run [OPTIONS] nutshells/ss-obfs server -v [OTHER_ARG...]

⁠Printing the version & command-line options:

docker container run --rm --read-only nutshells/ss-obfs server --help
docker container run --rm --read-only nutshells/ss-obfs client --help

However, please be informed that some of the options are managed by the entrypoint script⁠ of the container. You will encounter an error while trying to set any of them, just use the environment variables⁠ instead; as for other exceptions, just follow the message to get rid of them.

⁠Reference

⁠Environment Variables

Learn to set an environment variable here⁠, or refer to the Getting Started⁠ section for some live examples.

⁠Build Arguments

⁠Advanced Topics

⁠Using Docker-compose

See the sample file⁠.

⁠Better Performance

According to the optimization tips⁠, you'd better increase the open file limit for the container:

docker container run \
       --ulimit nofile=51200:51200 \
       [OTHER_OPTIONS] nutshells/ss-obfs server [OTHER_ARG...]

Additionally, the --net=host option provides the best network performance, use it if you know it exactly.

⁠Gaining a shell access

Get an interactive shell to a running container:

docker container exec -it <container_name> /bin/ash

⁠Customizing the image

⁠by using the --build-arg options

You can customize the image more easily by using the --build-arg option.

Let's remove the simple-obfs plugin completely from the build:

git clone --depth 1 https://github.com/quchao/nutshells.git
docker image build -q=false --rm=true --no-cache=true \
             -t nutshells/ss-obfs \
             -f ./ss-obfs/Dockerfile \
             --build-arg WITH_OBFS=false \
             ./ss-obfs

⁠By modifying the dockerfile

You may want to make some modifications to the image. Pull the source code from GitHub, customize it, then build one by yourself:

git clone --depth 1 https://github.com/quchao/nutshells.git
docker image build -q=false --rm=true --no-cache=true \
             -t nutshells/ss-obfs \
             -f ./ss-obfs/Dockerfile \
             ./ss-obfs

⁠By committing the changes on a container

Otherwise just pull the image from the official registry, start a container and get a shell⁠ to it, commit the changes⁠ afterwards.

docker container commit --change "Commit msg" <container_name> nutshells/ss-obfs

⁠Contributing

Contributions are always welcome in many ways:

• Give a star to show your fondness;
• File an issue⁠ if you have a question or an idea;
• Fork this repo and submit a PR⁠;
• Improve the documentation.

⁠Todo

• Add a section about modifying kernel parameters in containers.
• Add a HealthCheck instruction.
• Add ipv6 support.

⁠Acknowledgments & Licenses

Unless specified, all codes of Project Nutshells are released under the MIT License⁠.

Other relevant softwares:

Ware/Lib	License
Docker⁠
Shadowsocks-libev⁠
Simple-obfs⁠