Guide to Configuring frp Reverse Proxy Service in ServBay

frp (Fast Reverse Proxy) is a high-performance reverse proxy application that allows you to securely expose your local network services to the public internet. ServBay integrates the frp client (frpc), enabling you to connect to your own deployed frp server (frps), and access local sites hosted in ServBay via custom domains. This setup gives you full control over the tunnel server.

This guide provides step-by-step instructions on configuring the frp client within ServBay and connecting to your frps server.

Overview

Unlike other hosted tunnel services in ServBay, using frp requires you to pre-deploy and configure the frps server on your own server. ServBay acts as the frpc client, forwarding local site traffic through the frps server to the public network. This mode is ideal for developers who demand greater customization and control over their tunnels.

Use Cases

• Full control over the tunnel server: You have complete authority over the configuration, security, and performance of the frps server.
• Use custom domains and SSL: Flexibly configure any domain you own for your local projects and integrate with ServBay-managed ACME SSL certificates.
• Advanced networking configurations: frp supports multiple proxy types and advanced configurations to meet complex needs.
• Private deployment: Ideal when you don't want to rely on third-party tunneling services.

Prerequisites

1. ServBay Installed: Ensure your macOS system has ServBay successfully installed and running.
2. Self-hosted frps server:
   • You must have a publicly accessible server where you have successfully deployed and are running the frps service.
   • Note down the public IP address or domain name of your frps server.
   • Record the bindPort (the port for frp client-server communication) and token (authentication token) set in the frps server's configuration file (frps.toml or frps.ini).
3. Domain Name and DNS Configuration:
   • You need a public domain (e.g., your-frp-server.com) and must create an A record in DNS pointing to your frps server's public IP. This domain will be used to access your local site later.
4. ACME SSL Certificate in ServBay:
   • To enable HTTPS access to your external domain, you need to apply for an ACME SSL certificate for that external domain in ServBay's SSL Certificates section in advance. For example, if you plan to use project.your-frp-server.com for accessing your local site, apply for a certificate for project.your-frp-server.com.
5. Multiple Subdomains and SSL Certificates:
   • If you want to use multiple subdomains without adding multiple DNS A records, you can use a wildcard domain: add an A record for *.your-frp-server.com pointing to your frps server's public IP. Also, in ServBay, apply for an ACME SSL certificate covering the wildcard domain (when applying, enter your-frp-server.com, *.your-frp-server.com in the Domain field—make sure the wildcard entry is last and separate each by a comma). Afterwards, you can add any second-level domain in ServBay and share a single SSL certificate, without managing numerous A records.
   • With this method in ServBay, you can offer external access via domains such as company-project.your-frp-server.com, personal.your-frp-server.com, and customer-1.your-frp-server.com, without repetitive setup.

Step-by-Step Instructions

1. Install the frp Package in ServBay

1. Open the ServBay application.
2. In the left sidebar, click on Packages.
3. In the package list, find frp.
4. Click the install button next to frp.
5. After installation, the frp service may fail to start due to a lack of configuration—this is expected.

2. Prepare Your frps Server and Configuration

You need to independently install and run frps on your public server. ServBay can generate a basic frps.toml (recommended for newer frp versions) configuration template to help you get started:

1. In ServBay, navigate to Tunnel -> frp.

2. Locate and click the dropdown or expand icon next to frp server config (frps.toml). ServBay will display a sample frps.toml config file, similar to:

   # The frps configuration file automatically generated by ServBay
   # is intended for direct use on the server.
   # Please adjust the configuration parameters according
   # to your specific needs.
   bindPort = 12345
   auth.method = "token"
   auth.token = "myserverpassword"
   
   vhostHTTPPort = 80
   vhostHTTPSPort = 443
   
   log.to = "/tmp/frps.log"
   log.level = "info"
   log.maxDays = 3
   log.disablePrintColor = true
   
   # For newer frps versions (e.g., 0.52.0+), configure the Dashboard using webServer.port, webServer.addr, webServer.user, and webServer.password
   # webServer.port = 7500
   # webServer.addr = "0.0.0.0"
   # webServer.user = "admin"
   # webServer.password = "admin_password"

3. Important Configuration Notes:

   • bindPort: The port for frpc to communicate with frps. Ensure this port is open in your server's firewall. It is highly recommended to protect this port on your frps server, for example by using firewall rules to restrict incoming IPs.
   • auth.method = "token" and auth.token: Used for authenticating client connections. Be sure to change to your own strong password.
   • vhostHTTPPort = 80 and vhostHTTPSPort = 443: The ports frps will use to listen for HTTP and HTTPS virtual host requests.
     • [Key Point] ServBay is optimized for scenarios where the frps server uses ports 80 and 443 directly for vhostHTTPPort and vhostHTTPSPort. This allows seamless pass-through of ACME SSL certificates issued locally in ServBay to frps for client access.
     • If your frps server cannot use ports 80/443 directly (e.g., occupied by other services) and must use alternative ports (such as 8080/8443), you must deploy an additional reverse proxy server (like Nginx or Caddy) in front of frps. The reverse proxy listens on public ports 80/443 and forwards traffic to the actual vhostHTTPPort and vhostHTTPSPort of frps. In this setup, SSL certificates will be handled by the reverse proxy, not through ServBay pass-through.
   • log.to: The path to the frps log file.
   • Dashboard settings (e.g., webServer.port): For accessing the frps Dashboard UI. Optional.

