### Example: reverse proxy and port forwarding with PROXY protocol

Source: https://gost.run/en/tutorials/proxy-protocol

Two CLI commands: one starts a reverse proxy on port 8000 forwarding to port 8080, and the other starts a port forwarding service on port 8080 with PROXY protocol enabled.

```bash
gost -L tcp://:8000/:8080 -L tcp://:8080/example.com:80?proxyProtocol=1

```

```bash
curl -H"Host: example.com" http://192.168.100.100:8000

```

--------------------------------

### Client example - CLI

Source: https://gost.run/en/tutorials/tuntap

Starts a TAP client that connects to the server at SERVER_IP:8421. The client's TAP device net is 192.168.123.2/24.

```bash
gost -L=tap://:0/SERVER_IP:8421?net=192.168.123.2/24

```

--------------------------------

### Start Shadowsocks proxy via CLI

Source: https://gost.run/en/tutorials/protocols/ss

Command-line example to start a Shadowsocks proxy with chacha20-ietf-poly1305 cipher and password 'pass' on port 8338.

```bash
gost -L ss://chacha20-ietf-poly1305:pass@:8338
```

--------------------------------

### Start gost service with systemctl

Source: https://gost.run/en/getting-started/configuration-overview

Start the gost service immediately.

```bash
systemctl start gost

```

--------------------------------

### -V print version example

Source: https://gost.run/en/reference/configuration/cmd

Prints the version. The example shows the command and a sample output.

```shell
gost -V
# gost 3.0.0 (go1.24.0 linux/amd64)

```

--------------------------------

### -C external configuration file examples

Source: https://gost.run/en/reference/configuration/cmd

Examples of specifying a configuration file, using inline configuration, and reading from stdin.

```shell
# Use the configuration file gost.yml
gost -C /etc/gost/gost.yml

# Inline mode.
gost -C '{"api":{"addr":":8080"}}'

# Read from stdin:
gost -C - < gost.yml

```

--------------------------------

### Start gost with configuration file

Source: https://gost.run/en/blog/2026/github-mirror

Command to start gost using the gost.yaml configuration file.

```bash
./gost -C gost.yaml
```

--------------------------------

### Run GOST on public server A with HTTP/2

Source: https://gost.run/en/blog/2016/rtcp2

Starts a GOST HTTP/2 listener on port 443 of the public server A. This is the first step in the setup.

```bash
gost -L http2://:443

```

--------------------------------

### Server example - CLI

Source: https://gost.run/en/tutorials/tuntap

Starts a TAP server on port 8421 with the TAP device net 192.168.123.1/24. The server listens for UDP frames and forwards them to the TAP device.

```bash
gost -L=tap://:8421?net=192.168.123.1/24

```

--------------------------------

### Start Relay handler via CLI

Source: https://gost.run/en/reference/handlers/relay

Command-line example to start a Relay handler listening on port 8421.

```bash
gost -L relay://:8421
```

--------------------------------

### -O output format examples

Source: https://gost.run/en/reference/configuration/cmd

Examples of outputting yaml or json configuration and converting between formats.

```shell
# Output yaml format configuration:
gost -L http://:8080 -O yaml

# Output json format configuration:
gost -L http://:8080 -O json

# Convert json format configuration to yaml format:
gost -C gost.json -O yaml

# Convert yaml format configuration to json format:
gost -C gost.yaml -O json

```

--------------------------------

### HTTP plugin request example

Source: https://gost.run/concepts/router

Shows an example HTTP GET request to the plugin service. The 'dst' parameter is required, and 'id' is optional, used only with routing tunnels.

```bash
curl -XGET "http://127.0.0.1:8000/router?dst=192.168.1.2&id=1b564300-a2c5-406d-af0c-b7bdb039b0e3"

```

--------------------------------

### Start API service with CLI and options (global service)

Source: https://gost.run/en/tutorials/api/overview

Starts the API service with authentication, path prefix, and access log enabled. The user and password are provided in the -api argument.

```bash
gost -L http://:8080 -api "user:pass@:18080?pathPrefix=/api&accesslog=true"

```

--------------------------------

### Start API service with authentication via CLI

Source: https://gost.run/en/tutorials/api/overview

Starts the API service with authentication credentials provided in the -api argument.

```bash
gost -api user:pass@:18080

```

--------------------------------

### DNS Listener Command Line Configuration

Source: https://gost.run/en/reference/listeners/dns

Example of starting a DNS listener on port 10053 using UDP mode via the command line.

```bash
gost -L dns://:10053?mode=udp
```

--------------------------------

### Install PPTP server with apt-get

Source: https://gost.run/blog/2015/redsocks

Installs the PPTP server package on Ubuntu 14.04.

```bash
sudo apt-get install pptpd

```

--------------------------------

### Command-line example: gost -L ... -F ...

Source: https://gost.run/en/getting-started/configuration-overview

Shows a GOST command-line invocation that starts a proxy service with a forwarding chain. The -L parameter defines the local service (HTTP proxy with authentication and metadata), and the -F parameter defines the forwarder (SOCKS5 over TLS with authentication and metadata).

