User

User configuration is where authentication data and per-user policy come together.

Each user record can carry credentials, matching rules, ACLs, rate limits, and protocol-specific overrides.

name

required, type: username

Username.

token

required, type: mix

Authentication token used for this user.

This config option will only be used by the following user groups:

The token can take one of the following forms:

  • null

    null disables password-token authentication.

    Note

    This is different from not setting token value, which means forbid the user.

    Added in version 1.7.20.

  • str

    String in Unix crypt(5) format.

  • map

    The type key selects the actual token subtype.

    • fast_hash

      Custom fast-hash format. It uses a salt plus one or more of md5, sha1, and blake3. The hash is weak but fast. The values for salt, md5, sha1, and blake3 must be hex-encoded ASCII strings.

    • xcrypt_hash

      Requires a value key containing a valid crypt(5) string.

The currently supported crypt(5) methods are: md5, sha256, sha512.

match_by_facts

optional, type: facts_match_value | seq

Authentication facts that match this user.

This config option will only be used by the following user groups:

default: not set

Added in version 1.13.0.

expire

optional, type: rfc3339 datetime str

Time at which the user is considered expired. The check interval is controlled by refresh interval in group config.

default: not set

block_and_delay

optional, type: humanize duration

Blocks the user and delays the error response by the configured duration.

The response code for blocked user will be forbidden instead of auth failed.

default: not set

ingress_network_filter

optional, type: ingress network acl rule

Ingress network filter for clients.

If a server is chained behind a PROXY Protocol server, the client address used here is the one carried in the PROXY Protocol message.

This ACL is checked before the anonymous-auth path is considered, so the client receives an authentication failure and anonymous-user forbidden metrics are not incremented.

default: not set

Added in version 1.7.20.

proxy_request_filter

optional, type: proxy request acl rule

Proxy request types this user is allowed to use.

default: not set

dst_host_filter_set

optional, type: dst host acl rule set

Destination-host filter for each request. It does not apply to UDP ASSOCIATE tasks.

default: not set

dst_port_filter

optional, type: exact port acl rule

Destination-port filter for each request. It does not apply to UDP ASSOCIATE tasks.

default: not set

http_user_agent_filter

optional, type: user agent acl rule

Filter for the HTTP User-Agent header.

Note

This only applies to layer-7 http traffic, including http forward and https forward.

default: not set

tcp_connect

optional, type: tcp connect

User-level TCP connect parameters. These apply to direct escapers and are further constrained by escaper-level settings.

default: not set

tcp_sock_speed_limit

optional, type: tcp socket speed limit

Per-TCP-socket speed limit.

default: no limit

tcp_conn_speed_limit

deprecated

Changed in version 1.11.8: deprecated, use tcp_sock_speed_limit instead

tcp_conn_limit

deprecated

Changed in version 1.11.8: deprecated, use tcp_sock_speed_limit instead

udp_sock_speed_limit

optional, type: udp socket speed limit

Per-UDP-socket speed limit.

default: no limit

udp_relay_speed_limit

deprecated

Changed in version 1.11.8: deprecated, use udp_sock_speed_limit instead

udp_relay_limit

deprecated

Changed in version 1.11.8: deprecated, use udp_sock_speed_limit instead

tcp_all_upload_speed_limit

optional, type: global stream speed limit

Process-level upload speed limit for all client-side TCP connections.

This will only count in the data that will be forwarded.

default: no limit

Added in version 1.9.6.

tcp_all_download_speed_limit

optional, type: global stream speed limit

Process-level download speed limit for all client-side TCP connections.

This will only count in the data received from upstream.

default: no limit

Added in version 1.9.6.

udp_all_upload_speed_limit

optional, type: global datagram speed limit

Process-level upload speed limit for all client-side UDP connections.

This will only count in the data that will be forwarded.

default: no limit

Added in version 1.9.6.

udp_all_download_speed_limit

optional, type: global datagram speed limit

Process-level download speed limit for all client-side UDP connections.

This will only count in the data received from upstream.

default: no limit

Added in version 1.9.6.

tcp_remote_keepalive

