DOCSEARCHbyAlgolia
Submit Docs

frp Fast Reverse Proxy

repository·dev·Indexed 13 days ago

https://github.com/fatedier/frp

A fast reverse proxy that exposes local servers behind a NAT or firewall to the Internet. It supports TCP, UDP, HTTP, and HTTPS protocols, featuring P2P connect mode (XTCP), secret TCP (STCP) for private access, and plugin support for Unix domain sockets and static file servers. Since v0.52.0, it supports TOML, YAML, and JSON configuration formats.

Tokens
20.8K
Snippets
81
Records
115
Agent score
98%

What's inside frp

  1. What is frp?

    dev

    frp is a fast reverse proxy designed to expose local servers located behind a NAT or firewall to the Internet.

    Key capabilities include:

    • Protocol Support: Supports TCP, UDP, HTTP, and HTTPS.
    • Domain Name Forwarding: Enables requests to be forwarded to internal services via domain names.
    • P2P Mode: Offers a Peer-to-Peer connect mode for direct connections.

  2. What is frp and its core features

    dev

    frp is a high-performance reverse proxy application focused on intranet penetration. It allows you to expose services located in a private network (LAN) to the public internet by using a middleman node with a public IP address.

    Key features include:

    • Protocol Support: Supports TCP, UDP, HTTP, HTTPS, and P2P communication.
    • Transport Protocols: Supports TCP, QUIC, KCP, and Websocket for client-server communication.
    • Efficiency: Uses TCP connection stream multiplexing to carry multiple requests over a single connection, reducing latency and connection establishment time.
    • Load Balancing: Supports load balancing between proxy groups.
    • Port Multiplexing: Multiple services can be exposed through a single server port.
    • P2P Communication: Supports Peer-to-Peer mode where traffic does not pass through the server, maximizing bandwidth utilization.
    • Extensibility: Includes native client plugins (e.g., static file viewing, HTTPS/HTTP protocol conversion, HTTP/SOCKS5 proxy) and a highly extensible server-side plugin system.
    • Management: Provides UI pages for both server and client.

  3. Explore related frp projects

    dev

    Beyond the core frp repository, you can explore these specialized projects:

    • gofrp/plugin: A repository containing various plugins implemented via the frp extension mechanism for custom scenarios.
    • gofrp/tiny-frpc: A lightweight version of the frp client (minimum ~3.5MB) implemented using the SSH protocol. It supports common features and is ideal for resource-constrained devices.

  4. What is the SSH Tunnel Gateway?

    dev

    The SSH Tunnel Gateway allows frps to act as an SSH server that supports TCP protocol proxying using the SSH -R (reverse proxy) protocol.

    Unlike standard frp usage, this mode does not rely on frpc. Instead, a standard SSH client is used to establish the connection. This is useful for performing basic reverse proxying by connecting to frps via an SSH client when you do not want to or cannot run the frpc binary on the client machine.

  5. Implement the Server Plugin RPC interface

    dev

    Your external server must handle POST requests at a configured HTTP path.

    Request Format:

    • URL: POST /<path>?version=<version>&op=<operation>
    • Header: X-Frp-Reqid (used for tracing)
    • Body: A JSON object containing the operation details in a content field.

    Response Modes:

    1. Reject operation: Return a non-200 HTTP status code OR a JSON body with "reject": true and a "reject_reason" string.
    2. Allow and keep original: Return a JSON body with "reject": false and "unchange": true.
    3. Allow and modify content: Return a JSON body with "unchange": "false" (or omit) and a "content" field containing the new data.
    // Example Reject Response
{
    "reject": true,
    "reject_reason": "invalid user"
}

// Example Allow and Keep Original
{
    "reject": false,
    "unchange": true
}

// Example Allow and Modify
{
    "unchange": "false",
    "content": {
        "...": "replaced content"
    }
}

  6. Configure Load Balancing with Groups

    dev

    Load balancing is supported for tcp, http, and tcpmux types using the group concept. Multiple proxies assigned to the same loadBalancer.group will receive connections randomly.

    Example frpc.toml:

    [[proxies]]
