BlueBubbles Server
  • Server Overview
  • Installation Guides
    • Standard Installation
    • Manual Setup
  • FAQ
  • Private API Setup
  • Supporting the Project
  • Licenses / Legal
  • Basic Guides
    • Basic Guides - Overview
    • Port Forwarding & Dynamic DNS
    • Prevent macOS from Sleeping
    • Migrating Servers
    • Multiple Users on the Same Mac
    • Autostart Server After Crash
  • Troubleshooting Guides
    • Troubleshooting Guides - Overview
    • BlueBubbles Server Cannot Access MacOS Contacts
    • Not Receiving Notifications or URL Changes on Android
    • Unable to Send Messages to International Contacts
    • BlueBubbles App is Taking Up Too Much Storage
    • Can't Send Messages from BlueBubbles
    • BlueBubbles Server Opens to a Blank White Screen
    • Slow Upload Speed When Connecting Over LAN
    • Restarting Your Server Without a Direct Connection
    • Fix FaceTime Features for Virtual Machines
  • Advanced Guides
    • Advanced Guides - Overview
    • Generating an SSL Certificate using CertBot
    • Disabling SIP on Unofficial Macs for the Private API
    • Registering a Phone Number with your iMessage Account
    • macOS Virtualization
      • Running a macOS VM
        • Deploying macOS in VMWare on Windows (Full Guide)
        • Enabling iMessage in a VM
        • External Guides
          • Big Sur VM on a Mac Device
          • Big Sur VM on Proxmox
          • Big Sur VM on AMD Windows
          • Big Sur VM on Intel Windows
          • Catalina VM on a Mac Device
          • Catalina VM on Proxmox
          • Catalina VM on Intel / AMD Windows
          • Catalina VM on Intel Windows
          • Monterey VM on AMD Windows
      • Running BlueBubbles in Docker-OSX
        • Configuring BlueBubbles as a Service
    • BYO Proxy Service Guides
      • Cloudflare with a Custom Domain
      • Caddy & DuckDNS
      • Nginx Proxy Manager
      • Nginx Manual Setup
      • Tailscale VPN Setup
  • Developer Guides
    • Developer Guides - Overview
    • Build Yourself / Contribution Guide
    • REST API & Webhooks
    • Simple Web Server for Webhooks
      • Python Web Server Example
Powered by GitBook
On this page
  • Pre-requisites
  • Before You Begin
  • Port Forwarding Guide
  • Port-Forwarding Verification
  • Dynamic DNS Setup
  • Configuration in BlueBubbles

Was this helpful?

Edit on GitHub
Export as PDF
  1. Basic Guides

Port Forwarding & Dynamic DNS

This guide will show you how to port-forward using your home's router, so you can connect directly to your BlueBubbles server using a Dynamic DNS. No need for a third-party proxy service.

PreviousBasic Guides - OverviewNextPrevent macOS from Sleeping

Last updated 2 years ago

Was this helpful?

Before you begin, make sure that the following pre-requisites apply to you. If any of them do not apply to you, this will not be possible for you, and you may need to stick to the build-in proxy services, pay for one, or self-host a reverse proxy.

Pre-requisites

  • You have access to your network's router

    • This doesn't need to be physical access

    • You will need to know how to login to your router's UI via your browser. This guide will walk you through part of it but will not provide you with the required authentication information. You must already know this.

    • This will not work on school or work networks

  • Your macOS device must already be setup (physical or VM)

  • Your macOS device must have a static IP Address.

    • If you don't already have a static IP, learn how to set one

Before You Begin

Read these notes before you begin, just in case...

  • If you are running macOS in a VM, make sure the network adapter is configured as "Bridged".

    • This means that the VM will connect directly to your router, rather than through the host computer.

    • This allows external connections to connect directly to your mac server.

  • By default, this setup utilizes HTTP, not HTTPS. In order to use HTTPS, you will need to know how to setup a certificate with your dynamic DNS provider. Whether that be via your router, or manual using Let's Encrypt.

    • This implies that your data is unencrypted when no certificate is implemented.

    • You can utilize the Encrypt Messages option in the BlueBubbles server settings to protect some of your data, but not all.

  • If no certificate is implemented, and you are connecting over HTTP, BlueBubbles Web will not be usable. This is because browsers now require a secure connection when making API calls to a server.

Port Forwarding Guide