```bash
gost -L http://gost:gost@localhost:8080?foo=bar -F socks5+tls://gost:gost@192.168.1.1:8080?bar=baz

```

--------------------------------

### Complete GOST configuration in JSON

Source: https://gost.run/en/reference/configuration/file

Full JSON configuration example covering all GOST sections: services, chains, TLS, authers, admissions, bypasses, resolvers, hosts, recorders, log, profiling, api, and metrics. Use as a template for a complete GOST setup.

```json
{
  "services": [
    {
      "name": "service-0",
      "addr": ":8080",
      "interface": "eth0",
      "admission": "admission-0",
      "bypass": "bypass-0",
      "resolver": "resolver-0",
      "hosts": "hosts-0",
      "handler": {
        "type": "http",
        "auth": {
          "username": "gost",
          "password": "gost"
        },
        "auther": "auther-0",
        "retries": 1,
        "chain": "chain-0",
        "metadata": {
          "bar": "baz",
          "foo": "bar"
        }
      },
      "listener": {
        "type": "tcp",
        "auth": {
          "username": "user",
          "password": "pass"
        },
        "auther": "auther-0",
        "chain": "chain-0",
        "tls": {
          "certFile": "cert.pem",
          "keyFile": "key.pem",
          "caFile": "ca.pem"
        },
        "metadata": {
          "abc": "xyz",
          "def": 456
        }
      },
      "forwarder": {
        "nodes": [
          {
            "name": "target-0",
            "addr": "192.168.1.1:1234"
          },
          {
            "name": "target-1",
            "addr": "192.168.1.2:2345"
          }
        ],
        "selector": {
          "strategy": "rand",
          "maxFails": 1,
          "failTimeout": 30
        }
      }
    }
  ],
  "chains": [
    {
      "name": "chain-0",
      "selector": {
        "strategy": "round",
        "maxFails": 1,
        "failTimeout": 30
      },
      "hops": [
        {
          "name": "hop-0",
          "interface": "192.168.1.2",
          "selector": {
            "strategy": "rand",
            "maxFails": 3,
            "failTimeout": 60
          },
          "bypass": "bypass-0",
          "nodes": [
            {
              "name": "node-0",
              "addr": ":1080",
              "interface": "eth1",
              "sockopts": {
                "mark": 1
              },
              "bypass": "bypass-0",
              "connector": {
                "type": "socks5",
                "auth": {
                  "username": "user",
                  "password": "pass"
                },
                "metadata": {
                  "foo": "bar"
                }
              },
              "dialer": {
                "type": "tcp",
                "auth": {
                  "username": "user",
                  "password": "pass"
                },
                "tls": {
                  "caFile": "ca.pem",
                  "secure": true,
                  "serverName": "example.com"
                },
                "metadata": {
                  "bar": "baz"
                }
              }
            }
          ]
        }
      ]
    }
  ],
  "tls": {
    "certFile": "cert.pem",
    "keyFile": "key.pem",
    "caFile": "ca.pem"
  },
  "authers": [
    {
      "name": "auther-0",
      "auths": [
        {
          "username": "user1",
          "password": "pass1"
        },
        {
          "username": "user2",
          "password": "pass2"
        }
      ]
    }
  ],
  "admissions": [
    {
      "name": "admission-0",
      "whitelist": false,
      "matchers": [
        "127.0.0.1",
        "192.168.0.0/16"
      ]
    }
  ],
  "bypasses": [
    {
      "name": "bypass-0",
      "whitelist": false,
      "matchers": [
        "*.example.com",
        ".example.org",
        "0.0.0.0/8"
      ]
    }
  ],
  "resolvers": [
    {
      "name": "resolver-0",
      "nameservers": [
        {
          "addr": "udp://8.8.8.8:53",
          "chain": "chain-0",
          "ttl": 60,
          "prefer": "ipv4",
          "clientIP": "1.2.3.4",
          "timeout": 3
        },
        {
          "addr": "tcp://1.1.1.1:53"
        },
        {
          "addr": "tls://1.1.1.1:853"
        },
        {
          "addr": "https://1.0.0.1/dns-query",
          "hostname": "cloudflare-dns.com"
        }
      ]
    }
  ],
  "hosts": [
    {
      "name": "hosts-0",
      "mappings": [
        {
          "ip": "127.0.0.1",
          "hostname": "localhost"
        },
        {
          "ip": "192.168.1.10",
          "hostname": "foo.mydomain.org",
          "aliases": [
            "foo"
          ]
        },
        {
          "ip": "192.168.1.13",
          "hostname": "bar.mydomain.org",
          "aliases": [
            "bar",
            "baz"
          ]
        }
      ]
    }
  ],
  "recorders": [
    {
      "name": "recorder-0",
      "file": {
        "path": "/path/to/recorder/file",
        "sep": "\n",
        "rotation": {
          "maxSize": 100,
          "maxAge": 10,
          "maxBackups": 3,
          "localTime": false,
          "compress": false
        }
      }
    }
  ],
  "log": {
    "output": "stderr",
    "level": "debug",
    "format": "json",
    "rotation": {
      "maxSize": 100,
      "maxAge": 10,
      "maxBackups": 3,
      "localTime": false,
      "compress": false
    }
  },
  "profiling": {
    "addr": ":6060"
  },
  "api": {
    "addr": ":18080",
    "pathPrefix": "/api",
    "accesslog": true,
    "auth": {
      "username": "user",
      "password": "pass"
    },
    "auther": "auther-0"
  },
  "metrics": {
    "addr": ":9000",
    "path": "/metrics"
  }
}
```