4. Copy the generated config content to your frps server, save it as frps.toml (or frps.ini, depending on your frp version and preference), and adjust the parameters as needed.

5. Start your frps service.

3. Configure the frp Client in ServBay

Back in the ServBay app, configure the frp client connection parameters:

1. Navigate to Tunnel -> frp.

2. Fill in your frps server details:

   • Server Address: Enter the public domain or IP of your frps server (e.g., my.test.frp.server.host).
   • Server Port: Enter the bindPort you set in frps.toml (e.g., 12345).
   • Auth Token: Enter the auth.token value from your frps.toml (e.g., myserverpassword).

3. Set up tunnel mapping rules:

   • Local Domain: Select from the dropdown which local ServBay website you'd like to expose via frp (e.g., servbay.demo).
   • External Domain: Enter the domain you want public users to access your local site with (e.g., test.ks.do). This domain's DNS A record should already point to your frps server's IP.
     • Note: Unlike other tunnels ServBay supports (such as Ngrok or Cloudflared), you must enter the full domain name here.
   • ACME Certificates: Select from the dropdown the ACME SSL certificate you have applied for in ServBay for the above external domain (e.g., choose the certificate for test.ks.do).
     • Important: If you want HTTPS access for the external domain, you must select the correct certificate here. ServBay will pass this certificate information to frpc, which, after connecting with frps, will ensure frps serves HTTPS requests for the External Domain using that certificate. This means you do not need to configure a separate SSL certificate for the external domain directly on your frps server; ServBay handles this.

4. Add More Tunnels:

   • To create tunnels for multiple local sites or external domains, click the + button next to an existing tunnel entry to add a new tunnel configuration.

4. Save Configuration and Start frp Service

1. After completing all settings, click the Save button at the bottom right corner.
2. ServBay will save the frpc configuration and attempt to start the frp service.
3. Monitor the status indicator next to frp under Tunnel. If configured correctly and frpc connects successfully to frps, the indicator should turn green, showing the service is running.
4. Verify Access:
   • You should now be able to access your local site from the public internet via the configured External Domain (e.g., https://test.ks.do).
   • Click the copy or browser icon next to the external domain to test access.

Notes

• Deployment and Maintenance of frps Server: You are solely responsible for installing, configuring, hardening, and maintaining the frps server.
• Security for frps bindPort: Always use a strong auth.token, and consider using firewall rules to restrict access to the bindPort (e.g., only specific IPs or ranges).
• Choice of vhostHTTPPort and vhostHTTPSPort:
  • Strongly recommended: let frps listen on ports 80 and 443 directly as virtual host ports. This makes it easiest to take advantage of ServBay’s ACME SSL pass-through functionality.
  • If frps must use ports other than 80/443, you will need an additional reverse proxy (such as Nginx or Caddy) running in front of frps listening on 80/443 and forwarding traffic to the actual vhost ports. In this setup, SSL certificates are handled by the front-end proxy.
• ACME Certificate Requirement: To enable HTTPS for your external domain, you must apply for an ACME certificate for that domain in ServBay and select it correctly in the frp configuration.
• DNS Propagation: Ensure the DNS A record of your External Domain correctly points to the frps server's IP and has propagated globally.

Frequently Asked Questions (FAQ)

• Q: The frp service in ServBay fails to start, and the status indicator is red or orange. What should I do?
  • A: Check the frp configuration in ServBay: ensure Server Address, Server Port, and Auth Token exactly match the bindPort and auth.token in your frps.toml. Verify your frps server is running and that the bindPort is accessible from the ServBay machine (check firewall rules). Check the frp service logs for detailed error information.
• Q: I can access through External Domain, but only over HTTP, not HTTPS?
  • A: Make sure you have selected the correct ACME certificate for the External Domain in ServBay's frp configuration. Also, ensure that your frps.toml sets vhostHTTPSPort to the port on which frps actually listens for HTTPS requests (recommended: 443).
• Q: My frps server must use non-80/443 ports for virtual hosts. How do I configure SSL?
  • A: You need to set up a front-end reverse proxy (such as Nginx or Caddy) on your frps server. This reverse proxy should listen on public ports 80/443, obtain and configure SSL certificates (these can be managed independently from ServBay), and then forward HTTPS traffic (decrypted or encrypted, depending on configuration) to the actual vhostHTTPSPort of frps. In this scenario, the ACME Certificates field in ServBay’s frp settings is not used for serving public SSL—SSL is handled by your front-end proxy (Nginx or Caddy).
• Q: The frps.toml generated by ServBay is different from my existing frps.ini?
  • A: frp is migrating from .ini to .toml configuration. The template from ServBay uses the .toml format. If your frps version is older or you prefer .ini, refer to the official frp documentation for conversion or configuration. The core parameters have the same meaning.

Summary

By integrating the frp client, ServBay provides macOS developers who require advanced custom NAT traversal solutions with a powerful toolkit. By self-hosting your frps server and leveraging ServBay’s streamlined frpc configuration and ACME SSL certificate management, you can securely and flexibly share your local development sites with the public internet. Be sure to configure frps and frpc parameters carefully, especially ports and security settings, to ensure stability and safety for your service.