optional, type: tcp keepalive

TCP keepalive configuration for the remote TCP socket.

The tcp keepalive set in user config will only be taken into account in Direct type escapers.

default: no keepalive set

tcp_remote_misc_opts

optional, type: tcp misc sock opts

Miscellaneous TCP socket options for the remote TCP socket.

The user level TOS and Mark config will overwrite the one set at escaper level. Other fields will be limited to the smaller ones.

default: not set

udp_remote_misc_opts

optional, type: udp misc sock opts

Miscellaneous UDP socket options for the remote UDP socket.

The user level TOS and Mark config will overwrite the one set at escaper level. Other fields will be limited to the smaller ones.

default: not set

tcp_client_misc_opts

optional, type: tcp misc sock opts

Miscellaneous TCP socket options for the client TCP socket before the task enters the connection stage.

The user level TOS and Mark config will overwrite the one set at escaper level. Other fields will be limited to the smaller ones.

default: not set

udp_client_misc_opts

optional, type: udp misc sock opts

Miscellaneous UDP socket options for the client UDP socket.

The user level TOS and Mark config will overwrite the one set at server level. Other fields will be limited to the smaller ones.

default: not set

http_upstream_keepalive

optional, type: http keepalive

HTTP keepalive configuration at the user level.

default: set with default value

http_rsp_header_recv_timeout

optional, type: humanize duration

Custom HTTP response-header receive timeout for this user.

This will overwrite:

This will be overwritten by:

default: not set

Added in version 1.9.0.

tcp_conn_rate_limit

deprecated, alias: tcp_conn_limit_quota

Changed in version 1.13.0: deprecated, use connection_rate_limit instead

connection_rate_limit

optional, type: rate limit quota

Rate limit for new client-side connections.

The same connection used for different users will be counted for each of them.

default: no limit

Added in version 1.13.0.

request_rate_limit

optional, type: rate limit quota

Rate limit for requests.

default: no limit, alias: request_limit_quota

request_max_alive

optional, type: usize, alias: request_alive_max

Maximum number of active requests for this user.

Even if not set, the max alive requests should not be more than usize::MAX.

default: no limit

resolve_strategy

optional, type: resolve strategy

Custom resolve strategy for this user, constrained by the strategy allowed by the escaper. Not all escapers support this, see the documentation for each escaper for more info.

default: no custom resolve strategy is set

resolve_redirection

optional, type: resolve redirection

DNS redirection rules for this user.

default: not set

log_rate_limit

optional, type: rate limit quota

Rate limit for log requests.

default: no limit, alias: log_limit_quota

log_uri_max_chars

optional, type: usize

Maximum number of URI characters recorded in logs.

If set, this will override the one set in server level.

If not set, the one in server level will take effect.

Passwords embedded in URIs are replaced with xyz before logging.

default: not set

task_idle_max_count

optional, type: usize

The task is closed once the idle check reports IDLE this many times.

This will overwrite the one set at server side, see server task_idle_max_count.

The idle-check interval can only be configured at the server level, see server task_idle_check_interval.

default: not set

Changed in version 1.11.3: change default from 1 to not set

socks_use_udp_associate

optional, type: bool

Controls whether SOCKS UDP ASSOCIATE is used instead of the simplified UDP CONNECT mode.

default: false

audit

optional, type: user audit

Audit configuration for this user.

default: set with default values

explicit_sites

optional, type: seq of user site

Explicit per-site configuration for this user.

egress_path_id_map

optional, type: string id egress path value map

Per-escaper string id values for this user. Each map key is the target escaper name.

Example:

egress_path_id_map:
  direct-egress: hk-v4
  proxy-pool: corp-exit-2

Added in version 1.9.2.

egress_path_value_map

optional, type: json value egress path value map

Per-escaper json value values for this user. Each map key is the target escaper name.

Example:

egress_path_value_map:
  direct-float:
    ip: 203.0.113.11
    id: temp-egress
  proxy-chain:
    addr: proxy-1.example.net:3128
    resolve_sticky_key: session-a

Added in version 1.9.2.