Add option to enable HA/CARP failover support to the os-netbird plugin #5067

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open

myah-mitchell wants to merge 12 commits into opnsense:master from INDIGEX:master

security/netbird/src/etc/inc/plugins.inc.d/netbird.inc

-Original file line number
+Diff line change
@@ Expand Up / @@ -34,6 +34,45 @@ function netbird_enabled() @@
         return !(new \OPNsense\Netbird\Settings())->general->enable->isEmpty();
     }
+    function netbird_carp_enabled()
+    {
+        $settings = new \OPNsense\Netbird\Settings();
+        return (string)$settings->general->enable == '1' &&
+               (string)$settings->general->enablecarp == '1';
+    }
+    /**
+     * Check if the current host is CARP master for any monitored VIP.
+     * Used to guard the service so it cannot start on a BACKUP node.
+     * Returns true if CARP is not enabled OR if we are currently MASTER.
+     * @return bool
+     */
+    function netbird_carp_check_master()
+    {
+        if (!netbird_carp_enabled()) {
+            // CARP not enabled for NetBird, allow service to start
+            return true;
+        }
+        // Check ifconfig output for CARP MASTER state
+        $ifconfig = shell_exec('/sbin/ifconfig');
+        if (preg_match('/carp:.*MASTER/', $ifconfig)) {
+            return true;
+        }
+        return false;
+    }
+    function netbird_devices()
+    {
+        return [[
+            'pattern' => '^wt0$',
+            'configurable' => false,
+            'spoofmac' => false,
+            'volatile' => true,
+        ]];
+    }
     function netbird_services()
     {
         $services = [];
@@ Expand Down @@

security/netbird/src/etc/rc.syshook.d/carp/50-netbird

-Original file line number
+Diff line change
@@ -0,0 +1,61 @@
+    #!/usr/local/bin/php
+    <?php
+    /*
+     * Copyright (C) 2026 Myah Mitchell, Innovative Networks, Inc. d.b.a INDIGEX
+     * All rights reserved.
+     *
+     * Redistribution and use in source and binary forms, with or without
+     * modification, are permitted provided that the following conditions are met:
+     *
+     * 1. Redistributions of source code must retain the above copyright notice,
+     *    this list of conditions and the following disclaimer.
+     *
+     * 2. Redistributions in binary form must reproduce the above copyright
+     *    notice, this list of conditions and the following disclaimer in the
+     *    documentation and/or other materials provided with the distribution.
+     *
+     * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+     * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+     * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+     * AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+     * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+     * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+     * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+     * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+     * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+     * POSSIBILITY OF SUCH DAMAGE.
+     */
+    /*
+     * rc.syshook.d/carp hook — called by ifup when a CARP interface changes state
+     * (MASTER or BACKUP).
+     *
+     * This calls NetBird's carp event script in the background (non-blocking),
+     * which gathers events for 2 seconds; if more are triggered in the same slot,
+     * execute only the last one.  This moves events until we have at least
+     * 2 seconds of "silence" to process them, preventing duplicate actions
+     * when multiple CARP interfaces transition simultaneously during failover.
+     */
+    require_once("config.inc");
+    require_once("util.inc");
+    require_once("plugins.inc.d/netbird.inc");
+    if (netbird_carp_enabled()) {
+        $subsystem = !empty($argv[1]) ? $argv[1] : '';
+        $type = !empty($argv[2]) ? $argv[2] : '';
+        if ($type != 'MASTER' && $type != 'BACKUP') {
+            log_msg("Carp '$type' event unknown from source '{$subsystem}'");
+            exit(1);
+        }
+        if (!strstr($subsystem, '@')) {
+            log_msg("Carp '$type' event triggered from wrong source '{$subsystem}'");
+            exit(1);
+        }
+        log_msg("NetBird CARP: '{$type}' event from '{$subsystem}', starting NetBird's carp event handler");
+        mwexecfb('/usr/local/opnsense/scripts/netbird/carp_event.php %s %s > /dev/null', [$subsystem, $type]);
+    }

security/netbird/src/etc/rc.syshook.d/monitor/50-netbird

-Original file line number
+Diff line change
@@ -0,0 +1,49 @@
+    #!/usr/local/bin/php
+    <?php
+    /*
+     * Copyright (C) 2026 Myah Mitchell, Innovative Networks, Inc. d.b.a INDIGEX
+     * All rights reserved.
+     *
+     * Redistribution and use in source and binary forms, with or without
+     * modification, are permitted provided that the following conditions are met:
+     *
+     * 1. Redistributions of source code must retain the above copyright notice,
+     *    this list of conditions and the following disclaimer.
+     *
+     * 2. Redistributions in binary form must reproduce the above copyright
+     *    notice, this list of conditions and the following disclaimer in the
+     *    documentation and/or other materials provided with the distribution.
+     *
+     * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+     * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+     * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+     * AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+     * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+     * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+     * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+     * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+     * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+     * POSSIBILITY OF SUCH DAMAGE.
+     */
+    /*
+     * rc.syshook.d/monitor hook — called by rc.gateway_alarm when dpinger
+     * detects a gateway state change (any monitored gateway going up or down).
+     *
+     * This calls NetBird's gateway monitor script in the background (non-blocking),
+     * which checks whether the default gateway has actually changed since the last
+     * invocation. If so, it restarts NetBird so it can re-establish connections
+     * through the new default route.
+     */
+    require_once("config.inc");
+    require_once("util.inc");
+    require_once("plugins.inc.d/netbird.inc");
+    if (netbird_enabled()) {
+        $affected_gateways = !empty($argv[1]) ? $argv[1] : '';
+        log_msg("NetBird monitor: Gateway event from '{$affected_gateways}', starting NetBird's monitor event handler");
+        mwexecfb('/usr/local/opnsense/scripts/netbird/gw_monitor.php %s > /dev/null', [$affected_gateways]);
+    }

security/netbird/src/etc/rc.syshook.d/start/50-netbird

-Original file line number
+Diff line change
@@ -0,0 +1,48 @@
+    #!/usr/local/bin/php
+    <?php
+    /*
+     * Copyright (C) 2026 Myah Mitchell, Innovative Networks, Inc. d.b.a INDIGEX
+     * All rights reserved.
+     *
+     * Redistribution and use in source and binary forms, with or without
+     * modification, are permitted provided that the following conditions are met:
+     *
+     * 1. Redistributions of source code must retain the above copyright notice,
+     *    this list of conditions and the following disclaimer.
+     *
+     * 2. Redistributions in binary form must reproduce the above copyright
+     *    notice, this list of conditions and the following disclaimer in the
+     *    documentation and/or other materials provided with the distribution.
+     *
+     * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+     * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+     * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+     * AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+     * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+     * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+     * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+     * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+     * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+     * POSSIBILITY OF SUCH DAMAGE.
+     */
+    /*
+     * rc.syshook.d/start hook — called during system boot after services
+     * are available.
+     *
+     * This calls NetBird's gateway monitor script in the background (non-blocking),
+     * which seeds the default gateway cache used later by the monitor hook
+     * (50-netbird) so that the first dpinger alarm after boot can correctly detect
+     * whether the default gateway has changed.
+     */
+    require_once("config.inc");
+    require_once("util.inc");
+    require_once("plugins.inc.d/netbird.inc");
+    if (netbird_enabled()) {
+        log_msg("NetBird monitor: Starting NetBird's monitor event handler");
+        mwexecfb('/usr/local/opnsense/scripts/netbird/gw_monitor.php %s > /dev/null', [$affected_gateways]);
+    }

security/netbird/src/opnsense/mvc/app/controllers/OPNsense/Netbird/forms/settings.xml

-Original file line number
+Diff line change
@@ Expand Up / @@ -9,6 +9,12 @@ @@
             <type>checkbox</type>
             <help>Enable NetBird</help>
         </field>
+        <field>
+            <id>settings.general.enablecarp</id>
+            <label>Enable CARP Failover Support</label>
+            <type>checkbox</type>
+            <help>When enabled, NetBird interfaces will start on MASTER state and stop on BACKUP state.</help>
+        </field>
         <field>
             <id>settings.general.wireguardPort</id>
             <label>WireGuard Port</label>
@@ Expand Down @@

security/netbird/src/opnsense/mvc/app/models/OPNsense/Netbird/Settings.xml

-Original file line number
+Diff line change
@@ Expand Up / @@ -8,6 +8,10 @@ @@
                     <Default>0</Default>
                     <Required>Y</Required>
                 </enable>
+                <enablecarp type="BooleanField">
+                    <Default>0</Default>
+                    <Required>Y</Required>
+                </enablecarp>
                 <wireguardPort type="IntegerField">
                     <Default>51820</Default>
                     <Required>Y</Required>
@@ Expand Down @@

security/netbird/src/opnsense/scripts/netbird/carp_check.php

-Original file line number
+Diff line change
@@ -0,0 +1,54 @@
+    #!/usr/local/bin/php
+    <?php
+    /*
+     * Copyright (C) 2026 Myah Mitchell, Innovative Networks, Inc. d.b.a INDIGEX
+     * All rights reserved.
+     *
+     * Redistribution and use in source and binary forms, with or without
+     * modification, are permitted provided that the following conditions are met:
+     *
+     * 1. Redistributions of source code must retain the above copyright notice,
+     *    this list of conditions and the following disclaimer.
+     *
+     * 2. Redistributions in binary form must reproduce the above copyright
+     *    notice, this list of conditions and the following disclaimer in the
+     *    documentation and/or other materials provided with the distribution.
+     *
+     * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+     * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+     * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+     * AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+     * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+     * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+     * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+     * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+     * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+     * POSSIBILITY OF SUCH DAMAGE.
+     */
+    /**
+     * CARP check script for NetBird rc.d service guard.
+     *
+     * Returns exit code 0 if service can start:
+     *   - CARP mode not enabled for NetBird, OR
+     *   - Current host is CARP MASTER
+     *
+     * Returns exit code 1 if service should NOT start:
+     *   - CARP mode enabled and current host is BACKUP
+     *
+     * Usage in rc.d script:
+     *   start_precmd="netbird_precmd"
+     *   netbird_precmd() {
+     *       /usr/local/opnsense/scripts/OPNsense/Netbird/carp_check.php || return 1
+     *   }
+     */
+    require_once('config.inc');
+    require_once('plugins.inc.d/netbird.inc');
+    if (netbird_carp_check_master()) {
+        exit(0);
+    }
+    exit(1);

security/netbird/src/opnsense/scripts/netbird/carp_event.php

-Original file line number
+Diff line change
@@ -0,0 +1,74 @@
+    #!/usr/local/bin/php
+    <?php
+    /*
+     * Copyright (C) 2026 Myah Mitchell, Innovative Networks, Inc. d.b.a INDIGEX
+     * All rights reserved.
+     *
+     * Redistribution and use in source and binary forms, with or without
+     * modification, are permitted provided that the following conditions are met:
+     *
+     * 1. Redistributions of source code must retain the above copyright notice,
+     *    this list of conditions and the following disclaimer.
+     *
+     * 2. Redistributions in binary form must reproduce the above copyright
+     *    notice, this list of conditions and the following disclaimer in the
+     *    documentation and/or other materials provided with the distribution.
+     *
+     * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+     * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+     * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+     * AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+     * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+     * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+     * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+     * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+     * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+     * POSSIBILITY OF SUCH DAMAGE.
+     */
+    /*
+     * Gathers events for 2 seconds; if more are triggered in the same slot,
+     * execute only the last one.  This moves events until we have at least
+     * 2 seconds of "silence" to process them, preventing duplicate actions
+     * when multiple CARP interfaces transition simultaneously during failover.
+     */
+    require_once("config.inc");
+    require_once("util.inc");
+    $subsystem = !empty($argv[1]) ? $argv[1] : 'unknown';
+    $type = !empty($argv[2]) ? $argv[2] : 'unknown';
+    $debounce_ref = '/tmp/tmp_netbird_carp_event.tmp';
+    // Write our PID into the reference file to claim this event slot.
+    // Using file contents (PID) instead of filemtime avoids the 1-second
+    // granularity limit that allows two events arriving in the same second
+    // to both pass the debounce check.
+    $my_token = (string)getmypid();
+    file_put_contents($debounce_ref, $my_token, LOCK_EX);
+    sleep(2);
+    // If another event has overwritten the file with a different PID,
+    // this event is obsolete
+    if (@file_get_contents($debounce_ref) !== $my_token) {
+        log_msg("NetBird CARP: '{$type}' event from '{$subsystem}' ignored, newer event triggered making this obsolete");
+        exit(0);
+    }
+    // We are the last event in the burst — proceed
+    log_msg("NetBird CARP: '{$type}' event from '{$subsystem}', appears to be the last event in burst, processing");
+    switch ($type) {
+        case 'MASTER':
+            log_msg("NetBird CARP: '{$type}' event from '{$subsystem}', starting NetBird's WireGuard interface");
+            mwexecfm('/usr/local/sbin/configctl netbird up');
+            break;
+        case 'BACKUP':
+            log_msg("NetBird CARP: '{$type}' event from '{$subsystem}', stopping NetBird's WireGuard interface");
+            mwexecfm('/usr/local/sbin/configctl netbird down');
+            break;
+    }
+    @unlink($debounce_ref);

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add option to enable HA/CARP failover support to the os-netbird plugin #5067

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Add option to enable HA/CARP failover support to the os-netbird plugin #5067

Are you sure you want to change the base?

Uh oh!

Add option to enable HA/CARP failover support to the os-netbird plugin #5067

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!