--------------------------------

### Start HTTP/2 listener with command line

Source: https://gost.run/en/reference/listeners/http2

Starts a GOST service with an HTTP/2 listener on port 8443 using the command line configuration.

```bash
gost -L http2://:8443

```

--------------------------------

### Start global metrics service with -metrics or metrics config

Source: https://gost.run/en/tutorials/metrics

Start the metrics service in global mode using the -metrics command-line flag or the metrics object in the configuration file. The CLI examples show both a plain address and an address with authentication and a custom path. The YAML configuration defines the metrics service with addr, path, auth, and auther options; unix domain socket is also supported via addr: unix:///var/run/gost.sock.

```bash
gost -L :8080 -metrics=:9000

```

```bash
gost -L :8080 -metrics "user:pass@:9000?path=/metrics"

```

```yaml
services:
- name: service-0
  addr: ":8080"
  handler:
    type: auto
  listener:
    type: tcp

metrics:
  addr: :9000
  # also support unix domain socket
  # addr: unix:///var/run/gost.sock
  path: /metrics
  auth:
    username: user
    password: pass
  auther: auther-0

```

--------------------------------

### Start API service as normal service with CLI

Source: https://gost.run/en/tutorials/api/overview

Starts the API service as a normal service using the api handler with TLS, authentication, path prefix, and access log.

```bash
gost -L "api+tls://user:pass@:18080?pathPrefix=/api&accessLog=true"

```

--------------------------------

### Start Docker Compose

Source: https://gost.run/en/blog/2026/llm-router

Starts the Docker Compose services defined in the compose file.

```bash
docker compose up -d

```

--------------------------------

### Start GOST reverse proxy (./gost -C gost.yaml)

Source: https://gost.run/blog/2026/llm-router

Command to start the GOST reverse proxy using the gost.yaml configuration file.

```bash
./gost -C gost.yaml

```

--------------------------------

### Start GOST on domestic VPS with TLS and forward to foreign VPS

Source: https://gost.run/en/blog/2015/forward

Starts GOST on the domestic VPS (aliyun.com) listening on port 443 with HTTP over TLS, forwarding to the foreign VPS via SOCKS5. This builds the chain.

```bash
gost -L=http+tls://:443 -F=socks://linode.com:1080
```

--------------------------------

### Start standard SOCKS5 proxy service via CLI

Source: https://gost.run/en/tutorials/protocols/socks

Starts a SOCKS5 proxy service with username/password authentication (user:pass) on port 1080.

```bash
gost -L socks5://user:pass@:1080
```

--------------------------------

### Start HTTP and SOCKS5 Proxies

Source: https://gost.run/en/getting-started/quick-start

Starts two services: an HTTP proxy on port 8080 and a SOCKS5 proxy on port 1080. The CLI command and its equivalent YAML configuration are shown together.

```bash
gost -L http://:8080 -L socks5://:1080 

```

```yaml
services:
- name: service-0
  addr: ":8080"
  handler:
    type: http
  listener:
    type: tcp
- name: service-1
  addr: ":1080"
  handler:
    type: socks5
  listener:
    type: tcp

```

--------------------------------

### Complete GOST configuration in YAML

Source: https://gost.run/en/reference/configuration/file

Full YAML configuration example covering all GOST sections: services, chains, TLS, authers, admissions, bypasses, resolvers, hosts, recorders, log, profiling, api, and metrics. Use as a template for a complete GOST setup.

