Small Sharp Software Tools

Harness the Combinatoric Power of Command-Line Tools and Utilities

../Tutorials

Forward Services with Bore

Bash Homebrew tools

Published February 20, 2023 and last verified on March 10, 2024

If you need to make a local network service available to the outside world, you can use tools like localtunnel or ngrok. bore is a small, open-source alternative that lets you run both a client and server. It’s efficient, small, and fast. More importantly, it has no dependencies, so you don’t need a language runtime installed to use it.

In this tutorial you’ll forward a service using bore and its free public server, and then you’ll explore how to set up your own server with an authentication secret.

What You Need

  • To set up bore on macOS using Homebrew, you’ll need Homebrew installed, which you can do by following the Install Homebrew tutorial.
  • A service to forward, such as a web application. If you don’t have one, you’ll create one in this tutorial using Netcat.
    • Install netcat with your package manager on Linux, or Homebrew on macOS.

Installing Bore

The bore CLI tool is a single binary that includes both a client and a server.

On macOS, install bore with Homebrew using the following command:

brew install bore-cli

For other languages, download the binary from the releases page and copy the file to a location on your PATH.

Once you have bore installed, you can forward ports to a free public server.

Forward a Service to bore.pub

bore.pub is a hosted server that bore can forward to so you don’t need to self-host the server. It’s great for testing.

First, you’ll need a minimal server. You can do this an existing web server you’re using, but for a quick test, you can use Netcat.

Create a file called index.http that contains an HTTP response, with the header and body separated by a single line:

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Server: netcat

<!DOCTYPE html>
<html>
  <title>Bore test</title>
  <body>
    <h1>Hello from my local network.</h1>
  </body>
</html>

Now use an infinite loop in your shell to serve the file with Netcat on port 3000:

while true; do cat index.http | nc -l 3000; done

This starts Netcat listening on port 3000. Incoming connections will serve the HTTP response in index.http.

In another terminal, test the service to ensure it works using curl:

curl -i localhost:3000

You’ll see the response in the terminal:

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Server: netcat

<!DOCTYPE html>
<html>
  <title>Bore test</title>
  <body>
    <h1>Hello from my local network.</h1>
  </body>
</html>

Now use bore to forward the port to the free public bore.pub server using the following command::

bore local 3000 --to bore.pub

The client starts and forwards the port, displaying the external port it’s listening on:

2023-02-20T20:21:31.767961Z  INFO bore_cli::client: connected to server remote_port=35429
2023-02-20T20:21:31.768010Z  INFO bore_cli::client: listening at bore.pub:35429

Bore assigns a different remote port on every run if you don’t specify one.

In yet another Terminal window, connect to bore.pub:your_port using curl:

curl -i bore.pub:your_port

You’ll see your server’s response again.

Switch to the window running bore. The bore CLI tool also prints a log message showing the connection details:

2023-02-20T20:21:50.704301Z  INFO proxy{id=ea685f15-7579-4d49-91eb-6b835082cc45}: bore_cli::client: new connection
2023-02-20T20:21:50.748621Z  INFO proxy{id=ea685f15-7579-4d49-91eb-6b835082cc45}: bore_cli::client: connection exited

Press CTRL+C to stop bore.

Using the public bore.pub server works in a pinch, but you can create your own server too.

Running Your Own Server

For more secure environments, you may want to run your own server instead of relying on the public bore.pub service. The bore CLI includes the server component.

On a remote machine, install bore and start it with the following command:

bore server

This starts the server listening on port 7835:

2023-02-20T20:28:39.642766Z  INFO bore_cli::server: server listening addr=0.0.0.0:7835

On your local machine, establish the client connection:

bore local 3000 --to your_remote_server

You can specify the port using the -p option:

bore local 3000 --to your_remote_server -p 9999

Anyone using bore can use your service. If you want to restrict it, you can start the service with a secret that the client needs to supply.

Run the server with the -s option:

bore server -s 12345

This starts bore with the super secret password of 12345 which you supply when you try to use the client:

bore local 3000 --to your_remote_server -p 9999 -s 12345

Secrets passed to commands are often visible to people looking at process lists or history, so you can also use the BORE_SECRET environment variable. If this variable is set, bore will use it automatically. Of course, you’ll need to set this variable on the client and the server.

Conclusion

bore gives you a fast way to share a local service with others across the Internet without needing to configure firewall rules or set up complex tooling. It provides a lightweight alternative to other tools that have additional dependencies.