> For the complete documentation index, see [llms.txt](https://netfluss.ranagmbh.de/llms.txt).
> Use it to discover all available pages before exploring further.

# NetFluss FAQ

Answers to common NetFluss questions about features, Wi-Fi Manager, VPN Client, data usage, router monitoring, multi-language support, macOS support, install methods, permissions, privacy, and troubleshooting.

## Frequently asked questions

<ExpandableGroup>
  <Expandable title="What is NetFluss and what does it show?" default-open="false">
    NetFluss is a minimal macOS menu bar app that shows real-time upload and download rates across all active network adapters on your Mac.

    When you click the menu bar item, NetFluss also shows:

    - Current bandwidth per adapter (Wi‑Fi, Ethernet, VPN, and other virtual interfaces)
    - Important IP addresses, including local/router and external IPs
    - Options to quickly reconnect network adapters when needed
  </Expandable>

  <Expandable title="What is Bandwidth Statistics in NetFluss 2.0?" default-open="false">
    Bandwidth Statistics is a dedicated window that shows historical bandwidth usage over time, instead of only the live rates in the menu bar popover.

    The window includes:

    - Time ranges for `1H`, `24H`, `7D`, `30D`, and `1Y`
    - Separate download and upload timelines
    - Top adapters and top apps for the selected range

    Statistics collection is optional and off by default. You can keep NetFluss running without collecting any statistics, or enable statistics and separately control whether app-level statistics are collected.

    To open the Bandwidth Statistics window, right-click the NetFluss menu bar icon and choose `Bandwidth Statistics`.
  </Expandable>

  <Expandable title="How does the built-in Speed Test work and where is the history stored?" default-open="false">
    The built-in Speed Test lets you measure your internet connection directly from NetFluss without opening a browser or separate app.

    From the NetFluss menu bar icon, right-click and choose `Run Speed Test…` to open the dedicated Speed Test window. NetFluss runs the test using either the M-Lab or Cloudflare provider, and it remembers your last selected provider for the next run.

    Each completed speed test is saved locally in Speed Test History. You can compare results by date, provider, download speed, upload speed, and latency to see how your connection performs over time.
  </Expandable>

  <Expandable title="Does NetFluss check for updates automatically?" default-open="false">
    NetFluss supports optional automatic update checks against GitHub so you do not have to manually look up new releases.

    Go to Preferences → Update and enable `Check GitHub for updates automatically` to let NetFluss check once per day whether a newer version is available. Automatic checks only read release information from GitHub; they do not install updates without your action.

    If you prefer manual control, leave the automatic toggle off and use the existing manual update check in the About window whenever you want to see if a new version is available.
  </Expandable>

  <Expandable title="What are the new menu bar styles and color controls in NetFluss 1.12?" default-open="false">
    NetFluss 1.12 adds more control over how the menu bar display looks, so you can match it to your macOS setup and personal preference.

    You can choose between these menu bar icon styles:

    - Standard
    - Unified pill
    - Dashboard
    - Icon

    In addition to the layout styles, NetFluss 1.12 introduces separate color controls for:

    - Upload arrow
    - Download arrow
    - Upload number
    - Download number

    Use these options to tune both the shape and coloring of the menu bar item without affecting other parts of the UI.
  </Expandable>

  <Expandable title="What is Fritz!Box Bandwidth Monitoring (Experimental)?" default-open="false">
    Fritz!Box Bandwidth Monitoring shows total WAN download and upload rates from your Fritz!Box router directly in the NetFluss popover, alongside your Mac's own adapter traffic.

    NetFluss queries your Fritz!Box using the official TR-064 API. For bandwidth data, this feature does not require authentication, so you do not need to enter your Fritz!Box username or password.

    Enable the feature in Preferences → Fritz!Box Bandwidth. There you can also configure the router address if your Fritz!Box is not reachable at the default `fritz.box` hostname.

    <Callout kind="info" collapsed="false">
      Fritz!Box Bandwidth Monitoring is marked as experimental. Expect minor glitches or behavior changes in future NetFluss releases as it evolves.
    </Callout>
  </Expandable>

  <Expandable title="Why do UniFi and OpenWrt monitoring require credentials and how are they stored?" default-open="false">
    UniFi and OpenWrt monitoring in NetFluss 1.11 use authenticated access to your local controller or router to read bandwidth and metrics. These devices do not expose the required data anonymously, so NetFluss needs valid credentials to log in and query their APIs.

    NetFluss stores these credentials in Apple Keychain instead of plain preferences files. Keychain encrypts your passwords, integrates with macOS access controls, and avoids keeping sensitive data in readable configuration files on disk.

    NetFluss uses the stored credentials only on your Mac to talk directly to your UniFi controller or OpenWrt router. The credentials are not sent to NetFluss servers or shared externally.

    Authentication runs entirely in the background through direct API calls and does not open a browser window or OAuth-style popup. For UniFi, NetFluss sends an HTTP POST request to `/api/auth/login`, receives a session cookie, and then uses that cookie on each poll to call `/stat/device` for updated stats. If your UniFi controller uses a self-signed TLS certificate, NetFluss still connects by using custom insecure TLS handling for that specific connection so HTTPS works without extra setup.

    For OpenWrt, NetFluss talks to the `ubus` JSON-RPC API over HTTP. It calls `session.login` on `/ubus` to obtain a token and then includes that token in subsequent `ubus` requests to read bandwidth data.

    <Callout kind="info" collapsed="false">
      If you want to reset UniFi or OpenWrt credentials, remove the related entries from Apple Keychain or update them in NetFluss by re-entering your login details. NetFluss will then store the new credentials locally again.
    </Callout>
  </Expandable>

  <Expandable title="Is NetFluss free and open source? What license does it use?" default-open="false">
    NetFluss is free to use and open source. The entire app is written in Swift and published on GitHub.

    The project is licensed under an open-source license, which you can review directly in the `LICENSE` file in the NetFluss GitHub repository.
  </Expandable>

  <Expandable title="Which macOS versions does NetFluss support?" default-open="false">
    NetFluss requires macOS 13 Ventura or later. Earlier macOS versions are not supported.

    <Callout kind="info" collapsed="false">
      If NetFluss does not launch or refuses to install on an older system, check your macOS version in `` → `About This Mac` and upgrade to macOS 13 or newer.
    </Callout>
  </Expandable>

  <Expandable title="How do I install NetFluss (Homebrew vs manual)?" default-open="false">
    Install NetFluss in either of these ways:

    **Homebrew (recommended if you already use Homebrew):**

    ```bash
    brew install --cask rana-gmbh/netfluss/netfluss
    ```

    **Manual install:**

    1. Download the latest NetFluss `.zip` from the releases section of the GitHub repository.
    2. Unzip the archive.
    3. Move `NetFluss.app` into your `/Applications` folder.
    4. Launch NetFluss from Applications or Spotlight.

    After installation, you should see the NetFluss icon appear in your menu bar. Click it to open the detailed view.
  </Expandable>

  <Expandable title="Why does macOS ask for Location Services permission?" default-open="false">
    NetFluss uses the macOS CoreWLAN framework to show your Wi‑Fi SSID (network name) and band. On macOS, exposing SSID details through CoreWLAN is tied to Location Services.

    When NetFluss first tries to access Wi‑Fi SSID and band information, macOS may ask you to grant Location Services permission. If you deny this, NetFluss continues to work, but SSID-related details may be missing.

    <Callout kind="info" collapsed="false">
      NetFluss does not track or send your physical location. The Location Services prompt comes from macOS because SSID access is classified as location-related data.
    </Callout>
  </Expandable>

  <Expandable title="Where do the IP addresses come from?" default-open="false">
    NetFluss shows both internal and external IP information:

    - **Local/router IPs** come from your active network adapters on macOS.
    - **External IP** is looked up using `ipwho.is`, with `api.ipify.org` as a fallback service.

    NetFluss caches the external IP briefly to avoid unnecessary requests while keeping the value reasonably up to date. In Preferences → Appearance → External IP, you can choose whether NetFluss displays your external IPv4 or IPv6 address.
  </Expandable>

  <Expandable title="What is Connection Flow View and how do I use it?" default-open="false">
    Connection Flow View shows a visual path from your Mac to your router and out to the internet, including a VPN tunnel if one is active. You can optionally show IP addresses at each hop and see a country flag for VPN exit nodes.

    Enable or disable Connection Flow View and its IP display options in NetFluss Preferences. Use it when you want a quick, visual check of how your traffic is routed, including whether a VPN is active and where it exits.
  </Expandable>

  <Expandable title="Why is Top Apps empty or not updating?" default-open="false">
    The Top Apps view reads per‑connection byte counts from the `netstat -n -b -v` command and matches them to processes using `proc_pidpath`. Only processes with active TCP or UDP connections appear in the list.

    Top Apps may appear empty or static when:

    - Your Mac has no active network traffic from user apps
    - Only background system processes are talking to the network
    - The active traffic is very low or very short‑lived

    To check whether it works, start a clearly network-heavy task, such as:

    - Streaming a video in your browser
    - Downloading a large file

    Then reopen or refresh the Top Apps view. If you still never see any entries even during obvious traffic, open an issue on GitHub with details about your macOS version and screenshots.

    <Callout kind="info" collapsed="false">
      If you run macOS 15 and Top Apps stays empty, update to NetFluss 1.7.1 or later. Earlier NetFluss versions on macOS 15 include a bug that can prevent Top Apps from showing or updating.
    </Callout>
  </Expandable>

  <Expandable title="How do I hide or whitelist apps in Top Apps?" default-open="false">
    Use app filtering in Top Apps to hide noisy background processes and focus on the traffic you care about.

    Go to Preferences → Top Apps → `Apps to Hide`. NetFluss builds this list from processes that used bandwidth in the last 60 seconds, so you normally see it populate after some recent network activity.

    Add an app to `Apps to Hide` to remove it from the Top Apps view and free up space for other entries. Hidden apps no longer occupy one of the limited Top Apps slots, which makes it easier to monitor the tools and sites you actually want to track.
  </Expandable>

  <Expandable title="What are adapter and Top Apps grace periods?" default-open="false">
    Grace periods keep adapters and apps visible for a short time after they go idle, so lists do not flicker when traffic briefly stops. You can set Adapter Grace Period and Top Apps Grace Period to 3, 5, or 10 seconds in NetFluss Preferences.

    Longer grace periods keep adapter cards and the Top Apps list more stable, while shorter grace periods make them react faster to changes. Adjust these values based on whether you prefer stability or immediacy in the UI.
  </Expandable>

  <Expandable title="Why do I see many adapters (VPN or virtual interfaces)?" default-open="false">
    NetFluss shows all active network adapters, including:

    - Physical adapters (Wi‑Fi, Ethernet)
    - VPN interfaces
    - Virtual adapters created by security tools or virtualization software

    Some VPN or networking tools create new virtual adapters frequently. In those cases, renaming a specific adapter may not persist because the tool replaces the interface with a new one.

    Use the NetFluss preferences to:

    - Hide inactive adapters
    - Hide certain categories of adapters (such as VPN or virtual interfaces)
    - Control per‑adapter visibility and how they contribute to totals

    If you still see too many adapters, review your VPN or virtualization setup to reduce the number of virtual interfaces that macOS exposes.
  </Expandable>

  <Expandable title="What is the DNS Switcher and where do I find it?" default-open="false">
    DNS Switcher lets you change your active DNS provider directly from the NetFluss popover, without digging into macOS network settings.

    Open the NetFluss popover and look for the DNS section to switch between built-in presets for Cloudflare, Google, Quad9, and OpenDNS. You can also define custom DNS presets in NetFluss Preferences and choose which ones appear.

    When you apply a new DNS preset, NetFluss uses Touch ID authentication for the change when Touch ID is available, instead of showing an admin password dialog. If your Mac does not support Touch ID or it is unavailable, macOS falls back to the standard admin password prompt.

    In Preferences → DNS Switcher, you can control how DNS authentication behaves and which presets are enabled and shown, as well as reorder them to match how you prefer to switch DNS providers.
  </Expandable>

  <Expandable title="How do I edit a custom DNS preset?" default-open="false">
    In NetFluss 1.10 and later, you can edit custom DNS presets after you create them, including the preset name and DNS server addresses.

    Open Preferences → DNS Switcher and find the custom preset you want to change. Click the pencil icon next to that preset to update its details, then save your changes to apply the new name or servers the next time you switch to that preset.
  </Expandable>

  <Expandable title="Why did the menu bar text used to jump or shift?" default-open="false">
    Earlier NetFluss versions could cause the menu bar layout to shift when the displayed speed changed width, for example from `999 KB/s` to `1.2 MB/s`. As the label grew or shrank, surrounding menu bar icons moved slightly.

    NetFluss 1.9 adds a fixed-width container for the menu bar display so the space is reserved in advance and the icons stay stable. If you still notice jumping or shifting, update to NetFluss 1.9 or later.
  </Expandable>

  <Expandable title="Is the app notarized and signed?" default-open="false">
    Yes. NetFluss is notarized by Apple and signed with a Developer ID certificate.

    This means Gatekeeper recognizes the app as coming from an identified developer, and you can run it on macOS without bypassing security checks.
  </Expandable>

  <Expandable title="Where can I report bugs or request features?" default-open="false">
    Report bugs, ask questions, or request features in the NetFluss GitHub repository by opening a new issue.

    When you create an issue, include:

    - Your macOS version
    - The NetFluss version
    - A clear description of the problem or request
    - Screenshots or screen recordings, if relevant

    Providing detailed information helps the maintainer reproduce and fix issues faster.
  </Expandable>

  <Expandable title="What is the Wi-Fi Manager and how do I use it?" default-open="false">
    The Wi-Fi Manager (added in NetFluss 2.3) shows every nearby Wi-Fi network directly in the popover, with signal strength, band, security type, and a saved-star indicator.

    You can:

    - **Join a network** with a single click — known networks reconnect silently; new secured networks prompt for a password
    - **Pin networks** to the top of the list so they are always visible, even when out of range
    - **View details** via the (i) info popover per row: SSID, security, band, channel, RSSI, and BSSID
    - **Limit the list** to the N strongest networks (configurable in Preferences → Wi-Fi)

    Enable it in **Preferences → Wi-Fi**. NetFluss requires Location Services access to scan for nearby networks.

    <Callout kind="info" collapsed="false">
      Passwords for newly-joined networks are saved into macOS Known Networks via the privileged helper, so the system Wi-Fi menu reuses them even when NetFluss is not running.
    </Callout>
  </Expandable>

  <Expandable title="What is the built-in VPN Client and which protocols does it support?" default-open="false">
    The VPN Client (added in NetFluss 2.4) lets you connect to your VPN provider directly from NetFluss without installing any provider-specific software.

    Supported protocols:

    - **OpenVPN** (`.ovpn` files) — uses a bundled, signed `openvpn` binary
    - **WireGuard** (`.conf` files) — uses bundled `wg-quick` and `wireguard-go`
    - **IKEv2 / IPsec / L2TP** — uses the native macOS VPN stack via `NEVPNManager`

    The popover shows a profile picker, server picker, connect/disconnect button, live status dot, assigned tunnel IP, and the exit country flag with country name and public IP.

    Credentials are stored securely in the macOS Keychain. See the [VPN Client guide](/vpn-client) for detailed setup instructions.
  </Expandable>

  <Expandable title="How do I import VPN profiles into NetFluss?" default-open="false">
    You can import VPN profiles in three ways:

    - **Single config file** — import one `.ovpn` or `.conf` file
    - **Folder of configs** — import a directory containing multiple config files
    - **`.zip` bundle** — import a provider's profile pack; each config inside becomes a selectable server endpoint

    Go to **Preferences → VPN** and use the import button. Sidecar certificate files (CA, cert, key, tls-auth, tls-crypt, pkcs12, dh) are copied alongside the config so non-inline profiles resolve correctly.

    <Callout kind="info" collapsed="false">
      If an `.ovpn` file uses a provider-patched-only directive such as `scramble` or XOR obfuscation, NetFluss warns you up front that the bundled upstream `openvpn` cannot run it.
    </Callout>
  </Expandable>

  <Expandable title="Can NetFluss apply a custom DNS while my VPN is connected?" default-open="false">
    Yes. Each VPN profile has an optional per-profile DNS setting. When enabled, NetFluss applies one of your configured DNS presets while the tunnel is connected, and automatically restores the previous resolver when you disconnect.

    The DNS picker in the VPN profile settings shows only presets that have server addresses configured (the "Automatic" preset is excluded). This uses the same privileged helper and `networksetup` path as the standalone DNS Switcher.
  </Expandable>

  <Expandable title="Does NetFluss support VPN auto-reconnect and connect on launch?" default-open="false">
    Yes, both are available as per-profile toggles in **Preferences → VPN**:

    - **Reconnect automatically** — retries with exponential backoff (2 s up to 30 s, max 10 attempts). Deliberate disconnects and authentication failures are never retried.
    - **Connect when NetFluss starts** — automatically connects the profile when NetFluss launches. Only one profile can carry this setting at a time.
  </Expandable>

  <Expandable title="What is the Data Usage summary in the popover?" default-open="false">
    The Data Usage summary (added in NetFluss 2.4) shows a compact breakdown of your bandwidth consumption directly in the popover:

    - **Today** — total upload, download, and combined data for the current day
    - **This Month** — cumulative totals for the current month

    The summary requires historical statistics to be enabled. You can turn on statistics in **Preferences → Statistics**.

    <Callout kind="info" collapsed="false">
      The Data Usage summary is localised in English, German, Simplified Chinese, and Traditional Chinese.
    </Callout>
  </Expandable>

  <Expandable title="Can I exclude VPN traffic from my total bandwidth usage?" default-open="false">
    Yes. VPN and tunnel interfaces (`utun*`) can inflate your total bandwidth because traffic is counted on both the physical adapter and the VPN tunnel.

    Go to **Preferences → Adapters** and enable the option to exclude VPN/tunnel interfaces from the bandwidth summary. This prevents double-counting so the totals reflect your actual internet usage, not internal tunnel traffic.
  </Expandable>

  <Expandable title="What is OPNsense router monitoring?" default-open="false">
    OPNsense monitoring (added in NetFluss 2.1) shows real-time WAN bandwidth from your OPNsense firewall directly in the NetFluss popover, alongside Fritz!Box, UniFi, and OpenWrt.

    NetFluss queries the OPNsense REST API (`/api/diagnostics/traffic/interface`) over HTTPS or HTTP, auto-discovers the WAN interface, and stores your API key and secret securely in the macOS Keychain.

    Configure it in **Preferences → Router → OPNsense**. A test-connection button confirms connectivity before you save your credentials.
  </Expandable>

  <Expandable title="Which languages does NetFluss support?" default-open="false">
    NetFluss 2.2 introduced multi-language support. You can choose between:

    - English
    - German (Deutsch)
    - Simplified Chinese (简体中文)
    - Traditional Chinese (繁體中文)
    - System Default (follows your macOS language setting)

    Go to **Preferences → General → Language** to select a language. The change applies immediately to all windows — no restart needed.
  </Expandable>

  <Expandable title="What are customisable popover sections and how do I reorder them?" default-open="false">
    NetFluss 2.3 lets you customise which sections appear in the popover and in what order. The available sections are:

    - Download/Upload
    - Network adapters
    - Network flow
    - DNS
    - Router
    - Wi-Fi Networks
    - Top Apps

    Go to **Preferences → Appearance → Popover sections** to drag-and-drop reorder sections and toggle individual section visibility. Your custom order and visibility settings are saved automatically.
  </Expandable>

  <Expandable title="What is the System default menu bar colour option?" default-open="false">
    The "System default" colour option (added in NetFluss 2.4) automatically adapts your menu bar text and arrow colours to match your macOS appearance — light text on dark menu bars and dark text on light ones.

    Find it in **Preferences → Appearance** alongside the individual colour pickers for upload/download arrows and numbers. Selecting "System default" means you no longer need to manually adjust colours when switching between light and dark wallpapers.
  </Expandable>
</ExpandableGroup>