```yaml
services:
- name: service-0
  addr: ":8080"
  interface: eth0
  sockopts:
    mark: 1
  admission: admission-0
  bypass: bypass-0
  resolver: resolver-0
  hosts: hosts-0
  handler:
    type: http
    auth:
      username: user
      password: pass
    auther: auther-0
    chain: chain-0
    retries: 1
    metadata: 
      foo: bar
      bar: baz
  listener:
    type: tcp
    auth:
      username: user
      password: pass
    auther: auther-0
    chain: chain-0
    tls:
      certFile: cert.pem
      keyFile: key.pem
      caFile: ca.pem
    metadata:
      abc: xyz
      def: 456
  forwarder:
    nodes:
    - name: target-0
      addr: 192.168.1.1:1234
    - name: target-1
      addr: 192.168.1.2:2345
    selector:
      strategy: rand
      maxFails: 1
      failTimeout: 30s

chains:
- name: chain-0
  selector:
    strategy: round
    maxFails: 1
    failTimeout: 30s
  hops:
  - name: hop-0
    interface: 192.168.1.2
    sockopts:
      mark: 1
    selector:
      strategy: rand
      maxFails: 3
      failTimeout: 60s
    bypass: bypass-0
    nodes:
    - name: node-0
      addr: ":1080"
      interface: eth1
      sockopts:
        mark: 1
      bypass: bypass-0
      connector:
        type: socks5
        auth:
          username: user
          password: pass
        metadata:
          foo: bar
      dialer:
        type: tcp
        auth:
          username: user
          password: pass
        tls:
          caFile: "ca.pem"
          secure: true
          serverName: "example.com"
        metadata:
          bar: baz 

tls:
  certFile: "cert.pem"
  keyFile: "key.pem"
  caFile: "ca.pem"

authers:
- name: auther-0
  auths:
  - username: user1
    password: pass1
  - username: user2
    password: pass2

admissions:
- name: admission-0
  whitelist: false
  matchers:
  - 127.0.0.1
  - 192.168.0.0/16

bypasses:
- name: bypass-0
  whitelist: false
  matchers:
  - "*.example.com"
  - .example.org
  - 0.0.0.0/8

resolvers:
- name: resolver-0
  nameservers:
  - addr: udp://8.8.8.8:53
    chain: chain-0
    ttl: 60s
    prefer: ipv4
    clientIP: 1.2.3.4
    timeout: 3s
  - addr: tcp://1.1.1.1:53
  - addr: tls://1.1.1.1:853
  - addr: https://1.0.0.1/dns-query
    hostname: cloudflare-dns.com

hosts:
- name: hosts-0
  mappings:
  - ip: 127.0.0.1
    hostname: localhost
  - ip: 192.168.1.10
    hostname: foo.mydomain.org
    aliases:
    - foo
  - ip: 192.168.1.13
    hostname: bar.mydomain.org
    aliases:
    - bar
    - baz

recorders:
- name: recorder-0
  file:
    path: /path/to/recorder/file
    sep: "\n"
    rotation:
      maxSize: 100
      maxAge: 10
      maxBackups: 3
      localTime: false
      compress: false

log:
  output: stderr
  level: debug
  format: json
  rotation:
    maxSize: 100
    maxAge: 10
    maxBackups: 3
    localTime: false
    compress: false

profiling:
  addr: ":6060"

api:
  addr: ":18080"
  pathPrefix: /api
  accesslog: true
  auth:
    username: user
    password: pass
  auther: auther-0

metrics:
  addr: :9000
  path: /metrics

```

--------------------------------

### HTTP plugin request example

Source: https://gost.run/concepts/ingress

Example curl command to query the HTTP plugin service with a host parameter.

```bash
curl -XGET http://127.0.0.1:8000/ingress?host=example.com

```

--------------------------------

### Start SOCKS5 service for iperf test

Source: https://gost.run/en/tutorials/protocols/socks

Starts a SOCKS5 proxy with UDP relay enabled and a large UDP buffer for iperf testing.

```bash
gost -L "socks5://:1080?notls=true&udp=true&udpBufferSize=65535"
```

--------------------------------

### Start SOCKS5 proxy with CLI

Source: https://gost.run/en/reference/handlers/socks5

Starts a SOCKS5 proxy on port 1080 using the command line. The handler type is 'socks' and the listener type is 'tcp'.

```bash
gost -L socks://:1080
```

--------------------------------

### Redis data source data example

Source: https://gost.run/concepts/router

Shows an example of the data stored in Redis for a router, as returned by the HGETALL command. Each destination network is paired with its gateway.

```text
> HGETALL gost:routers:router-0
1) "10.0.0.1"
2) "192.168.123.1"
3) "192.168.1.0/24"
4) "192.168.123.2"
5) "172.10.0.0/16"
6) "192.168.123.3"

```

--------------------------------

### Start SOCKS4 proxy service via CLI

Source: https://gost.run/en/tutorials/protocols/socks

Starts a standard SOCKS4 proxy service on port 1080. Compatible with SOCKS4A protocol. Only supports the CONNECT method.

```bash
gost -L socks4://:1080
```

--------------------------------

### Enable gost service with systemctl

Source: https://gost.run/en/getting-started/configuration-overview

Enable the gost service to start at boot.

```bash
systemctl enable gost

```

--------------------------------

### YAML service configuration for SOCKS4 connector

Source: https://gost.run/en/reference/connectors/socks4

Example of configuring the SOCKS4 connector in a YAML service definition, including the chain and node setup.

```yaml
services:
- name: service-0
  addr: ":8000"
  handler:
    type: auto
    chain: chain-0
  listener:
    type: tcp
chains:
- name: chain-0
  hops:
  - name: hop-0
    nodes:
    - name: node-0
      addr: 192.168.1.1:1080
      connector:
        type: socks4
      dialer:
        type: tcp
```

--------------------------------

### CLI: Start DNS proxy with UDP and TLS upstreams

Source: https://gost.run/en/tutorials/dns

