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.

README.md 6.6 KiB

4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156
  1. bubble-flexrouter
  2. =================
  3. bubble-flexrouter provides HTTP/HTTPS proxy services for Bubble.
  4. Some websites and apps refuse to respond to requests originating from a cloud IP address.
  5. Thus, when a user is connected to their Bubble, some sites and apps will not work.
  6. With flex routing, Bubble can route these requests through a device connected to the Bubble that is running bubble-flexrouter.
  7. Now, from the perspective of the website or app, these requests will originate from a "clean" IP, and so a valid response
  8. will be sent.
  9. Note that using flex routing does remove some privacy protection - sites and apps that are flex-routed will see
  10. one of your device's real IP addresses.
  11. # The Easy Way
  12. Download the latest bubble-flexrouter release:
  13. * [bubble-flexrouter for Windows](https://jenkins.bubblev.org/public/releases/bubble-flexrouter/bubble-flexrouter-windows/latest/bubble-flexrouter.zip)
  14. * [bubble-flexrouter for Mac OS X](https://jenkins.bubblev.org/public/releases/bubble-flexrouter/bubble-flexrouter-macos/latest/bubble-flexrouter.zip)
  15. * [bubble-flexrouter for Linux](https://jenkins.bubblev.org/public/releases/bubble-flexrouter/bubble-flexrouter-linux/latest/bubble-flexrouter.zip)
  16. The [README](README-release.md) file found within the above release ZIP file describes how to use
  17. the `flex_init.sh` and `flex_register.sh` scripts to manage a flex router.
  18. These scripts make managing a flex router much easier than what is described here.
  19. The instructions below describe the low-level way to initialize and register a flex router
  20. and are intended for software developers.
  21. # Build bubble-flexrouter
  22. You can skip this step if you have a pre-built binary from one of the above ZIP files.
  23. If you want to build from source:
  24. * Follow the [build instructions](BUILD.md) to build the bubble-flexrouter binary
  25. * or, on Windows, follow the [Windows build instructions](BUILD-windows.md)
  26. # Installation
  27. There are a few steps to installation:
  28. * Generate the flex-router password
  29. * Create an SSH key pair
  30. * Create an auth token file
  31. * Install system service
  32. ## Generate the bubble-flexrouter password
  33. During installation, choose a password for the service. It should be random and at least 30 characters long.
  34. Store this password in securely someplace where the Bubble app can read it. Ideally this is *not* on the filesystem,
  35. but in some internal app storage mechanism, since it will be stored in plaintext.
  36. Bcrypt the password (use 12 rounds) and store the bcrypted value in a file. This file should only be readable by
  37. the bubble-flexrouter system service.
  38. ## Create an SSH key pair
  39. During installation, generate an RSA key pair:
  40. ssh-keygen -t rsa -f /some/secure/location
  41. In the above, `/some/secure/location` should be a path that is only readable by the bubble-flexrouter system service.
  42. When this step is done, `/some/secure/location` should be the path to the SSH private key and
  43. `/some/secure/location.pub` should be the path to the SSH public key.
  44. ## Create an auth token file
  45. bubble-flexrouter uses an auth token to secure its connection to a Bubble.
  46. During installation, write a random token to a file. This token must be at least 50 characters long.
  47. After writing the file, ensure that it is only readable by the bubble-flexrouter service.
  48. ## Install system service
  49. Install bubble-flexrouter as a system service (Windows Service or Mac OS launch daemon) during Bubble app installation.
  50. It should always be running. Set it to run at system startup.
  51. The user that bubble-flexrouter runs as must have sufficient privileges to add and remove IP routes from the
  52. system routing table. This usually means Administrator (on Windows) or root (on Mac OS).
  53. The service requires some environment variables to be set:
  54. * `BUBBLE_FR_SSH_KEY` - full path to the *private* SSH key
  55. * `BUBBLE_FR_PASS` - full path to the bcrypted password file
  56. * `BUBBLE_FR_TOKEN` - full path to the auth token file
  57. Run the service with these environment variables set.
  58. ## Uncommon configuration
  59. By default bubble-flexrouter will listen on 127.0.0.1 on ports 9823 and 9833.
  60. If these ports are unavailable, you can change them with command line arguments to bubble-flexrouter.
  61. Run `bubble-flexrouter --help` to see the full list of command line options. Usually you will not need to set any arguments.
  62. # Registering
  63. When a user successfully logs in to a Bubble node, the API response will include a session token. Use this token
  64. and the bubble-flexrouter password to register the flexrouter with the Bubble.
  65. To register the flexrouter with the Bubble, send a registration request to the admin port, listening on 127.0.0.1:9833
  66. This request must include the request header `Content-Type: application/json`
  67. POST http://127.0.0.1:9833/register
  68. {
  69. "password": "<password>",
  70. "session": "<session-token>",
  71. "bubble": "<bubble-hostname>",
  72. "ip": "<client-vpn-ip>"
  73. }
  74. Where:
  75. * `<password>` is the bubble-flexrouter password that was generated during installation
  76. * `<session-token>` is the session token returned when the used logged in (usually from the `auth/login` API call)
  77. * `<bubble-hostname>` is the hostname of the Bubble that the app has connected to
  78. * `<client-vpn-ip>` is the VPN IP address that was assigned to the device (usually starts with `10.19.`)
  79. A successful registration request will return HTTP status 200. Any other response indicates a failure, and the response
  80. body will contain a plaintext string with an error message.
  81. An example using curl:
  82. curl -H 'Content-Type: application/json' \
  83. -d '{"password":"Uy6dDwNP5msid3P6QEpeVmQMuUiAda","session":"47cc4974-2eca-47d8-8c74-c2cc106b9ba8","bubble":"nexus-dr66b-wn85d-ux27e.bubv.net","ip":"10.19.49.12"}' \
  84. http://127.0.0.1:9833/register
  85. # Unregistering
  86. When a user logs out of a Bubble node, unregister the flexrouter by sending a request to the admin port.
  87. This request must include the request header `Content-Type: application/json`
  88. POST http://127.0.0.1:9833/unregister
  89. {
  90. "password": "<password>"
  91. }
  92. Where:
  93. * `<password>` is the bubble-flexrouter password that was generated during installation
  94. A successful unregister request will return HTTP status 200. Any other response indicates a failure, and the response
  95. body will contain a plaintext string with an error message.
  96. An example using curl:
  97. curl -H 'Content-Type: application/json' \
  98. -d '{"password":"Uy6dDwNP5msid3P6QEpeVmQMuUiAda"}' \
  99. http://127.0.0.1:9833/unregister
  100. # Uninstallation
  101. If the Bubble app is uninstalled from the system, then also:
  102. * Stop and remove the system service
  103. * Remove the bcrypted password file
  104. * Remove both files of the SSH key pair
  105. * Remove the auth token file