# frp
[![Build Status](https://circleci.com/gh/fatedier/frp.svg?style=shield)](https://circleci.com/gh/fatedier/frp)
[![GitHub release](https://img.shields.io/github/tag/fatedier/frp.svg?label=release)](https://github.com/fatedier/frp/releases)
[README](README.md) | [中文文档](README_zh.md)
<h3 align="center">Gold Sponsors</h3>
<!--gold sponsors start-->
<p align="center">
<a href="https://workos.com/?utm_campaign=github_repo&utm_medium=referral&utm_content=frp&utm_source=github" target="_blank">
<img width="300px" src="https://raw.githubusercontent.com/fatedier/frp/dev/doc/pic/sponsor_workos.png">
</a>
</p>
<!--gold sponsors end-->
<h3 align="center">Silver Sponsors</h3>
* Sakura Frp - 欢迎点击 "加入我们"
## What is frp?
frp is a fast reverse proxy to help you expose a local server behind a NAT or firewall to the Internet. As of now, it supports **TCP** and **UDP**, as well as **HTTP** and **HTTPS** protocols, where requests can be forwarded to internal services by domain name.
frp also has a P2P connect mode.
## Table of Contents
<!-- vim-markdown-toc GFM -->
* [Development Status](#development-status)
* [Architecture](#architecture)
* [Example Usage](#example-usage)
* [Access your computer in LAN by SSH](#access-your-computer-in-lan-by-ssh)
* [Visit your web service in LAN by custom domains](#visit-your-web-service-in-lan-by-custom-domains)
* [Forward DNS query request](#forward-dns-query-request)
* [Forward Unix domain socket](#forward-unix-domain-socket)
* [Expose a simple HTTP file server](#expose-a-simple-http-file-server)
* [Enable HTTPS for local HTTP(S) service](#enable-https-for-local-https-service)
* [Expose your service privately](#expose-your-service-privately)
* [P2P Mode](#p2p-mode)
* [Features](#features)
* [Configuration Files](#configuration-files)
* [Using Environment Variables](#using-environment-variables)
* [Split Configures Into Different Files](#split-configures-into-different-files)
* [Dashboard](#dashboard)
* [Admin UI](#admin-ui)
* [Monitor](#monitor)
* [Prometheus](#prometheus)
* [Authenticating the Client](#authenticating-the-client)
* [Token Authentication](#token-authentication)
* [OIDC Authentication](#oidc-authentication)
* [Encryption and Compression](#encryption-and-compression)
* [TLS](#tls)
* [Hot-Reloading frpc configuration](#hot-reloading-frpc-configuration)
* [Get proxy status from client](#get-proxy-status-from-client)
* [Only allowing certain ports on the server](#only-allowing-certain-ports-on-the-server)
* [Port Reuse](#port-reuse)
* [Bandwidth Limit](#bandwidth-limit)
* [For Each Proxy](#for-each-proxy)
* [TCP Stream Multiplexing](#tcp-stream-multiplexing)
* [Support KCP Protocol](#support-kcp-protocol)
* [Connection Pooling](#connection-pooling)
* [Load balancing](#load-balancing)
* [Service Health Check](#service-health-check)
* [Rewriting the HTTP Host Header](#rewriting-the-http-host-header)
* [Setting other HTTP Headers](#setting-other-http-headers)
* [Get Real IP](#get-real-ip)
* [HTTP X-Forwarded-For](#http-x-forwarded-for)
* [Proxy Protocol](#proxy-protocol)
* [Require HTTP Basic Auth (Password) for Web Services](#require-http-basic-auth-password-for-web-services)
* [Custom Subdomain Names](#custom-subdomain-names)
* [URL Routing](#url-routing)
* [TCP Port Multiplexing](#tcp-port-multiplexing)
* [Connecting to frps via HTTP PROXY](#connecting-to-frps-via-http-proxy)
* [Range ports mapping](#range-ports-mapping)
* [Client Plugins](#client-plugins)
* [Server Manage Plugins](#server-manage-plugins)
* [Development Plan](#development-plan)
* [Contributing](#contributing)
* [Donation](#donation)
* [GitHub Sponsors](#github-sponsors)
* [PayPal](#paypal)
<!-- vim-markdown-toc -->
## Development Status
frp is under development. Try the latest release version in the `master` branch, or use the `dev` branch for the version in development.
We are working on v2 version and trying to do some code refactor and improvements. It won't be compatible with v1.
We will switch v0 to v1 at the right time and only accept bug fixes and improvements instead of big feature requirements.
## Architecture
![architecture](/doc/pic/architecture.png)
## Example Usage
Firstly, download the latest programs from [Release](https://github.com/fatedier/frp/releases) page according to your operating system and architecture.
Put `frps` and `frps.ini` onto your server A with public IP.
Put `frpc` and `frpc.ini` onto your server B in LAN (that can't be connected from public Internet).
### Access your computer in LAN by SSH
1. Modify `frps.ini` on server A and set the `bind_port` to be connected to frp clients:
```ini
# frps.ini
[common]
bind_port = 7000
```
2. Start `frps` on server A:
`./frps -c ./frps.ini`
3. On server B, modify `frpc.ini` to put in your `frps` server public IP as `server_addr` field:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[ssh]
type = tcp
local_ip = 127.0.0.1
local_port = 22
remote_port = 6000
```
Note that `local_port` (listened on client) and `remote_port` (exposed on server) are for traffic goes in/out the frp system, whereas `server_port` is used between frps.
4. Start `frpc` on server B:
`./frpc -c ./frpc.ini`
5. From another machine, SSH to server B like this (assuming that username is `test`):
`ssh -oPort=6000 test@x.x.x.x`
### Visit your web service in LAN by custom domains
Sometimes we want to expose a local web service behind a NAT network to others for testing with your own domain name and unfortunately we can't resolve a domain name to a local IP.
However, we can expose an HTTP(S) service using frp.
1. Modify `frps.ini`, set the vhost HTTP port to 8080:
```ini
# frps.ini
[common]
bind_port = 7000
vhost_http_port = 8080
```
2. Start `frps`:
`./frps -c ./frps.ini`
3. Modify `frpc.ini` and set `server_addr` to the IP address of the remote frps server. The `local_port` is the port of your web service:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[web]
type = http
local_port = 80
custom_domains = www.example.com
```
4. Start `frpc`:
`./frpc -c ./frpc.ini`
5. Resolve A record of `www.example.com` to the public IP of the remote frps server or CNAME record to your origin domain.
6. Now visit your local web service using url `http://www.example.com:8080`.
### Forward DNS query request
1. Modify `frps.ini`:
```ini
# frps.ini
[common]
bind_port = 7000
```
2. Start `frps`:
`./frps -c ./frps.ini`
3. Modify `frpc.ini` and set `server_addr` to the IP address of the remote frps server, forward DNS query request to Google Public DNS server `8.8.8.8:53`:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[dns]
type = udp
local_ip = 8.8.8.8
local_port = 53
remote_port = 6000
```
4. Start frpc:
`./frpc -c ./frpc.ini`
5. Test DNS resolution using `dig` command:
`dig @x.x.x.x -p 6000 www.google.com`
### Forward Unix domain socket
Expose a Unix domain socket (e.g. the Docker daemon socket) as TCP.
Configure `frps` same as above.
1. Start `frpc` with configuration:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[unix_domain_socket]
type = tcp
remote_port = 6000
plugin = unix_domain_socket
plugin_unix_path = /var/run/docker.sock
```
2. Test: Get Docker version using `curl`:
`curl http://x.x.x.x:6000/version`
### Expose a simple HTTP file server
Browser your files stored in the LAN, from public Internet.
Configure `frps` same as above.
1. Start `frpc` with configuration:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[test_static_file]
type = tcp
remote_port = 6000
pl