From 33fdaaef428ddc5d8fc89cb907bf2af395fbb951 Mon Sep 17 00:00:00 2001 From: idk Date: Thu, 22 May 2025 00:00:52 -0400 Subject: [PATCH] Update README.md --- README.md | 118 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 81 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index a269510..bef615b 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,34 @@ # go-gitlooseleaf -A soft-fork of Gitea that enables simultaneous multi-protocol access via standard TLS, I2P, and Tor onion services. This repository contains only the network interface modules and CI configuration needed to build custom Gitea binaries. +A soft-fork of Gitea that enables simultaneous multi-protocol access via standard TLS, I2P, and Tor onion services. This project enhances access to Gitea repositories across diverse network environments without compromising core functionality. + +## Features + +- **Multi-Protocol Access**: Access your Gitea instance simultaneously through: + - Standard HTTPS/TLS connections + - I2P (Invisible Internet Project) network + - Tor onion services +- **Complete Protocol Support**: All Git operations work seamlessly across all networks: + - Web interface for browsing and management + - Git operations over HTTPS + - Git operations over SSH (when using Gitea's built-in SSH server) +- **Minimal Configuration**: Requires minimal changes to standard Gitea setup +- **Censorship Resistance**: Maintains repository availability even when specific networks are blocked ## How It Works -This project leverages GitHub Actions to automatically build a modified version of Gitea that can simultaneously serve content over multiple protocols: -- Standard HTTPS/TLS connections -- I2P (Invisible Internet Project) network -- Tor onion services +go-gitlooseleaf leverages Gitea's modular network architecture to enable multi-protocol access without modifying the core codebase. The implementation replaces Gitea's network interfaces with protocol-aware alternatives: -The beauty of this approach is that it requires no changes to Gitea's core codebase, as Gitea intelligently encapsulates network operations through abstraction: - -1. **Network Listeners**: Gitea uses `graceful.GetListener()` (defined in `modules/graceful/server.go`) for all incoming connections -2. **Network Clients**: Gitea's HTTP client connections can be configured with custom transport implementations - -We take advantage of these abstractions by replacing the default implementations with our multi-protocol versions during the build process. +1. **Network Listeners**: Gitea uses `graceful.GetListener()` (defined in `modules/graceful/server.go`) for all incoming connections, which we replace with our multi-protocol implementation +2. **Automatic Protocol Detection**: The system automatically detects and routes connections through the appropriate protocol +3. **Rate Limiting**: Built-in protection against excessive connection attempts ## Implementation Details -The network listener replacement works because Gitea's default `GetListener()` implementations (`DefaultGetListener()`) are defined in platform-specific files: -- `modules/graceful/net_unix.go` for Unix-like systems -- `modules/graceful/net_windows.go` for Windows - -Our implementation introduces a `MultiGetListener()` function that handles TLS, I2P, and Tor connections using the `go-meta-listener` package, while still supporting Unix sockets for internal functions. - -Similarly, we replace the default HTTP client with a version that can route traffic through the appropriate network (TLS, I2P, or Tor) based on the destination. - -## Current Implementation - -The current implementation in `net_mirror.go` uses: -- `go-meta-listener/mirror` for listening on multiple protocols -- Rate limiting through `go-i2p/go-limit` -- Environment variables (`EMAIL`, `HOSTNAME`) for configuration +The network listener replacement works by providing a custom implementation of Gitea's `GetListener()` function: ```go -// This implements the GetListener function for TLS, I2P, and Onion +// MultiGetListener handles connections across TLS, I2P, and Tor func MultiGetListener(network, address string) (net.Listener, error) { // Support for Unix sockets remains unchanged if network == "unix" || network == "unixpacket" { @@ -51,7 +45,7 @@ func MultiGetListener(network, address string) (net.Listener, error) { return nil, err } - // Apply rate limiting + // Apply rate limiting for protection return limitedlistener.NewLimitedListener(ml, limitedlistener.WithMaxConnections(500), // concurrent connections limitedlistener.WithRateLimit(24), // connections per second @@ -59,20 +53,41 @@ func MultiGetListener(network, address string) (net.Listener, error) { } ``` -## Usage Caveats +## Configuration -While the HTTP interface works seamlessly across all three protocols, other Gitea communication channels require additional configuration: +### Basic Setup -1. **SMTP Client**: If configured, email connections from Gitea will need proper routing: - - For I2P: Use local ports like `127.0.0.1:7659/7660` - - For Tor: Configure appropriate SOCKS proxy settings - -2. **SSH Connections**: Git operations over SSH require additional configuration to properly route through anonymity networks. These settings depend on your specific deployment environment. - -3. **Environment Variables**: +1. **Environment Variables**: - `EMAIL`: Used for TLS certificate generation (required for HTTPS) - `HOSTNAME`: Server hostname (defaults to local machine name if not set) +2. **Gitea Configuration** (app.ini): + ```ini + [server] + START_SSH_SERVER = true # Enable built-in SSH server for multi-protocol SSH support + SSH_PORT = 22 # Must end with "22" for automatic SSH mirroring (e.g., 22, 2222, 10022) + ``` + +### Network Addresses + +Your Gitea instance will be available at: +- HTTPS: `https://yourdomain.com` +- Tor: `http://youronionaddress.onion` (automatically generated) +- I2P: `http://youri2paddress.i2p` (automatically generated) + +Access using Git clients: +```bash +# Clone via HTTPS +git clone https://yourdomain.com/username/repo.git +git clone http://youronionaddress.onion/username/repo.git +git clone http://youri2paddress.i2p/username/repo.git + +# Clone via SSH (when using built-in SSH server) +git clone git@yourdomain.com:username/repo.git +git clone git@youronionaddress.onion:username/repo.git +git clone git@youri2paddress.i2p:username/repo.git +``` + ## Installation You can: @@ -80,8 +95,37 @@ You can: 2. Use the included `install.sh` script to set up a system service 3. Build from source using the GitHub Actions workflows as a reference +## Use Cases + +- **Self-hosting enthusiasts**: Offer your personal Git repositories through multiple networks with a single installation +- **Code hobbyists**: Share your projects with friends regardless of their network constraints or preferences +- **Organizations in regions with network restrictions**: Ensure repository access despite local network limitations +- **Open source projects**: Maximize availability of your codebase to contributors worldwide +- **Educational institutions**: Provide consistent access to course materials and student repositories +- **Privacy-conscious development**: Enable contribution without requiring standard TLS connections + +## FAQ + +**Q: Does this affect Gitea's performance?** +A: There is minimal performance impact for standard TLS connections. I2P and Tor connections will have the typical latency associated with these networks. + +**Q: How do I view my .onion and .i2p addresses?** +A: After starting the service, addresses are displayed in the logs and stored in `./certs/hostname.onion` and `./certs/hostname.i2p`. + +**Q: Can users have different identities on different protocols?** +A: No, user accounts are shared across all protocols. This is an availability enhancement, not an anonymity solution. + +**Q: Is this compatible with Gitea upgrades?** +A: Each version is built against a specific Gitea release. Check the releases page for compatibility information. + +**Q: Do I need to run Tor and I2P services separately?** +A: No, go-gitlooseleaf includes embedded Tor and I2P capabilities, no separate services needed. + +**Q: Why must the SSH port end with "22"?** +A: The automatic protocol detection for SSH connections relies on recognizing the port number pattern. Any port ending in "22" (such as 22, 2222, 10022) will work correctly. + ## License Both this modification and Gitea itself are licensed under the MIT license. - See [LICENSE](LICENSE) for this project's license -- See [LICENSE-gitea.md](LICENSE-gitea.md) for the Gitea license from https://github.com/go-gitea/gitea +- See [LICENSE-gitea.md](LICENSE-gitea.md) for the Gitea license