Starts a DNS proxy on port 10053 with UDP upstream 1.1.1.1 and TLS upstream tls://1.1.1.1:853 in UDP mode.

```shell
gost -L dns://:10053/1.1.1.1,tls://1.1.1.1:853?mode=udp

```

--------------------------------

### Start SOCKS5 server for iperf test (command line)

Source: https://gost.run/tutorials/protocols/socks

Starts a SOCKS5 server with UDP relay enabled for iperf3 testing. The 'notls' option disables encryption negotiation.

```bash
gost -L "socks5://:1080?notls=true&udp=true&udpBufferSize=65535"

```

--------------------------------

### DNS查询example.org(ipv4)及响应

Source: https://gost.run/blog/2022/bypass

使用dig命令查询example.org，由于通过分流器，响应中包含ANSWER SECTION，返回正常结果。

```bash
dig -p 10053 example.org
```

```text
;; QUESTION SECTION:
;example.org.               IN  A

;; ANSWER SECTION:
example.org.        74244   IN  A   93.184.216.34
```

--------------------------------

### Remote Serial Forwarding Setup

Source: https://gost.run/en/blog/2023/serial

Two-step setup to forward a local serial port (COM1) on host A to a virtual port on remote host B via a relay service. First start a relay on host A, then on host B map the serial port through the relay.

```bash
gost -L relay://:8420

```

```bash
gost -L serial://COM1/COM1 -F relay://192.168.1.1:8420

```

--------------------------------

### 自定义域名解析（命令行）

Source: https://gost.run/tutorials/dns

通过hosts参数设置自定义域名映射，将example.org映射到127.0.0.1和::1，将example.com映射到2001:db8::1。

```bash
gost -L dns://:10053/1.1.1.1?hosts=example.org:127.0.0.1,example.org:::1,example.com:2001:db8::1
```

--------------------------------

### Redis data source example output

Source: https://gost.run/en/concepts/hosts

Example output from a Redis SMEMBERS command showing the stored host mappings in the same format as file data sources.

```text
> SMEMBERS gost:hosts
1) "127.0.0.1 example.com"
2) "2001:db8::1 example.com"

```

--------------------------------

### DNS查询example.com(ipv4)及响应

Source: https://gost.run/blog/2022/bypass

使用dig命令查询example.com，由于未通过分流器，响应中只有QUESTION SECTION，没有ANSWER SECTION。

```bash
dig -p 10053 example.com
```

```text
;; QUESTION SECTION:
;example.com.               IN  A
```

--------------------------------

### Custom Response Header: forwarder.nodes.http.responseHeader example

Source: https://gost.run/en/tutorials/reverse-proxy

Adds or overwrites HTTP response header fields on a node via the http.responseHeader option. Existing fields with the same name are overwritten. For example, a request to http://example.com gets foo: bar and bar: 123 added to the upstream response.

```yaml
services:
- name: http
  addr: :80
  handler:
    type: tcp
    metadata:
      sniffing: true
  listener:
    type: tcp
  forwarder:
    nodes:
    - name: example-com
      addr: example.com:80
      # filter:
      #   host: example.com
      matcher:
        rule: Host(`example.com`)
      http:
        responseHeader:
          foo: bar
          bar: 123

```

--------------------------------

### Websocket listener command-line configuration

Source: https://gost.run/en/reference/listeners/ws

Starts a GOST service with the Websocket listener using the command line. The example listens on port 8080 with the path /ws.

```bash
gost -L http+ws://:8080?path=/ws

```

--------------------------------

### Build GOST from source

Source: https://gost.run/en

Clone the repository, change to the cmd/gost directory, and build the binary using go build.

```bash
git clone https://github.com/go-gost/gost.git
cd gost/cmd/gost
go build

```

--------------------------------

### DNS查询example.org(ipv6)

Source: https://gost.run/tutorials/dns

使用dig命令查询example.org的AAAA记录，端口10053。

```bash
dig -p 10053 AAAA example.org
```

```text
;; QUESTION SECTION:
;example.org.               IN  AAAA

;; ANSWER SECTION:
example.org.        3600    IN  AAAA    ::1
```

--------------------------------

### CLI Example: gost -L tun://:8421?net=192.168.123.2/24

Source: https://gost.run/en/reference/handlers/tun

Starts a TUN handler with the specified network address. The net parameter is required for the TUN listener.

```bash
gost -L tun://:8421?net=192.168.123.2/24
```

--------------------------------

### DNS查询example.com(ipv6)

Source: https://gost.run/tutorials/dns

使用dig命令查询example.com的AAAA记录，端口10053。

```bash
dig -p 10053 AAAA example.com
```

```text
;; QUESTION SECTION:
;example.com.               IN  AAAA

;; ANSWER SECTION:
example.com.        3600    IN  AAAA    2001:db8::1
```

--------------------------------

### probeResist web option example

Source: https://gost.run/en/tutorials/probe-resistance

Sets the probeResist type to 'web' with a URL. The proxy requests that URL via HTTP GET and returns the response to the client.

