import SupportOptions from "@/components/SupportOptions"; import { TabsGroup, TabsItem } from "@/components/Tabs"; import Alert from "@/components/DocsAlert"; import { FaInfoCircle } from "react-icons/fa";

macOS Client

Firezone supports macOS with a native client available both in the Mac App Store and as a standalone distributable.

Prerequisites

• macOS 13 or higher
• Intel x86-64 or Apple Silicon CPU architecture

Installation

Firezone distributes the macOS client in two ways: through the Mac App Store and as a standalone download.

If you're looking for the easiest way to install and manage Firezone on your Mac, use the App Store version.

If you want the ability to rollback to an earlier release or install the client without an Apple account, use the standalone version.

1. Download the Client from the Mac App Store.
2. Click Open in the App Store.
3. Click Enable System Extension in the window that appears.
4. Click Open System Settings in the dialog that appears.
5. Toggle the switch next to FirezoneNetworkExtension to enable the system extension.
6. Click Done.
7. Click Grant VPN Permission. macOS will show a dialog saying, "Firezone" Would Like to Add VPN Configurations.
8. Click Allow.
9. The Welcome to Firezone window will open.

Firezone is now ready for use.

1. Download the Client
2. Open the downloaded .dmg file.
3. Drag the Firezone icon to the Applications folder.
4. Open the Applications folder and double-click the Firezone icon.
5. Click Enable System Extension in the window that appears.
6. Click Open System Settings in the dialog that appears.
7. Toggle the switch next to FirezoneNetworkExtension to enable the system extension.
8. Click Done.
9. Next, click Grant VPN Permission. macOS will show a dialog saying, "Firezone" Would Like to Add VPN Configurations.
10. Click Allow.

Firezone is now ready for use.

Switching between App Store and Standalone

If you have the App Store version installed and want to switch to the standalone version (or vice versa), follow these steps:

1. Quit the Firezone Client.
2. Uninstall the Firezone Client by dragging it to the Trash and emptying the Trash.
3. Reboot your Mac. You must reboot your Mac to ensure the system extension is removed to prevent conflicts.
4. Install the desired version using the instructions above.

Note: This will reset any changes you've made to the client settings, so be sure to configure them again if needed.

Usage

Signing in

1. In the menu bar, click the crossed-out Firezone icon and click Sign In. macOS will show a dialog saying, “Firezone” Wants to Use “firezone.dev” to Sign In.
2. Click Continue. Firezone will open a sign-in page.
3. Select your account and sign in. The Firezone icon should no longer be crossed out.

Accessing a Resource

When Firezone is signed in, web browsers and other programs will automatically use it to securely connect to Resources.

To copy-paste the address of a Resource:

1. In the menu bar, click the Firezone icon to open the status menu.
2. Open a Resource's submenu and click on its address to copy it.
3. Paste the address into your browser's URL bar and press Return.

Quitting

1. In the menu bar, click on the Firezone icon to open the status menu.
2. Click Disconnect and Quit or Quit.

When Firezone is not running, you can't access private Resources, and the computer will use its normal DNS and Internet behavior.

If you were signed in, then you will still be signed in the next time you start Firezone.

Signing out

1. In the menu bar, Click on the Firezone icon to open the status menu.
2. Click Sign out.

When you're signed out, you can't access private Resources, and the computer will use its normal DNS and Internet behavior.

Upgrading

We recommend keeping the Firezone client up to date if possible. How this is achieved depends on how you installed the client.

Use the App Store to update the Firezone Apple Client. See Apple's documentation "Use the App Store to update apps on Mac" for more information.

To upgrade the standalone Firezone Client:

1. Quit the Firezone Client if it's running.
2. Download the latest version.
3. Open the downloaded .dmg file.
4. Drag the Firezone icon to the Applications folder, replacing the existing version.
5. Open the Applications folder and double-click the Firezone icon.

Diagnostic logs

Firezone writes log files to disk. These logs stay on your computer and are not transmitted anywhere. If you find a bug, you can send us a .aar archive of your logs to help us fix the bug.

To export or clear your logs:

1. In the menu bar, click on the Firezone icon to open the status menu.
2. Click Settings.
3. Click Diagnostic Logs.
4. Click Export Logs or Clear Log Directory.

Uninstalling

1. Quit the Firezone Client.
2. Drag the Firezone icon from the Applications folder to the Trash.
3. Empty the Trash.

See Apple's documentation "Uninstall apps on your Mac" for more information.

Troubleshooting

Signing in doesn't do anything

If you go through the sign in process successfully and nothing happens, it could be that the System Extension is not enabled or installed correctly. To fix this, perform the following steps:

Step 1: Remove the VPN Profile

1. Quit the Firezone Client.
2. Open System Settings.
3. Go to VPN.
4. Click the <span><FaInfoCircle className="inline" /></span> in the Firezone entry to open its settings.
5. Click the Remove Configuration... button and confirm the removal.

Step 2: Remove the Network Extension

1. Open System Settings.
2. Go to General -> Login Items & Extensions.
3. Scroll to the bottom and look for the Network Extensions section.
4. Click the <span><FaInfoCircle className="inline" /></span> in the Network Extensions section to open its settings.
5. Click the ellipsis (...) button in the Firezone.app entry to open the contextual menu.
6. Click Delete Extension.

Step 3: Open the Firezone Client

1. Open the Firezone Client.
2. Click Enable System Extension and follow the instructions to enable the system extension.
3. Click Grant VPN Permission and follow the instructions to allow the VPN profile.

Step 4: Sign in

The system extension and related VPN profile should now be installed correctly. If you still have issues, please contact support.

Check if Firezone is controlling DNS

1. Open the Terminal app.
2. Run dig firezone.dev and look for a line starting with ;; SERVER:.

If the Firezone is controlling the system's DNS, then the server will be 100.100.111.1 or some other IP in the 100.100.111.0/24 range or fd00:2021:1111:8000:100:100:111:0/120 range.

Firezone Split DNS:

;; SERVER: 100.100.111.1#53(100.100.111.1)
;; WHEN: Thu May 30 00:00:00 UTC 2024
;; MSG SIZE  rcvd: 57

Normal system DNS:

;; SERVER: fe80::96a6:7eff:fe78:edb7%15#53(fe80::96a6:7eff:fe78:edb7%15)
;; WHEN: Thu May 30 00:00:00 UTC 2024
;; MSG SIZE  rcvd: 57

Known issues

• Authentication will not use Firefox even if it is the default browser: Firezone will not use Firefox for authentication on macOS even if it is the default browser. This is due to Firefox's lack of support for Apple's WebAuthenticationSession API. To work around this issue, use Safari or Chrome for authentication.
• Cloudflare WARP client conflicts with other VPN apps: The Cloudflare WARP client may interfere with Firezone's ability to initialize its tunnel interface or resolve DNS resources. Ensure the Cloudflare WARP client is disabled completely or uninstalled to prevent these issues.
• SentinelOne agent can block DNS queries: The SentinelOne agent for macOS may interfere with Firezone's ability to successfully forward and reply to DNS queries made by applications on macOS. The symptom when this occurs is that all DNS queries on the system will fail, not just those that match the DNS Resources you have in your account. The issue seems to mainly be present on x86_64 systems only. See this issue for more information: #6768.