Bubble proxy service
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Jonathan Cobb eaadabbb00 wrap install/uninstall in functions, update docs 8 months ago
img WIP. add windows build instructions, try whoami instead of users (not supported on windows) 9 months ago
macos wrap install/uninstall in functions, update docs 8 months ago
src add admin ping handler, complete mac install script, add mac uninstall script 8 months ago
.gitignore getting releases to work on win/mac 9 months ago
BUILD-windows.md use shell script blocks 8 months ago
BUILD.md use shell script blocks 8 months ago
Cargo.lock add admin ping handler, complete mac install script, add mac uninstall script 8 months ago
Cargo.toml add admin ping handler, complete mac install script, add mac uninstall script 8 months ago
LICENSE.md add license file 8 months ago
README-release.md fix typo 8 months ago
README.md wrap install/uninstall in functions, update docs 8 months ago
bubble_release.sh include install/uninstall scripts in macos zip file 8 months ago
dist_jenkins.sh fix install/uninstall locations in dist_jenkins.sh 8 months ago
first_time_ubuntu.sh initial commit 9 months ago
flex_init.sh shell script ergonomics 8 months ago
flex_register.sh prompt for flex router password in flex_register, update docs 9 months ago
set_version.sh pull version from Cargo.toml 9 months ago

README.md

bubble-flexrouter

bubble-flexrouter provides HTTP/HTTPS proxy services for Bubble.

Some websites and apps refuse to respond to requests originating from a cloud IP address. Thus, when a user is connected to their Bubble, some sites and apps will not work.

With flex routing, Bubble can route these requests through a device connected to the Bubble that is running bubble-flexrouter. Now, from the perspective of the website or app, these requests will originate from a “clean” IP, and so a valid response will be sent.

Note that using flex routing does remove some privacy protection - sites and apps that are flex-routed will see one of your device’s real IP addresses.

The Easy Way

The Mac OS Super Easy Way

For Mac OS X, there is a super simple way to install the bubble-flexrouter.

Open a Terminal window and paste the command below, then press Enter:

sudo /bin/bash -c "$(curl -sL https://jenkins.bubblev.org/public/releases/bubble-flexrouter/bubble-flexrouter-macos/latest/install.sh)"

This will download the latest bubble-flexrouter distribution zip file and install it as a LaunchDaemon. You’ll be asked to set the flexrouter password during installation.

After you have run install.sh, continue with this README for information on how to run flex_register.sh to register your flexrouter with a running Bubble.

Mac OS Uninstall

Use the uninstall.sh script to undo everything that install has done.

Running uninstall.sh will unload the LaunchDaemon and remove all files that were installed.

You can perform the uninstall by running:

sudo /bin/bash -c "$(curl -sL https://jenkins.bubblev.org/public/releases/bubble-flexrouter/bubble-flexrouter-macos/latest/uninstall.sh)"

Or by downloading the bubble-flexrouter for Mac OS X distribution, unzipping it, and running the uninstall.sh script therein.

Installing from a distribution zip file

Download the latest bubble-flexrouter release:

The README file found within the above release ZIP file describes how to use the flex_init.sh and flex_register.sh scripts to manage a flex router. These scripts make managing a flex router much easier than what is described here.

The instructions below describe the low-level way to initialize and register a flex router and are intended for software developers.

The Hard Way

If you want to customize the installation, follow these instructions.

Build bubble-flexrouter

You can skip this step if you have a pre-built binary from one of the above ZIP files.

If you want to build from source:

Installation

There are a few steps to installation:

  • Generate the flex-router password
  • Create an auth token file
  • Create an SSH key pair
  • Install system service

Generate the bubble-flexrouter password

During installation, choose a password for the service. It should be random and at least 30 characters long.

Bcrypt the password (use 12 rounds).

Store the plaintext (not bcrypted) password securely someplace where the Bubble app can read it. It will need this password to register and unregister the router with the Bubble. Ideally this is not on the filesystem, but in some internal app storage mechanism, since it will be stored in plaintext.