Now that you've read the pre-requisites and the "before you begin" notes, you can start the setup.

  1. Get the IP of both your router and your macOS device (or VM).

    1. To get this information, open System Preferences and find the Network settings.

    2. Click on the connected Ethernet or WiFi device on the left sidebar.

    3. On the right-hand side, find the IP Address entry, and under that, the Router IP entry

      1. If you do not see IP Address or Router entries on the right side, click Advanced, and then select the TCP/IP tab.

    4. Copy those IPs somewhere you can reference.

  2. Open your browser and navigate to your router's home page

    1. In your browser's URL bar, enter http://<router IP>, replacing <router IP> with the router entry you copied earlier. If your router's home page connects over HTTPS, use https:// instead. However, the majority of routers utilize HTTP by default.

    2. Your router's IP will typically look something like one of the following:

      1. 192.168.0.1

      2. 10.0.0.1

      3. 192.168.50.1

    3. If you get one of those Your connection isn't private browser pages, simply type thisisunsafe directly into the browser window (not the URL bar) and the site should load.

  3. When prompted to enter your login credentials, enter your username and password to login.

    1. It's typical that the router has the default username and password printed on a sticker, on the device itself.

  4. Next, you will need to find the Port-forwarding settings. Many routers will list it in the sidebar under Port Forwarding, or similar. However, some routers may hide those settings under the WAN tab in the sidebar.

  5. Once on the port forwarding configuration page, click the button to add a new port forwarding configuration/profile.

  6. You will be prompted to enter some information:

    1. Name: You can enter any name

    2. Protocol: TCP or Both

    3. External Port: This is the port that you will use in your server URL to connect.

      1. This can be the same as the port that BlueBubbles is running on.

    4. Internal IP Address: The IP of your macOS device that you copied earlier

    5. Internal Port: The port that the BlueBubbles server is configured with

  7. Save the configuration/profile

  8. Read the next section to figure out how to verify that everything was setup properly

Port-Forwarding Verification

This section will show you how to verify that you've port-forwarded correctly.

  1. In the Port field, enter in the External Port you configured when setting up the port-forwarding.

  2. Click the Check Port button

    1. You will receive a Success message if you've configured port-forwarding correctly.

    2. You will see an Error if you did not configure port-forwarding correctly.

If your verification failed, it means something went wrong in the process. Here are some things you can try to possibly fix any issues:

  • Go through the guide again and make sure that everything is configured properly

  • If you did not setup a static IP for your mac, your mac's IP Address may have changed, and you need to configure your port-forwarding profile with the new IP Address.

  • Maybe you entered the BlueBubbles port into the CanYouSeeMe website, and not the External Port you configured within your router.

  • Run the BlueBubbles server and try again.

Dynamic DNS Setup

Once you have setup port-forwarding, the next step would be to sign up and use a Dynamic DNS service to connect your home IP Address to a domain. Here are some free Dynamic DNS providers that are fairly popular and well-liked:

Once you have one picked, sign up for a free account. And setup a new Dynamic DNS configuration.

Next, you will need to download the corresponding "DUC" (Dynamic Update Client) for your provider. This allows your mac to update the DNS record whenever it's router's external IP changes. Without it, you will lose connection to your server whenever your external IP changes.

Here are the DUC clients for the providers above:

Once the DUC is installed, login or configure it with your account.

Lastly, add the DUC app to your mac account's login items so it runs each time the computer is rebooted.

You will now be able to connect to your BlueBubbles server via your Dynamic DNS domain + Port Forwarded Port. For example: http://<dynamic dns>:<port>

Configuration in BlueBubbles

In order to use your new Dynamic DNS with BlueBubbles, simply follow these steps.

  1. Open your BlueBubbles server

  2. Open the Settings tab

  3. Find the Proxy Service drop down and select Dynamic DNS.

  4. You will get a popup window asking you for a server URL. Enter your dynamic DNS URL + Port (i.e. http://<dynamic dns>:<port>)

  5. If you have an SSL Certificate, set your server URL to HTTPS instead of HTTP. Make sure to also enable Settings > Advanced Connection Settings > Use Custom Certificate. Once enabled, a self-signed certificate (server.key and server.pem) will be created in ~/Library/Application Support/bluebubbles-server/Certs. Replace both files with your certificate files. It is important to name these files exactly the same as the self-signed certificate files that were created. Note: If your certificate file ends in .crt, simply rename it to .pem.

  6. Restart your BlueBubbles server to activate your new settings.

  7. You should now be configured to use BlueBubbles via port-forwarding.

If you do not know your username or password, it's fairly typical for the default username to be admin. However, the password can vary by manufacturer. A list of possible default credentials can be found .

If you cannot find the port-forwarding configuration page, you might have luck finding it after reading one of the guides

On your mac, open your browser and navigate to

No-IP now includes 1 free certificate, which you can apply

here
here
here
https://canyouseeme.org/
No-IP
here
DynDNS
DuckDNS
No-IP DUC
DynDNS DUC
DuckDNS DUC