Divers/go-away
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Page: Installation
Pages
Challenges Installation Rule Actions
5 Installation
WeebDataHoarder edited this page 2025-05-03 04:17:19 +02:00
Table of Contents

Installation

go-away usually is configured as a reverse proxy that sits in front or in between the target site and the internet.

Automated TLS can be enabled if necessary, and this allows TLS Fingerprinting to be added to the request context.

It can take plaintext HTTP/1 and HTTP/2 / h2c connections if desired over the same port. When doing this, it is recommended to have another reverse proxy upstream (for example Caddy, nginx, HAProxy) to handle HTTPs or similar.

From source

go-away is compiled using Golang. Requires Go 1.24+. Builds statically without CGo usage.

If you are looking for Go 1.22 support, the go1.22 is available with patches regularly rebased on main development branch.

Compilation

git clone https://git.gammaspectra.live/git/go-away.git && cd go-away

# Optional: Compile compressed assets. zopfli / brotli / zstd required
./build-compress.sh

# Optional, for development: Rebuild WASM files using TinyGo. Requires compiling Clang / LLVM
# ./build-wasm.sh

# Build go-away static binary without cgo 
CGO_ENABLED=0 go build -pgo=auto -v -trimpath -ldflags=-buildid= -o go-away ./cmd/go-away

# Run example server targeting backend at http://127.0.0.1:3000
./go-away --slog-level DEBUG --bind ":8080" \
--backend "git.example.com=http://127.0.0.1:3000" \
--client-ip-header "X-Client-Ip" \
--policy examples/forgejo.yml --policy-snippets examples/snippets/

Example of nginx/caddy pointing git.example.com onto go-away:

# Run example server targeting backend at http://127.0.0.1:3000
./go-away --slog-level DEBUG --bind ":8080" \
--backend "git.example.com=http://127.0.0.1:3000" \
--client-ip-header "X-Client-Ip" \
--policy examples/forgejo.yml --policy-snippets examples/snippets/

Example of go-away terminating TLS directly via ACME for git.example.com:

# Run example server targeting backend at http://127.0.0.1:3000
./go-away --slog-level DEBUG --bind ":443" --acme-autocert \
--backend "git.example.com=http://127.0.0.1:3000" \
--backend-ip-header "X-Client-Ip" \
--policy examples/forgejo.yml --policy-snippets examples/snippets/

It is recommended to use some sort of Layer 4 SNI/TLS proxy to pass requests to go-away without decryption. This will allow TLS Fingerprinting to be done directly.

Command line usage

Arguments can use either one or two dashes (--) for passing options.