```shell
gost -L=http://gost:gost@:8080?probeResist=web:example.com/page.html
```

--------------------------------

### Run GOST on intranet server B with HTTP/2

Source: https://gost.run/en/blog/2016/rtcp2

Starts a GOST HTTP/2 listener on port 8080 of the intranet server B. This is the second step in the setup.

```bash
gost -L http2://:8080

```

--------------------------------

### GOST configuration file example

Source: https://gost.run/en/reference/configuration/file

A complete JSON configuration example for GOST, showing the structure for services, chains, authers, admissions, bypasses, resolvers, hosts, TLS, recorders, logging, profiling, API, and metrics. Use this as a reference for configuring a GOST instance.

```json
{
  "services": [
    {
      "name": "service-0",
      "addr": ":8080",
      "interface": "eth1",
      "bypass": "bypass-0",
      "connector": {
        "type": "socks5",
        "auth": {
          "username": "user",
          "password": "pass"
        },
        "metadata": {
          "foo": "bar"
        }
      },
      "dialer": {
        "type": "tcp",
        "auth": {
          "username": "user",
          "password": "pass"
        },
        "tls": {
          "caFile": "ca.pem",
          "secure": true,
          "serverName": "example.com"
        },
        "metadata": {
          "bar": "baz"
        }
      }
    }
  ],
  "chains": [
    {
      "name": "chain-0",
      "hops": [
        {
          "name": "hop-0",
          "nodes": [
            {
              "name": "node-0",
              "addr": "server:8080",
              "connector": {
                "type": "socks5",
                "auth": {
                  "username": "user",
                  "password": "pass"
                },
                "metadata": {
                  "foo": "bar"
                }
              },
              "dialer": {
                "type": "tcp",
                "auth": {
                  "username": "user",
                  "password": "pass"
                },
                "tls": {
                  "caFile": "ca.pem",
                  "secure": true,
                  "serverName": "example.com"
                },
                "metadata": {
                  "bar": "baz"
                }
              }
            }
          ]
        }
      ]
    }
  ],
  "authers": [
    {
      "name": "auther-0",
      "auths": [
        {
          "username": "user1",
          "password": "pass1"
        },
        {
          "username": "user2",
          "password": "pass2"
        }
      ]
    }
  ],
  "admissions": [
    {
      "name": "admission-0",
      "whitelist": false,
      "matchers": [
        "127.0.0.1",
        "192.168.0.0/16"
      ]
    }
  ],
  "bypasses": [
    {
      "name": "bypass-0",
      "whitelist": false,
      "matchers": [
        "*.example.com",
        ".example.org",
        "0.0.0.0/8"
      ]
    }
  ],
  "resolvers": [
    {
      "name": "resolver-0",
      "nameservers": [
        {
          "addr": "udp://8.8.8.8:53",
          "chain": "chain-0",
          "prefer": "ipv4",
          "clientIP": "1.2.3.4",
          "ttl": 60,
          "timeout": 30
        },
        {
          "addr": "tcp://1.1.1.1:53"
        },
        {
          "addr": "tls://1.1.1.1:853"
        },
        {
          "addr": "https://1.0.0.1/dns-query",
          "hostname": "cloudflare-dns.com"
        }
      ]
    }
  ],
  "hosts": [
    {
      "name": "hosts-0",
      "mappings": [
        {
          "ip": "127.0.0.1",
          "hostname": "localhost"
        },
        {
          "ip": "192.168.1.10",
          "hostname": "foo.mydomain.org",
          "aliases": [
            "foo"
          ]
        },
        {
          "ip": "192.168.1.13",
          "hostname": "bar.mydomain.org",
          "aliases": [
            "bar",
            "baz"
          ]
        }
      ]
    }
  ],
  "tls": {
    "certFile": "cert.pem",
    "keyFile": "key.pem",
    "caFile": "ca.pem"
  },
  "recorders": [
    {
      "name": "recorder-0",
      "file": {
        "path": "/path/to/recorder/file",
        "sep": "\n",
        "rotation": {
          "maxSize": 100,
          "maxAge": 10,
          "maxBackups": 3,
          "localTime": false,
          "compress": false
        }
      }
    }
  ],
  "log": {
    "output": "stderr",
    "level": "debug",
    "format": "json",
    "rotation": {
      "maxSize": 100,
      "maxAge": 10,
      "maxBackups": 3,
      "localTime": false,
      "compress": false
    }
  },
  "profiling": {
    "addr": ":6060",
    "enabled": true
  },
  "api": {
    "addr": ":18080",
    "pathPrefix": "/api",
    "accesslog": true,
    "auth": {
      "username": "user",
      "password": "password"
    },
    "auther": "auther-0"
  },
  "metrics": {
    "addr": ":9000",
    "path": "/metrics"
  }
}
```

--------------------------------

### DNS查询example.org(ipv4)

Source: https://gost.run/tutorials/dns

使用dig命令查询example.org的A记录，端口10053。

```bash
dig -p 10053 example.org
```