Store the bcrypted value securely somewhere someplace where only the bubble-flexrouter service can read it. If you store the bcrypted value in a file, ensure that only the bubble-flexrouter service can read the file.

Create an auth token file

bubble-flexrouter uses an auth token to secure its connection to a Bubble.

During installation, generate a random token. This token must be at least 50 characters long.

Store the token securely somewhere someplace where only the bubble-flexrouter service can read it. If you store the token in a file, ensure that only the bubble-flexrouter service can read the file.

Create an SSH key pair

During installation, generate an RSA key pair:

ssh-keygen -t rsa -f /some/secure/location

In the above, /some/secure/location should be a path that is only readable by the bubble-flexrouter system service.

When this step is done, /some/secure/location should be the path to the SSH private key and /some/secure/location.pub should be the path to the SSH public key.

Install system service

Install bubble-flexrouter as a system service (Windows Service or Mac OS launch daemon) during Bubble app installation.

It should always be running. Set it to run at system startup.

The user that bubble-flexrouter runs as must have sufficient privileges to add and remove IP routes from the system routing table. This usually means Administrator (on Windows) or root (on Mac OS).

For Mac OS X, you can use the com.bubble-vpn.flexrouter.plist file included in the distribution zip file.

The service requires some environment variables to be set:

  • BUBBLE_FR_SSH_KEY - full path to the private SSH key
  • BUBBLE_FR_PASS - full path to the bcrypted password file, or the actual bcrypted password prefixed with @
  • BUBBLE_FR_TOKEN - full path to the auth token file, or the actual token prefixed with @

Run the service with these environment variables set.

Uncommon configuration

By default bubble-flexrouter will listen on 127.0.0.1 on ports 9823 and 9833.

If these ports are unavailable, you can change them with command line arguments to bubble-flexrouter.

Run bubble-flexrouter --help to see the full list of command line options. Usually you will not need to set any arguments.

Registering

When a user successfully logs in to a Bubble node, the API response will include a session token. Use this token and the bubble-flexrouter password to register the flexrouter with the Bubble.

To register the flexrouter with the Bubble, send a registration request to the admin port, listening on 127.0.0.1:9833

This request must include the request header Content-Type: application/json

POST http://127.0.0.1:9833/register
{
  "password": "<password>",
  "session": "<session-token>",
  "bubble": "<bubble-hostname>",
  "ip": "<client-vpn-ip>"
}

Where:

  • <password> is the bubble-flexrouter password that was generated during installation
  • <session-token> is the session token returned when the used logged in (usually from the auth/login API call)
  • <bubble-hostname> is the hostname of the Bubble that the app has connected to
  • <client-vpn-ip> is the VPN IP address that was assigned to the device (usually starts with 10.19.)

A successful registration request will return HTTP status 200. Any other response indicates a failure, and the response body will contain a plaintext string with an error message.

An example using curl:

curl -H 'Content-Type: application/json' \
     -d '{"password":"Uy6dDwNP5msid3P6QEpeVmQMuUiAda","session":"47cc4974-2eca-47d8-8c74-c2cc106b9ba8","bubble":"nexus-dr66b-wn85d-ux27e.bubv.net","ip":"10.19.49.12"}' \
     http://127.0.0.1:9833/register

Unregistering

When a user logs out of a Bubble node, unregister the flexrouter by sending a request to the admin port.

This request must include the request header Content-Type: application/json

POST http://127.0.0.1:9833/unregister
{
  "password": "<password>"
}

Where:

  • <password> is the bubble-flexrouter password that was generated during installation

A successful unregister request will return HTTP status 200. Any other response indicates a failure, and the response body will contain a plaintext string with an error message.

An example using curl:

curl -H 'Content-Type: application/json' \
     -d '{"password":"Uy6dDwNP5msid3P6QEpeVmQMuUiAda"}' \
     http://127.0.0.1:9833/unregister

Uninstallation

If the Bubble app is uninstalled from the system, then also:

  • Stop and remove the system service
  • Remove the bcrypted password file
  • Remove both files of the SSH key pair
  • Remove the auth token file