Usage of go-away:
  -acme-autocert string
        enables HTTP(s) mode and uses the provided ACME server URL or available service (available: letsencrypt)
  -backend value
        backend definition in the form of an.example.com=http://backend:1234 (can be specified multiple times)
  -backend-ip-header string
        Backend HTTP header to set the client IP address from, if empty defaults to leaving Client header alone (X-Real-Ip, X-Client-Ip, X-Forwarded-For, Cf-Connecting-Ip, etc.)
  -bind string
        network address to bind HTTP/HTTP(s) to (default ":8080")
  -bind-network string
        network family to bind HTTP to, e.g. unix, tcp (default "tcp")
  -bind-proxy
        use PROXY protocol in front of the listener
  -cache string
        path to temporary cache directory (default "/tmp/go_away_cache")
  -challenge-template string
        name or path of the challenge template to use (anubis, forgejo) (default "anubis")
  -challenge-template-logo string
        override template logo to use
  -challenge-template-theme string
        override template theme to use (forgejo => [forgejo-auto, forgejo-dark, forgejo-light, gitea...])
  -check
        check configuration and policies, then exit
  -client-ip-header string
        Client HTTP header to fetch their IP address from (X-Real-Ip, X-Client-Ip, X-Forwarded-For, Cf-Connecting-Ip, etc.)
  -config string
        path to config override YAML file
  -debug-bind string
        network address to bind debug on
  -jwt-private-key-seed string
        Seed for the jwt private key, or on JWT_PRIVATE_KEY_SEED env. One be generated by passing "generate" as a value, follows RFC 8032 private key definition. Defaults to random
  -metrics-bind string
        network address to bind metrics on
  -passthrough
        passthrough mode sends all requests to matching backends until state is loaded
  -path string
        base path where to expose go-away package onto, challenges will be served from here (default "/.well-known/.git.gammaspectra.live/git/go-away/cmd/go-away")
  -policy string
        path to policy YAML file
  -policy-snippets value
        path to YAML snippets folder (can be specified multiple times)
  -slog-level string
        logging level (see https://pkg.go.dev/log/slog#hdr-Levels) (default "WARN")
  -socket-mode string
        socket mode (permissions) for unix domain sockets. (default "0770")

Dockerfile

A Dockerfile is available under the repository root. See more information on available configuration under the docker-compose section.

Container images

Container images are published under the following package repositories:

  • git.gammaspectra.live/git/go-away
  • codeberg.org/gone/go-away
  • ghcr.io/weebdatahoarder/go-away

The following tags are available, each on linux/amd64 linux/arm64 linux/riscv64 architectures:

  • latest: Follows the main development branch. Expect breakage, but also new changes faster.
  • MAJOR.MINOR.PATCH-alpine3.21: Specific tagged versions matching patch release, based on alpine3.21.
  • MAJOR.MINOR-alpine3.21: Specific tagged versions matching the general MAJOR.MINOR release tags, based on alpine3.21.
  • MAJOR-alpine3.21: Specific tagged versions matching the general MAJOR release tags, based on alpine3.21. MAJOR number will be updated when breaking changes are introduced without deprecation paths.

We recommend following either MAJOR.MINOR or MAJOR tags on production, or if testing, latest. See Latest releases for changelogs.

docker-compose or alike

Example follows a hypothetical Forgejo server running on http://forgejo:3000 serving git.example.com

networks:
  forgejo:
    external: false
    
volumes:
  goaway_cache:
    
services:
  go-away:
    # See above container images to choose the preferred tag
    # image: codeberg.org/gone/go-away:latest
    # image: ghcr.io/weebdatahoarder/go-away:latest
    image: git.gammaspectra.live/git/go-away:latest
    restart: always
    ports:
      - "3000:8080"
    networks:
      - forgejo
    depends_on:
      - forgejo
    volumes:
      - "goaway_cache:/cache"
      - "./examples/forgejo.yml:/policy.yml:ro"
      # Example snippets are bundled by default
      # You can include your own if needed
      #- "./your/snippets/:/policy/snippets/:ro"
    environment:
      #GOAWAY_BIND: ":8080"
      # Supported tcp, unix, and proxy (for enabling PROXY module for request unwrapping)
      #GOAWAY_BIND_NETWORK: "tcp"
      #GOAWAY_SOCKET_MODE: "0770"

      # Enable Prometheus metrics under /metrics on this bind
      #GOAWAY_METRICS_BIND: ":9090"
      # Enable Go debug profiles under this bind
      #GOAWAY_DEBUG_BIND: ":6060"
      
      # set to letsencrypt or other directory URL to enable HTTPS. Above ports will be TLS only.
      # enables request JA3N / JA4 client TLS fingerprinting
      # TLS fingerprints are served on X-TLS-Fingerprint-JA3N and X-TLS-Fingerprint-JA4 headers
      # TLS fingerprints can be matched against on CEL conditions
      #GOAWAY_ACME_AUTOCERT: ""
      
      # Cache path for several services like certificates and caching network ranges
      # Can be semi-ephemeral, recommended to be mapped to a permanent volume
      #GOAWAY_CACHE="/cache"
      
      # default is WARN, set to INFO to also see challenge successes and others
      # DEBUG will log all requests
      #GOAWAY_SLOG_LEVEL: "INFO"
      
      # this value is used to sign cookies and challenges. by default a new one is generated each time
      # set to generate to create one, then set the same value across all your instances
      #GOAWAY_JWT_PRIVATE_KEY_SEED: ""
      
      # HTTP header that the client ip will be fetched from
      # Defaults to the connection ip itself, if set here make sure your upstream proxy sets this properly
      # Usually X-Forwarded-For is a good pick
      # Not necessary with GOAWAY_BIND_NETWORK: proxy
      GOAWAY_CLIENT_IP_HEADER: "X-Real-Ip"
      
      # HTTP header that go-away will set the obtained ip will be set to
      # If left empty, the header on GOAWAY_CLIENT_IP_HEADER will be left as-is
      #GOAWAY_BACKEND_IP_HEADER: ""
      
      # Alternate way of specifying parameters or more advanced settings
      # Pass path to YAML file
      #GOAWAY_CONFIG: ""
      
      GOAWAY_POLICY: "/policy.yml"

      # Include extra snippets to load from this path.
      # Note that the default snippets from example/snippets/ are included by default
      #GOAWAY_POLICY_SNIPPETS: "/policy/snippets"
      
      # Template, and theme for the template to pick. defaults to an anubis-like one
      # An file path can be specified. See embed/templates for a few examples
      GOAWAY_CHALLENGE_TEMPLATE: forgejo
      GOAWAY_CHALLENGE_TEMPLATE_THEME: forgejo-auto
      
      # Logo url to use on templates. Defaults to either template specific or bundled logo
      #GOAWAY_CHALLENGE_TEMPLATE_LOGO: ""
      
      # Backend to match. Can be subdomain or full wildcards, "*.example.com" or "*"
      # Note: if you access git.example.com:8080, you will need to set the following
      #       GOAWAY_BACKEND: "git.example.com:8080=http://forgejo:3000"
      GOAWAY_BACKEND: "git.example.com=http://forgejo:3000"
      
    # additional backends can be specified via more command arguments  
    # command: ["--backend", "ci.example.com=http://ci:3000"]

  forgejo:
    # etc.

go-away Documentation

Installation

Policy Syntax