```text
;; QUESTION SECTION:
;example.org.               IN  A

;; ANSWER SECTION:
example.org.        3600    IN  A   127.0.0.1
```

--------------------------------

### Custom Request Header: forwarder.nodes.http.requestHeader example

Source: https://gost.run/en/tutorials/reverse-proxy

Adds or overwrites HTTP request header fields on a node via the http.requestHeader option. Existing fields with the same name are overwritten. For example, a request to http://example.com gets User-Agent: gost/3.0.0, foo: bar, and bar: 123 added to the upstream request.

```yaml
services:
- name: http
  addr: :80
  handler:
    type: tcp
    metadata:
      sniffing: true
  listener:
    type: tcp
  forwarder:
    nodes:
    - name: example-com
      addr: example.com:80
      # filter:
      #   host: example.com
      matcher:
        rule: Host(`example.com`)
      http:
        requestHeader:
          User-Agent: gost/3.0.0
          foo: bar
          bar: 123
        # host: test.example.com
    - name: example-org
      addr: example.org:80
      # filter:
      #   host: example.org
      matcher:
        rule: Host(`example.org`)
      http:
        requestHeader:
          User-Agent: curl/7.81.0
          foo: bar
          bar: baz
        # host: test.example.org:80

```

--------------------------------

### 自定义域名解析（配置文件）

Source: https://gost.run/tutorials/dns

通过hosts配置定义自定义域名映射，将example.org映射到127.0.0.1和::1，将example.com映射到2001:db8::1。

```yaml
services:
- name: service-0
  addr: :10053
  hosts: hosts-0
  handler:
    type: dns
  listener:
    type: dns
    metadata:
      mode: udp
  forwarder:
    nodes:
    - name: target-0
      addr: 1.1.1.1
hosts:
- name: hosts-0
  mappings:
  - ip: 127.0.0.1
    hostname: example.org
  - ip: ::1
    hostname: example.org
  - ip: 2001:db8::1
    hostname: example.com
```

--------------------------------

### Redis data retrieval example

Source: https://gost.run/en/concepts/hop

Shows a Redis GET command and its response, illustrating the data format stored in Redis. The response is a JSON string of node configurations.

```text
> GET gost:hops:hop-0:nodes
"[{\"name\":\"http\",...},{\"name\":\"socks5\",...}]"

```

--------------------------------

### 配置文件配置上游DNS服务节点分流器

Source: https://gost.run/blog/2022/bypass

在DNS代理服务的转发器节点上设置分流器，实现精细化分流。当查询example.org时转发给target-1，查询example.com时转发给target-0。

```yaml
services:
- name: service-0
  addr: :10053
  handler:
    type: dns
  listener:
    type: dns
  forwarder:
    nodes:
    - name: target-0
      addr: 1.1.1.1
      bypass: bypass-0
    - name: target-1
      addr: 8.8.8.8
      bypass: bypass-1
bypasses:
- name: bypass-0
  matchers:
  - example.org
- name: bypass-1
  matchers:
  - example.com
```

--------------------------------

### Equivalent command for port forwarding

Source: https://gost.run/tutorials/protocols/grpc

This single command shows the equivalent configuration for the port forwarding setup above: it directly starts a SOCKS5 proxy over gRPC on port 8443.

```bash
gost -L socks5+grpc://:8443
```

--------------------------------

### CLI: Start file server with dir option

Source: https://gost.run/en/tutorials/file

Starts a file server on port 8080 serving the directory `/path/to/dir`. The `dir` option specifies the local directory, defaulting to the current working directory.

```bash
gost -L file://:8080?dir=/path/to/dir

```

--------------------------------

### HTTP CONNECT Server - CLI

Source: https://gost.run/en/tutorials/http-tunnel

Starts a simple HTTP proxy server with authentication on port 8080.

```bash
gost -L http://user:pass@:8080
```

--------------------------------

### PHT over TLS - Command Line

Source: https://gost.run/tutorials/protocols/pht

Starts a PHT listener over TLS (phts) on port 8443, with explicit path settings. TLS configuration is referenced from the TLS configuration guide.

```bash
gost -L "http+phts://:8443?authorizePath=/authorize&pushPath=/push&pullPath=/pull"
```

--------------------------------

### Websocket Secure (wss) listener command-line configuration

Source: https://gost.run/en/reference/listeners/ws

Starts a GOST service with the Websocket Secure listener using the command line. The example listens on port 8443 with the path /ws.

```bash
gost -L http+wss://:8443?path=/ws

```

--------------------------------

### File Format for Max Conn Limiter

Source: https://gost.run/en/concepts/limiter

Example file content for a max connection limiter. Lines starting with `#` are comments. Each line follows the format `ip/cidr limit`, with `$` for default and `$$` for default input/output.

```text
# ip/cidr  limit

$ 1000
$$ 100
192.168.1.1  200
192.168.0.0/16  50

```

--------------------------------

### DNS查询example.com(ipv4)

Source: https://gost.run/tutorials/dns

使用dig命令查询example.com的A记录，端口10053。

```bash
dig -p 10053 example.com
```

