g3/g3proxy/README.md

[![docs](https://readthedocs.org/projects/g3-project-g3proxy/badge)](https://g3-project.readthedocs.io/projects/g3proxy/)

# g3proxy

The g3proxy is an enterprise level forward proxy, but still with basic support for
tcp streaming / tls streaming / transparent proxy / reverse proxy.

## User Guide

[中文](UserGuide.zh_CN.md) | [English](UserGuide.en_US.md)

## How to build

You need to follow the [dev-setup](../doc/dev-setup.md) guide to set up your build environment first.

To build debug binaries:

```shell
cargo build -p g3proxy -p g3proxy-ctl
```

To build release binaries:

```shell
cargo build --profile release-lto -p g3proxy -p g3proxy-ctl
```

See [Build and Package](../doc/build_and_package.md) if you want to build binary packages or docker images.

## Documents

You can view the reference documentation generated by sphinx online at
[Read the Docs](https://g3-project.readthedocs.io/projects/g3proxy/en/latest/),
including detailed configuration format, log format, metrics definition, protocol definition, etc.

## Examples

You can find example config in the [examples](examples) directory.

## Detailed Features

### Server

Servers will handle connections from clients. There many types of servers can be used for different purpose.

The common features are:

* Ingress network filter | Target Host filter | Target Port filter
* Socket Speed Limit
* Request Rate Limit | IDLE Check
* Protocol Inspection | TLS/TLCP Interception | ICAP Adaptation
* Various TCP & UDP socket config options
* Rustls TLS Server
* Openssl/BoringSSL/AWS-LC/Tongsuo TLS Server & Client
* Tongsuo TLCP Server & Client (国密《GB/T 38636-2020》)

#### Forward Proxy Servers

- Http(s) Proxy
    * TLS / mTLS
    * Http Forward | Https Forward | Http CONNECT | Ftp over HTTP
    * easy-proxy | masque/http Well-Known URI
    * Basic User Authentication
    * Port Hiding

- Socks Proxy
    * Socks4 Tcp Connect | Socks5 Tcp Connect | Socks5 UDP Associate
    * User Authentication
    * Client side UDP IP Binding / IP Map / Ranged Port

#### Transparent Proxy Servers

- SNI Proxy
    * Multiple Protocol: TLS SNI extension | HTTP Host Header
    * Host Redirection / Host ACL

- TCP TPROXY
    * Linux [Netfilter TPROXY](https://docs.kernel.org/networking/tproxy.html)
    * FreeBSD [ipfw forward](https://man.freebsd.org/cgi/man.cgi?query=ipfw)
    * OpenBSD [pf divert-to](https://man.openbsd.org/pf.conf.5#divert-to)

#### Reverse Proxy Servers

- Http(s) Reverse Proxy
    * TLS / mTLS
    * Basic User Authentication
    * Port Hiding
    * Host based Routing

#### Streaming Servers

- TCP Stream
    * Upstream TLS / mTLS
    * Load Balance: RR / Random / Rendezvous / Jump Hash

- TLS Stream
    * mTLS
    * Upstream TLS / mTLS
    * Load Balance: RR / Random / Rendezvous / Jump Hash

#### Alias Port Servers

Alias port servers can be used to add extra ports to other servers.

- Plain TCP Port
    * PROXY Protocol
- Plain TLS Port
    * PROXY Protocol
    * mTLS
    * based on Rustls
- Native TLS Port
    * PROXY Protocol
    * mTLS
    * based on OpenSSL/BoringSSL/AWS-LC/Tongsuo
- Intelli Proxy Proxy
    * Multiple protocol: Http Proxy | Socks Proxy
    * PROXY Protocol

### Escaper

Escapers are used to define the way to connect to upstream. There are many types of escapers.

The common features are:

* Happy Eyeballs
* Socket Speed Limit
* Various TCP & UDP socket config options
* IP Bind

#### Direct Connect Escapers

- DirectFixed
    * TCP Connect | TLS Connect | HTTP(s) Forward | UDP Associate
    * Egress network filter
    * Resolve redirection
    * Index based Egress Path Selection

- DirectFloat
    * TCP Connect | TLS Connect | HTTP(s) Forward | UDP Associate
    * Egress network filter
    * Resolve redirection
    * Dynamic IP Bind
    * Json based Egress Path Selection

#### Proxy Chaining Escapers

- Http Proxy
    * TCP Connect | TLS Connect | HTTP(s) Forward
    * PROXY Protocol
    * Load Balance: RR / Random / Rendezvous / Jump Hash
    * Basic User Authentication

- Https Proxy
    * TCP Connect | TLS Connect | HTTP(s) Forward
    * PROXY Protocol
    * Load Balance: RR / Random / Rendezvous / Jump Hash
    * Basic User Authentication
    * mTLS

- Socks5(s) Proxy
    * TCP Connect | TLS Connect | HTTP(s) Forward | UDP Associate
    * Load Balance: RR / Random / Rendezvous / Jump Hash
    * Basic User Authentication

- ProxyFloat
    * Dynamic Proxy: Http Proxy | Https Proxy | Socks5(s) Proxy
    * Json based Egress Path Selection

#### Router Escapers

Router escaper can be used to select the real escapers, based on different route rules.

- route-client - based on client addresses
    * exact ip match
    * subnet match
- route-mapping - based on user supplied rules in requests
    * Index based Egress Path Selection
- route-query - based on queries to external agent
- route-resolved - based on resolved IP of target host
- route-geoip - based on GeoIP rules of the resolved IP
- route-select - simple load balancer
    * RR / Random / Rendezvous / Jump Hash
    * Json based Egress Path Selection
- route-upstream - based on original target host
    * exact ip match
    * exact domain match
    * wildcard domain match
    * subnet match
    * regex domain match
- route-failover - failover between primary and standby escaper

#### Other Helper Escapers

- comply-audit - overwrite server side auditor settings

### Resolver

- c-ares
    * UDP
    * TCP
- hickory
    * UDP / TCP
    * DNS over TLS
    * DNS over HTTPS
    * DNS over HTTP/3
    * DNS over QUIC
- fail-over

### Auth

#### Auth Method

- HTTP Basic Auth
- Socks5 User Auth
- Anonymous user

#### User Features

- ACL: Proxy Request | Target Host | Target Port | User Agent
- Socket Speed Limit | Process Level Global Speed Limit
- Request Rate Limit | Concurrency Limit | IDLE Check
- Auto Expire | Block
- Json based Egress Path Selection

#### User Site Features

It's also possible to set different site config for each user:

- Match by Exact IP | Exact Domain | Wildcard Domain | Subnet
- Request | Client Traffic | Remote Traffic Metrics
- Task Duration Histogram Metrics
- Custom TLS Client Config

### Audit

- TCP Protocol Inspection
- Task Level Sampling
- TLS/TLCP Interception
- External Certificate Generator
- TLS/TLCP Decrypted Stream Dump
- Stream Detour for connection based protocols
- Http1 & Http2 Interception
- IMAP & SMTP Interception
- ICAP Adaptation, support HTTP1/HTTP2/IMAP/SMTP

### Logging

- Log Types
    * Server: task log
    * Escaper: escape error log
    * Resolver: resolve error log
    * Audit: inspect & intercept log

- Backend Protocol
    * journald
    * syslog
    * fluentd

### Metrics

- Metrics Types
    * Server level metrics
    * Escaper level metrics
    * User level metrics
    * User-Site level metrics
    * Resolver metrics
    * Runtime metrics
    * Log metrics

- Backend Protocol
    * StatsD, so it's possible to use StatsD implementations to redistribute metrics to many other TSDBs