(WIP) guerrilla — A collection of easy-to-deploy censorship circumvention tools for digital guerrillas

Table of Contents

• Roadmap
• Usage
• Services
  • shadowsocks-rust server
• Tools
  • genqr — Generate a QR code for shadowsocks clients
  • genpass — Generate a random password using openssl
• Licenses

This repository provides a Docker Compose project for running different kinds of proxies and other censorship circumvention tools on your own servers. More services and documentation will be added later.

The announcement can be found here.

Roadmap

This project is in its early stages of development. The roadmap will be updated as new needs arise.

• ✓ (service) shadowsocks server

• ❏ (service) DNS resolver and/or proxy with support for DoH

• ❏ (service) mask as a regular site

• ✓ (tool) shadowsocks qr generator

• ✓ (tool) openssl base64 password generator

Usage

1. Clone the project

   $ git clone https://github.com/de4thr0ll/guerrilla.git

   Note	All further commands are performed in the cloned project root directory.

2. Build and pull all container images

   $ docker compose pull && docker compose build

   Note	This may take quite some time, especially for the tools image.

3. Add a .env file with the following contents

   EXTERNAL_IP=<your.server_ip.without.angles>

4. Follow further instructions for a specific service or tool.

Services

shadowsocks-rust server

A port of shadowsocks written in Rust. For more, see this repo.

1. Generate a password for the server

   Tip	See genpass.

2. Create a configuration file

   $ cp shadowsocks.json{.example,}

3. Edit the configuration file shadowsocks.json as appropriate

   Tip	The config file reference can be found here.

   Warning

   If you want to change the port shadowsocks-rust is listening on, don’t forget to change it in the compose.yml file.

   Note	The server field in the config file must contain the service name, shadowsocks.

4. Start the server

   $ docker compose up -d shadowsocks

Tools

Miscellaneous tools to simplify your user experience.

Tip	To enable ping support for tools, add the NET_RAW capability in the compose.yml file.

genqr — Generate a QR code for shadowsocks clients

This will generate a QR code for adding shadowsocks configuration to clients. The code will be printed right in your terminal in UTF-8.

Example video

$ docker compose run --rm tools genqr

genpass — Generate a random password using openssl

$ docker compose run --rm tools genpass <size>

Note	<size> is the size of your password in bytes. The password itself will have a larger count of characters since it is encoded in Base64.

Tip	The longer password the better. Make sure to use at least 20-byte passwords.

Licenses

• The code is licensed under the BSD Zero Clause License.

• guerrilla banner © 2024 by de4thr0ll <160345688+de4thr0ll@users.noreply.github.com> is licensed under CC BY 4.0.