```text
;; QUESTION SECTION:
;example.com.               IN  A

;; ANSWER SECTION:
example.com.        10610   IN  A   93.184.216.34
```

--------------------------------

### File Format for Bandwidth Limiter

Source: https://gost.run/en/concepts/limiter

Example file content for a bandwidth limiter. Lines starting with `#` are comments. Each line follows the format `ip/cidr input output(optional)`, with `$` for default and `$$` for default input/output.

```text
# ip/cidr  input  output(optional)

$ 100MB  200MB
$$ 10MB
192.168.1.1  1MB 10MB
192.168.0.0/16  512KB  1MB

```

--------------------------------

### Start SNI handler via command line

Source: https://gost.run/reference/handlers/sni

Runs an SNI handler listening on port 8080 using the -L flags. This one-line command is the quickest way to get the proxy running.

```text
gost -L sni://:8080

```

--------------------------------

### 配置文件配置DNS代理服务分流器

Source: https://gost.run/blog/2022/bypass

使用YAML配置文件配置DNS代理服务，设置服务级分流器bypass-0，匹配example.com，当查询example.com时返回空结果。

```yaml
services:
- name: service-0
  addr: :10053
  bypass: bypass-0
  handler:
    type: dns
  listener:
    type: dns
  forwarder:
    nodes:
    - name: target-0
      addr: 1.1.1.1
bypasses:
- name: bypass-0
  matchers:
  - example.com
```

--------------------------------

### File Format for Request Rate Limiter

Source: https://gost.run/en/concepts/limiter

Example file content for a request rate limiter. Lines starting with `#` are comments. Each line follows the format `ip/cidr rate(r/s)`, with `$` for default and `$$` for default input/output.

```text
# ip/cidr  rate(r/s)

$ 100
$$ 10
192.168.1.1  20
192.168.0.0/16  50

```

--------------------------------

### Create redsocks configuration file

Source: https://gost.run/en/blog/2015/redsocks

Creates redsocks.conf with base and redsocks settings, including the SOCKS5 proxy details.

```text
base {
    log_debug = on;
    log_info = on;
    log = "file:/tmp/reddi.log";
    daemon = on;
    redirector = iptables;
}

redsocks {
    local_ip = 0.0.0.0;
    local_port = 31338;
    ip = 127.0.0.1;
    port = 8899;
    type = socks5;
}

```

--------------------------------

### Redirect UDS to TCP service

Source: https://gost.run/tutorials/unix

Redirect a local Unix domain socket to a TCP service. The command starts a UDS listener on gost.sock and forwards to 192.168.1.1:8080. The YAML configuration defines the same setup with a chain.

```bash
gost -L unix://gost.sock -F tcp://192.168.1.1:8080

```

```yaml
services:
- name: service-0
  addr: gost.sock
  handler:
    type: unix
    chain: chain-0
  listener:
    type: unix
chains:
- name: chain-0
  hops:
  - name: hop-0
    nodes:
    - name: node-0
      addr: 192.168.1.1:8080
      connector:
        type: tcp
      dialer:
        type: tcp

```

--------------------------------

### Run redsocks

Source: https://gost.run/en/blog/2015/redsocks2

Start redsocks with the configuration file. Verify it's running by checking if it's listening on port 31338 using netstat.

```bash
redsocks -c redsocks.conf

```

```bash
netstat -tlnp

```

--------------------------------

### Forwarder CLI example

Source: https://gost.run/en/concepts/selector

CLI command to start a TCP forwarder with a node group and selector options. The command forwards traffic from :8080 to either :8081 or :8082 using round-robin strategy, with maxFails=1 and failTimeout=30s.

```bash
gost -L "tcp://:8080/:8081,:8082?strategy=round&maxFails=1&failTimeout=30s"
```

--------------------------------

### 命令行配置DNS代理服务分流器

Source: https://gost.run/blog/2022/bypass

使用命令行参数配置DNS代理服务，设置分流器bypass=example.com，当查询example.com时返回空结果。

```bash
gost -L dns://:10053/1.1.1.1?bypass=example.com
```

--------------------------------

### PHT Data Channel - CLI

Source: https://gost.run/en/tutorials/protocols/http3

Starts an HTTP3 data channel listener using PHT mode on port 8443 with custom paths for authorization, push, and pull. Use this CLI command for quick setup.

```bash
gost -L "h3://:8443?authorizePath=/authorize&pushPath=/push&pullPath=/pull"
```

--------------------------------

### 服务上的分流器 - 命令行配置

Source: https://gost.run/blog/2022/bypass

使用命令行参数设置 HTTP 代理服务的黑名单分流器，匹配 example.com 的请求会被拒绝。

```bash
gost -L http://:8080?bypass=example.com
```

--------------------------------

### Start HTTP/3 listener via command line (gost -L http+h3://:8080)

Source: https://gost.run/reference/listeners/http3

Launches a GOST proxy with an HTTP/3 listener on UDP port 8080 using the command-line configuration format.

```bash
gost -L http+h3://:8080

```