name = "test1"
type = "tcp"
localPort = 8080
remotePort = 80
loadBalancer.group = "web"
loadBalancer.groupKey = "123"

[[proxies]]
name = "test2"
type = "tcp"
localPort = 8081
remotePort = 80
loadBalancer.group = "web"
loadBalancer.groupKey = "123"

    Note: For tcp type, remotePort in the same group must be identical. For http type, customDomains, subdomain, and locations must be identical.

  7. Using Metadata with Server Plugins

    dev

    Metadata allows you to pass custom key-value pairs to your server plugin. There are two levels of metadata:

    1. Global Metadata: Defined in frpc.toml under metadatas. These are sent in the Login operation under the metas key, and in all other operations under user.metas.
    2. Proxy Metadata: Defined in frpc.toml under a specific proxy's metadatas. These are sent only during the NewProxy operation under the metas key.

    Example frpc.toml configuration:

    serverAddr = "127.0.0.1"
serverPort = 7000
user = "fake"
metadatas.token = "fake"
metadatas.version = "1.0.0"

[[proxies]]
name = "ssh"
type = "tcp"
localPort = 22
remotePort = 6000
metadatas.id = "123"
    # frpc.toml
serverAddr = "127.0.0.1"
serverPort = 7000
user = "fake"
metadatas.token = "fake"
metadatas.version = "1.0.0"

[[proxies]]
name = "ssh"
type = "tcp"
localPort = 22
remotePort = 6000
metadatas.id = "123"

  8. Enable experimental features using feature gates

    dev

    frp uses feature gates to allow users to test experimental features before they reach a stable state. Features progress through three lifecycle stages:

    1. ALPHA: Disabled by default; may be unstable.
    2. BETA: May be enabled by default; more stable but still evolving.
    3. GA (Generally Available): Enabled by default; ready for production use.

    To enable a feature gate, add it to your configuration file using the featureGates key.

    featureGates = { VirtualNet = true }

  9. Authenticate clients using Token or OIDC

    dev

    frp supports two main authentication methods. You must configure auth.method in both frpc.toml and frps.toml.

    Token Authentication

    Set auth.method = "token". Both sides must share the same auth.token.

    File-based token source: You can read the token from a file instead of hardcoding it:

    # frpc.toml
auth.method = "token"
auth.tokenSource.type = "file"
auth.tokenSource.file.path = "/path/to/token/file"

    OIDC Authentication

    Set auth.method = "oidc". This uses the Client Credentials Grant flow.

    Server configuration (frps.toml):

    auth.method = "oidc"
auth.oidc.issuer = "https://example-oidc-issuer.com/"
auth.oidc.audience = "https://oidc-audience.com/.default"

    Client configuration (frpc.toml):

    auth.method = "oidc"
auth.oidc.clientID = "YOUR_CLIENT_ID"
auth.oidc.clientSecret = "oidc_secret"
auth.oidc.audience = "https://oidc-audience.com/.default"
auth.oidc.tokenEndpointURL = "https://example-oidc-endpoint.com/oauth2/v2.0/token"

  10. Related projects and specialized versions

    dev

    Beyond the main frp repository, there are specialized projects for different use cases:

    • gofrp/plugin: A dedicated repository for frp plugins, containing various extensions to meet customized needs.
    • gofrp/tiny-frpc: A lightweight version of the frp client based on the SSH protocol. It is approximately 3.5MB in size and supports common features, making it ideal for resource-constrained devices.

  11. Understand frp Architecture

    dev
    frp operates as a reverse proxy system. While the specific implementation details are contained in the full documentation, the architecture is designed to facilitate intranet penetration by bridging external requests to internal services through a server-client model.

  12. Enable Dynamic Proxy Management (Store)

    dev

    You can dynamically create, update, and delete proxies and visitors at runtime via the Web UI or API without restarting frpc. To enable this, specify a path for the store configuration to persist settings to disk. Store entries take precedence over configuration file entries if names conflict.

    [store]
path = "./db.json"