public_git
/
pikvm
mirror of https://github.com/pikvm/pikvm.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
pikvm/netbird/index.html

3707 lines
70 KiB
HTML
Raw Blame History

<!DOCTYPE html><html lang="en" class="no-js"><head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="How to configure the access to your PiKVM using NetBird VPN">
<meta name="author" content="Maxim Devaev">
<link rel="canonical" href="https://pikvm.github.io/pikvm/netbird/">
<link rel="prev" href="../cloudflared/">
<link rel="next" href="../wifi/">
<link rel="alternate" type="application/rss+xml" title="RSS feed" href="../feed_rss_created.xml">
<link rel="alternate" type="application/rss+xml" title="RSS feed of updated content" href="../feed_rss_updated.xml">
<link rel="icon" href="../_assets/favicon.ico">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.6">
<title>NetBird VPN - PiKVM Handbook</title>
<link rel="stylesheet" href="../assets/stylesheets/main.484c7ddc.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin="">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=arial,+sans-serif:300,300i,400,400i,700,700i%7Cmonospace:400,400i,700,700i&amp;display=fallback">
<style>:root{--md-text-font:"arial, sans-serif";--md-code-font:"monospace"}</style>
<link rel="stylesheet" href="../_assets/user.css">
<script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
<link href="../assets/stylesheets/glightbox.min.css" rel="stylesheet"><script src="../assets/javascripts/glightbox.min.js"></script><style id="glightbox-style">
html.glightbox-open { overflow: initial; height: 100%; }
.gslide-title { margin-top: 0px; user-select: text; }
.gslide-desc { color: #666; user-select: text; }
.gslide-image img { background: white; }
.gscrollbar-fixer { padding-right: 15px; }
.gdesc-inner { font-size: 0.75rem; }
body[data-md-color-scheme="slate"] .gdesc-inner { background: var(--md-default-bg-color); }
body[data-md-color-scheme="slate"] .gslide-title { color: var(--md-default-fg-color); }
body[data-md-color-scheme="slate"] .gslide-desc { color: var(--md-default-fg-color); }
</style></head>
<body dir="ltr">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#setting-up-the-overlay" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header md-header--shadow" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href=".." title="PiKVM Handbook" class="md-header__button md-logo" aria-label="PiKVM Handbook" data-md-component="logo">
<img src="../_assets/logo.png" alt="logo">
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"></path></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
PiKVM Handbook
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
NetBird VPN
</span>
</div>
</div>
</div>
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"></path></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required="">
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"></path></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"></path></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<a href="javascript:void(0)" class="md-search__icon md-icon" title="Share" aria-label="Share" data-clipboard="" data-clipboard-text="" data-md-component="search-share" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11c.54.5 1.25.81 2.04.81a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3c0 .24.04.47.09.7L8.04 9.81C7.5 9.31 6.79 9 6 9a3 3 0 0 0-3 3 3 3 0 0 0 3 3c.79 0 1.5-.31 2.04-.81l7.12 4.15c-.05.21-.08.43-.08.66 0 1.61 1.31 2.91 2.92 2.91s2.92-1.3 2.92-2.91A2.92 2.92 0 0 0 18 16.08"></path></svg>
</a>
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"></path></svg>
</button>
</nav>
<div class="md-search__suggest" data-md-component="search-suggest"></div>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix="">
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
<div class="md-header__source">
<a href="https://github.com/pikvm/pikvm" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"></path></svg>
</div>
<div class="md-source__repository">
pikvm/pikvm
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation">
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href=".." title="PiKVM Handbook" class="md-nav__button md-logo" aria-label="PiKVM Handbook" data-md-component="logo">
<img src="../_assets/logo.png" alt="logo">
</a>
PiKVM Handbook
</label>
<div class="md-nav__source">
<a href="https://github.com/pikvm/pikvm" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"></path></svg>
</div>
<div class="md-source__repository">
pikvm/pikvm
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_1">
<label class="md-nav__link" for="__nav_1" id="__nav_1_label" tabindex="">
<span class="md-ellipsis">
Device guides
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_1_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_1">
<span class="md-nav__icon md-icon"></span>
Device guides
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item">
<a href="../v4/" class="md-nav__link">
<span class="md-ellipsis">
PiKVM V4 Mini &amp; Plus
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../v3/" class="md-nav__link">
<span class="md-ellipsis">
PiKVM V3
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../switch/" class="md-nav__link">
<span class="md-ellipsis">
PiKVM Switch
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../v2/" class="md-nav__link">
<span class="md-ellipsis">
DIY PiKVM V2
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../v1/" class="md-nav__link">
<span class="md-ellipsis">
DIY PiKVM V1
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_2">
<label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="">
<span class="md-ellipsis">
Getting started
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_2">
<span class="md-nav__icon md-icon"></span>
Getting started
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item">
<a href="../cheatsheet/" class="md-nav__link">
<span class="md-ellipsis">
Cheat sheet
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../webui/" class="md-nav__link">
<span class="md-ellipsis">
Web UI overview
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../shortcuts/" class="md-nav__link">
<span class="md-ellipsis">
Sending shortcuts
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../config/" class="md-nav__link">
<span class="md-ellipsis">
Configuring PiKVM
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../auth/" class="md-nav__link">
<span class="md-ellipsis">
Authentication &amp; 2FA
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../faq/" class="md-nav__link">
<span class="md-ellipsis">
FAQ &amp; troubleshooting
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../flashing_os/" class="md-nav__link">
<span class="md-ellipsis">
Flashing OS
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" checked="">
<label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="">
<span class="md-ellipsis">
Networking
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3">
<span class="md-nav__icon md-icon"></span>
Networking
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_1" checked="">
<label class="md-nav__link" for="__nav_3_1" id="__nav_3_1_label" tabindex="0">
<span class="md-ellipsis">
Internet access
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_1_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3_1">
<span class="md-nav__icon md-icon"></span>
Internet access
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item">
<a href="../port_forwarding/" class="md-nav__link">
<span class="md-ellipsis">
Port forwarding
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../reverse_proxy/" class="md-nav__link">
<span class="md-ellipsis">
Reverse proxy
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../tailscale/" class="md-nav__link">
<span class="md-ellipsis">
Tailscale VPN
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../cloudflared/" class="md-nav__link">
<span class="md-ellipsis">
Cloudflare tunnel
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
NetBird VPN
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
NetBird VPN
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix="">
<li class="md-nav__item">
<a href="#setting-up-the-overlay" class="md-nav__link">
<span class="md-ellipsis">
Setting up the overlay
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#installing-netbird" class="md-nav__link">
<span class="md-ellipsis">
Installing NetBird
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#updating-netbird" class="md-nav__link">
<span class="md-ellipsis">
Updating NetBird
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#registering-the-device" class="md-nav__link">
<span class="md-ellipsis">
Registering the device
</span>
</a>
<nav class="md-nav" aria-label="Registering the device">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#option-1-setup-key-recommended" class="md-nav__link">
<span class="md-ellipsis">
Option 1: Setup key (recommended)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#option-2-interactive-sso-login" class="md-nav__link">
<span class="md-ellipsis">
Option 2: Interactive SSO login
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#verifying-and-persisting" class="md-nav__link">
<span class="md-ellipsis">
Verifying and persisting
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#configuring-a-client-device" class="md-nav__link">
<span class="md-ellipsis">
Configuring a client device
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#troubleshooting" class="md-nav__link">
<span class="md-ellipsis">
Troubleshooting
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../wifi/" class="md-nav__link">
<span class="md-ellipsis">
Setting up Wi-Fi
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../modem/" class="md-nav__link">
<span class="md-ellipsis">
Setting up 3G/4G/LTE modem
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../letsencrypt/" class="md-nav__link">
<span class="md-ellipsis">
Let's Encrypt certificates
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_4">
<label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="">
<span class="md-ellipsis">
Video
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_4">
<span class="md-nav__icon md-icon"></span>
Video
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item">
<a href="../video/" class="md-nav__link">
<span class="md-ellipsis">
Video modes (WebRTC, Direct)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../webrtc_config/" class="md-nav__link">
<span class="md-ellipsis">
WebRTC configuration
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../edid/" class="md-nav__link">
<span class="md-ellipsis">
Tuning HDMI EDID
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../pass/" class="md-nav__link">
<span class="md-ellipsis">
HDMI passthrough
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../latency/" class="md-nav__link">
<span class="md-ellipsis">
Latency
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_5">
<label class="md-nav__link" for="__nav_5" id="__nav_5_label" tabindex="">
<span class="md-ellipsis">
Peripheral devices
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_5">
<span class="md-nav__icon md-icon"></span>
Peripheral devices
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item">
<a href="../atx_board/" class="md-nav__link">
<span class="md-ellipsis">
ATX board
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../usb/" class="md-nav__link">
<span class="md-ellipsis">
USB configuration
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../usb_pass/" class="md-nav__link">
<span class="md-ellipsis">
USB passthrough
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../audio/" class="md-nav__link">
<span class="md-ellipsis">
Audio / Microphone
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_5_5">
<label class="md-nav__link" for="__nav_5_5" id="__nav_5_5_label" tabindex="0">
<span class="md-ellipsis">
Keyboard &amp; mouse
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_5_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_5_5">
<span class="md-nav__icon md-icon"></span>
Keyboard &amp; mouse
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item">
<a href="../mouse/" class="md-nav__link">
<span class="md-ellipsis">
Mouse modes
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../mouse_jiggler/" class="md-nav__link">
<span class="md-ellipsis">
Mouse jiggler
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../pico_hid/" class="md-nav__link">
<span class="md-ellipsis">
Pico HID (USB, PS/2)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../bluetooth_hid/" class="md-nav__link">
<span class="md-ellipsis">
Bluetooth HID
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../msd/" class="md-nav__link">
<span class="md-ellipsis">
Mass storage drive
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../usb_ethernet/" class="md-nav__link">
<span class="md-ellipsis">
Ethernet-over-USB
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../usb_serial/" class="md-nav__link">
<span class="md-ellipsis">
Serial-over-USB
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../gpio/" class="md-nav__link">
<span class="md-ellipsis">
GPIO (pins, relays, lamps, etc)
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_6">
<label class="md-nav__link" for="__nav_6" id="__nav_6_label" tabindex="">
<span class="md-ellipsis">
Advanced usage
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_6">
<span class="md-nav__icon md-icon"></span>
Advanced usage
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item">
<a href="../auth_advanced/" class="md-nav__link">
<span class="md-ellipsis">
Advanced authentication
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../id/" class="md-nav__link">
<span class="md-ellipsis">
PiKVM identification
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../on_boot_config/" class="md-nav__link">
<span class="md-ellipsis">
On-boot configuration
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../auto_snapshots/" class="md-nav__link">
<span class="md-ellipsis">
Automatic snapshots
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../vnc/" class="md-nav__link">
<span class="md-ellipsis">
Using VNC
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../multiport/" class="md-nav__link">
<span class="md-ellipsis">
Multiport KVM-over-IP
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../wol/" class="md-nav__link">
<span class="md-ellipsis">
Wake-on-LAN the server
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../ipmi/" class="md-nav__link">
<span class="md-ellipsis">
IPMI &amp; Redfish integration
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../pst/" class="md-nav__link">
<span class="md-ellipsis">
Persistent storage
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../prometheus/" class="md-nav__link">
<span class="md-ellipsis">
Prometheus monitoring
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_7">
<label class="md-nav__link" for="__nav_7" id="__nav_7_label" tabindex="">
<span class="md-ellipsis">
Development
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_7">
<span class="md-nav__icon md-icon"></span>
Development
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item">
<a href="../api/" class="md-nav__link">
<span class="md-ellipsis">
HTTP API reference
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../building_os/" class="md-nav__link">
<span class="md-ellipsis">
Building PiKVM OS
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../3d_printing/" class="md-nav__link">
<span class="md-ellipsis">
Cases for 3D printing
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_8">
<label class="md-nav__link" for="__nav_8" id="__nav_8_label" tabindex="">
<span class="md-ellipsis">
Legacy
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_8_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_8">
<span class="md-nav__icon md-icon"></span>
Legacy
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item">
<a href="../arduino_hid/" class="md-nav__link">
<span class="md-ellipsis">
Arduino HID
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../msd_legacy/" class="md-nav__link">
<span class="md-ellipsis">
Big DVD images on old PiKVM
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_9">
<label class="md-nav__link" for="__nav_9" id="__nav_9_label" tabindex="">
<span class="md-ellipsis">
PiKVM info
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_9_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_9">
<span class="md-nav__icon md-icon"></span>
PiKVM info
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item">
<a href="../compliance/" class="md-nav__link">
<span class="md-ellipsis">
Compliance
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_9_2">
<div class="md-nav__link md-nav__container">
<a href="../blog/" class="md-nav__link ">
<span class="md-ellipsis">
Blog &amp; news
</span>
</a>
<label class="md-nav__link " for="__nav_9_2" id="__nav_9_2_label" tabindex="0">
<span class="md-nav__icon md-icon"></span>
</label>
</div>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_9_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_9_2">
<span class="md-nav__icon md-icon"></span>
Blog &amp; news
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_9_2_2">
<label class="md-nav__link" for="__nav_9_2_2" id="__nav_9_2_2_label" tabindex="0">
<span class="md-ellipsis">
Archive
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="3" aria-labelledby="__nav_9_2_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_9_2_2">
<span class="md-nav__icon md-icon"></span>
Archive
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item">
<a href="../blog/archive/2026/" class="md-nav__link">
<span class="md-ellipsis">
2026
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../blog/archive/2025/" class="md-nav__link">
<span class="md-ellipsis">
2025
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../blog/archive/2024/" class="md-nav__link">
<span class="md-ellipsis">
2024
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../blog/archive/2023/" class="md-nav__link">
<span class="md-ellipsis">
2023
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../blog/archive/2022/" class="md-nav__link">
<span class="md-ellipsis">
2022
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../blog/archive/2021/" class="md-nav__link">
<span class="md-ellipsis">
2021
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../blog/archive/2020/" class="md-nav__link">
<span class="md-ellipsis">
2020
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_9_2_3">
<label class="md-nav__link" for="__nav_9_2_3" id="__nav_9_2_3_label" tabindex="0">
<span class="md-ellipsis">
Categories
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="3" aria-labelledby="__nav_9_2_3_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_9_2_3">
<span class="md-nav__icon md-icon"></span>
Categories
</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item">
<a href="../blog/category/development/" class="md-nav__link">
<span class="md-ellipsis">
Development
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../blog/category/products/" class="md-nav__link">
<span class="md-ellipsis">
Products
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../blog/category/releases/" class="md-nav__link">
<span class="md-ellipsis">
Releases
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc">
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix="">
<li class="md-nav__item">
<a href="#setting-up-the-overlay" class="md-nav__link">
<span class="md-ellipsis">
Setting up the overlay
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#installing-netbird" class="md-nav__link">
<span class="md-ellipsis">
Installing NetBird
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#updating-netbird" class="md-nav__link">
<span class="md-ellipsis">
Updating NetBird
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#registering-the-device" class="md-nav__link">
<span class="md-ellipsis">
Registering the device
</span>
</a>
<nav class="md-nav" aria-label="Registering the device">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#option-1-setup-key-recommended" class="md-nav__link">
<span class="md-ellipsis">
Option 1: Setup key (recommended)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#option-2-interactive-sso-login" class="md-nav__link">
<span class="md-ellipsis">
Option 2: Interactive SSO login
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#verifying-and-persisting" class="md-nav__link">
<span class="md-ellipsis">
Verifying and persisting
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#configuring-a-client-device" class="md-nav__link">
<span class="md-ellipsis">
Configuring a client device
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#troubleshooting" class="md-nav__link">
<span class="md-ellipsis">
Troubleshooting
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<h1>NetBird VPN</h1>
<div><p><a href="https://netbird.io/">NetBird</a> can be used to access PiKVM from the Internet
if configuring <a href="../port_forwarding/">port forwarding</a> is not possible or more
security is desired. NetBird is an open-source, self-hostable WireGuard-based mesh
VPN that connects devices peer-to-peer without a central gateway. NetBird also offers a free (for private use)
hosted management service. </p>
<p>Because PiKVM's root filesystem is read-only, NetBird requires an overlay
filesystem so it can write runtime state without modifying the underlying disk.</p>
<p>The origin of this guide can be found <a href="https://netbird.io/knowledge-hub/netbird-on-pikvm">here</a>.</p>
<hr>
<h2 id="setting-up-the-overlay">Setting up the overlay<a class="headerlink" href="#setting-up-the-overlay" title="Permanent link"></a></h2>
<p>The NetBird client stores its state in <code>/var/lib/netbird</code>. On PiKVM this path must be
writable at runtime, so we mount an overlay backed by tmpfs over a persistent
copy of the state.</p>
<ol>
<li>
<p>Switch to read-write mode and create the persistent state directory:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>rw
<span class="gp">[root@pikvm ~]# </span>mkdir<span class="w"> </span>-p<span class="w"> </span>/root/netbird-state
</code></pre></div>
</li>
<li>
<p>Create the helper script. Save as <code>/usr/local/bin/setup-netbird-overlay.sh</code>:</p>
<div class="highlight"><pre><span></span><code><span class="ch">#!/bin/bash</span>
<span class="nb">set</span><span class="w"> </span>-e
<span class="c1"># Mount a tmpfs for writable NetBird state</span>
mkdir<span class="w"> </span>-p<span class="w"> </span>/tmp/netbird-state
mount<span class="w"> </span>-t<span class="w"> </span>tmpfs<span class="w"> </span>tmpfs<span class="w"> </span>/tmp/netbird-state
<span class="c1"># Copy persistent state into the writable tmpfs</span>
<span class="k">if</span><span class="w"> </span><span class="o">[</span><span class="w"> </span>-d<span class="w"> </span>/root/netbird-state<span class="w"> </span><span class="o">]</span><span class="p">;</span><span class="w"> </span><span class="k">then</span>
<span class="w"> </span>cp<span class="w"> </span>-a<span class="w"> </span>/root/netbird-state/.<span class="w"> </span>/tmp/netbird-state/
<span class="k">fi</span>
<span class="c1"># Bind mount over /var/lib/netbird so NetBird sees the writable copy</span>
mkdir<span class="w"> </span>-p<span class="w"> </span>/var/lib/netbird
mountpoint<span class="w"> </span>-q<span class="w"> </span>/var/lib/netbird<span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span>umount<span class="w"> </span>/var/lib/netbird<span class="w"> </span><span class="o">||</span><span class="w"> </span><span class="nb">true</span>
mount<span class="w"> </span>--bind<span class="w"> </span>/tmp/netbird-state<span class="w"> </span>/var/lib/netbird
</code></pre></div>
<p>Make it executable:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>chmod<span class="w"> </span>+x<span class="w"> </span>/usr/local/bin/setup-netbird-overlay.sh
</code></pre></div>
</li>
<li>
<p>Create a systemd unit to run the setup before NetBird starts and save
state back on stop. Save as <code>/etc/systemd/system/netbird-overlay.service</code>:</p>
<div class="highlight"><pre><span></span><code><span class="k">[Unit]</span>
<span class="na">Description</span><span class="o">=</span><span class="s">Setup tmpfs overlay for NetBird</span>
<span class="na">After</span><span class="o">=</span><span class="s">local-fs.target tmp.mount</span>
<span class="na">Before</span><span class="o">=</span><span class="s">netbird@netbird.service</span>
<span class="k">[Service]</span>
<span class="na">Type</span><span class="o">=</span><span class="s">oneshot</span>
<span class="na">ExecStart</span><span class="o">=</span><span class="s">/usr/local/bin/setup-netbird-overlay.sh</span>
<span class="na">ExecStop</span><span class="o">=</span><span class="s">/bin/sh -c 'cp -a /tmp/netbird-state/. /root/netbird-state/'</span>
<span class="na">RemainAfterExit</span><span class="o">=</span><span class="s">yes</span>
<span class="k">[Install]</span>
<span class="na">WantedBy</span><span class="o">=</span><span class="s">multi-user.target</span>
</code></pre></div>
</li>
<li>
<p>Enable the overlay service:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>systemctl<span class="w"> </span>daemon-reload
<span class="gp">[root@pikvm ~]# </span>systemctl<span class="w"> </span><span class="nb">enable</span><span class="w"> </span>netbird-overlay.service
</code></pre></div>
</li>
</ol>
<hr>
<h2 id="installing-netbird">Installing NetBird<a class="headerlink" href="#installing-netbird" title="Permanent link"></a></h2>
<p>NetBird is installed from the <a href="https://aur.archlinux.org/packages/netbird-bin">AUR</a>
using <code>makepkg</code>. The <code>netbird-bin</code> package provides pre-built binaries with SHA256
checksum verification, avoiding the need to compile from source on the Pi.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code>makepkg</code> must not run as root. PiKVM provides the unprivileged <code>kvmd-webterm</code>
user for this purpose.</p>
</div>
<ol>
<li>
<p>Update the system and install the build dependencies, then clone the AUR package:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>pacman<span class="w"> </span>-Syu<span class="w"> </span>--needed<span class="w"> </span>git<span class="w"> </span>base-devel
<span class="gp">[root@pikvm ~]# </span><span class="nb">cd</span><span class="w"> </span>/tmp
<span class="gp">[root@pikvm tmp]# </span>git<span class="w"> </span>clone<span class="w"> </span>https://aur.archlinux.org/netbird-bin.git
<span class="gp">[root@pikvm tmp]# </span>chown<span class="w"> </span>-R<span class="w"> </span>kvmd-webterm:kvmd-webterm<span class="w"> </span>netbird-bin
</code></pre></div>
</li>
<li>
<p>Build the package as the <code>kvmd-webterm</code> user:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm tmp]# </span>su<span class="w"> </span>-s<span class="w"> </span>/bin/bash<span class="w"> </span>kvmd-webterm<span class="w"> </span>-c<span class="w"> </span><span class="s1">'cd /tmp/netbird-bin &amp;&amp; makepkg'</span>
</code></pre></div>
<p>This will download the NetBird binary for your architecture, verify its
SHA256 checksum, and create a pacman package.</p>
</li>
<li>
<p>Install the built package:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm tmp]# </span>pacman<span class="w"> </span>-U<span class="w"> </span>/tmp/netbird-bin/netbird-bin-*.pkg.tar.*
</code></pre></div>
</li>
<li>
<p>Clean up the build directory:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm tmp]# </span>rm<span class="w"> </span>-rf<span class="w"> </span>/tmp/netbird-bin
<span class="gp">[root@pikvm tmp]# </span><span class="nb">cd</span><span class="w"> </span>~
</code></pre></div>
</li>
<li>
<p>Create a systemd override to adapt the service for PiKVM's read-only filesystem:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>mkdir<span class="w"> </span>-p<span class="w"> </span>/etc/systemd/system/netbird@.service.d
</code></pre></div>
<p>Save the following as <code>/etc/systemd/system/netbird@.service.d/pikvm.conf</code>:</p>
<div class="highlight"><pre><span></span><code><span class="k">[Unit]</span>
<span class="na">After</span><span class="o">=</span><span class="s">netbird-overlay.service</span>
<span class="na">Requires</span><span class="o">=</span><span class="s">netbird-overlay.service</span>
<span class="k">[Service]</span>
<span class="na">ExecStart</span><span class="o">=</span>
<span class="na">ExecStart</span><span class="o">=</span><span class="s">/usr/bin/netbird service run --log-file syslog --daemon-addr unix:///var/run/netbird/%i.sock</span>
<span class="na">LogsDirectory</span><span class="o">=</span>
<span class="na">Environment</span><span class="o">=</span><span class="s">NB_DISABLE_SSH_CONFIG=true</span>
</code></pre></div>
<p>The key changes from the default service file are:</p>
<ul>
<li><strong><code>After=</code> and <code>Requires=</code></strong> include <code>netbird-overlay.service</code> so the
overlay is mounted before NetBird starts.</li>
<li><strong><code>ExecStart=</code></strong> is cleared then set with <code>--log-file syslog</code> instead of
a file path, since <code>/var/log</code> is read-only.</li>
<li><strong><code>LogsDirectory=</code></strong> is cleared to prevent systemd from trying to create
a log directory on the read-only filesystem.</li>
<li><strong><code>NB_DISABLE_SSH_CONFIG=true</code></strong> prevents NetBird from writing SSH
shortcut configuration to <code>/etc/ssh/ssh_config.d/99-netbird.conf</code>,
which would fail on the read-only filesystem. This only disables
the convenience of <code>ssh &lt;peer-name&gt;</code> -- SSH over NetBird still works
using the peer's IP address directly.</li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The empty <code>ExecStart=</code> line is <strong>not a typo</strong>. In systemd, <code>ExecStart</code>
is a list-type setting. An empty assignment clears the previous value so
the next line replaces it rather than appending to it.</p>
</div>
</li>
<li>
<p>Enable and start the services:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>systemctl<span class="w"> </span>daemon-reload
<span class="gp">[root@pikvm ~]# </span>systemctl<span class="w"> </span><span class="nb">enable</span><span class="w"> </span>netbird@netbird.service
<span class="gp">[root@pikvm ~]# </span>systemctl<span class="w"> </span>start<span class="w"> </span>netbird-overlay.service
<span class="gp">[root@pikvm ~]# </span>systemctl<span class="w"> </span>start<span class="w"> </span>netbird@netbird.service
</code></pre></div>
</li>
</ol>
<hr>
<h2 id="updating-netbird">Updating NetBird<a class="headerlink" href="#updating-netbird" title="Permanent link"></a></h2>
<p>Since NetBird is installed from the AUR rather than an official repository,
updates must be performed manually by rebuilding the package.</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>rw
<span class="gp">[root@pikvm ~]# </span><span class="nb">cd</span><span class="w"> </span>/tmp
<span class="gp">[root@pikvm tmp]# </span>git<span class="w"> </span>clone<span class="w"> </span>https://aur.archlinux.org/netbird-bin.git
<span class="gp">[root@pikvm tmp]# </span>chown<span class="w"> </span>-R<span class="w"> </span>kvmd-webterm:kvmd-webterm<span class="w"> </span>netbird-bin
<span class="gp">[root@pikvm tmp]# </span>su<span class="w"> </span>-s<span class="w"> </span>/bin/bash<span class="w"> </span>kvmd-webterm<span class="w"> </span>-c<span class="w"> </span><span class="s1">'cd /tmp/netbird-bin &amp;&amp; makepkg'</span>
<span class="gp">[root@pikvm tmp]# </span>pacman<span class="w"> </span>-U<span class="w"> </span>/tmp/netbird-bin/netbird-bin-*.pkg.tar.*
<span class="gp">[root@pikvm tmp]# </span>rm<span class="w"> </span>-rf<span class="w"> </span>/tmp/netbird-bin
<span class="gp">[root@pikvm tmp]# </span><span class="nb">cd</span><span class="w"> </span>~
<span class="gp">[root@pikvm ~]# </span>systemctl<span class="w"> </span>restart<span class="w"> </span>netbird@netbird
<span class="gp">[root@pikvm ~]# </span>ro
</code></pre></div>
<hr>
<h2 id="registering-the-device">Registering the device<a class="headerlink" href="#registering-the-device" title="Permanent link"></a></h2>
<p>There are two ways to register your PiKVM with NetBird. The <code>--disable-dns</code>
flag is used in both cases to prevent NetBird from trying to write to
<code>/etc/resolv.conf</code> on the read-only filesystem.</p>
<h3 id="option-1-setup-key-recommended">Option 1: Setup key (recommended)<a class="headerlink" href="#option-1-setup-key-recommended" title="Permanent link"></a></h3>
<p>Setup keys allow registration without any browser interaction, making them
ideal for headless devices like PiKVM.</p>
<ol>
<li>
<p>Log in to the <a href="https://app.netbird.io/">NetBird dashboard</a> and navigate to
<strong>Setup Keys</strong>. Create a new key.</p>
</li>
<li>
<p>Register your PiKVM using the setup key:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>netbird<span class="w"> </span>up<span class="w"> </span>--setup-key<span class="w"> </span>&lt;YOUR_SETUP_KEY&gt;<span class="w"> </span>--disable-dns
</code></pre></div>
</li>
</ol>
<h3 id="option-2-interactive-sso-login">Option 2: Interactive SSO login<a class="headerlink" href="#option-2-interactive-sso-login" title="Permanent link"></a></h3>
<p>You can also use the standard SSO login flow. PiKVM does not have a browser,
but the activation URL can be opened on any other device.</p>
<ol>
<li>
<p>Start the login flow:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>netbird<span class="w"> </span>up<span class="w"> </span>--disable-dns
</code></pre></div>
</li>
<li>
<p>NetBird will print an activation URL in the terminal, for example:</p>
<div class="highlight"><pre><span></span><code>Please do the SSO login in your browser.
If your browser didn't open automatically, use this URL to log in:
https://login.netbird.io/activate?user_code=XXXX-XXXX
</code></pre></div>
</li>
<li>
<p>Copy this URL and open it in a browser on your computer or phone.
Complete the login there. The PiKVM terminal will proceed automatically
once authentication is confirmed.</p>
</li>
</ol>
<h3 id="verifying-and-persisting">Verifying and persisting<a class="headerlink" href="#verifying-and-persisting" title="Permanent link"></a></h3>
<ol>
<li>
<p>Verify the connection:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>netbird<span class="w"> </span>status
</code></pre></div>
<p>You should see <code>Status: Connected</code> and a NetBird IP address (e.g. <code>100.x.x.x</code>).</p>
</li>
<li>
<p>Persist the authentication state so it survives reboots:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>rw
<span class="gp">[root@pikvm ~]# </span>cp<span class="w"> </span>-a<span class="w"> </span>/tmp/netbird-state/.<span class="w"> </span>/root/netbird-state/
<span class="gp">[root@pikvm ~]# </span>ro
</code></pre></div>
</li>
<li>
<p>Reboot to verify everything starts automatically:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>reboot
</code></pre></div>
</li>
</ol>
<div class="admonition warning">
<p class="admonition-title">Persist state after configuration changes</p>
<p>Because the overlay uses tmpfs, any changes NetBird writes at runtime
(authentication tokens, key rotations, etc.) exist only in RAM. After making
configuration changes or re-authenticating, always persist the state:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>rw
<span class="gp">[root@pikvm ~]# </span>cp<span class="w"> </span>-a<span class="w"> </span>/tmp/netbird-state/.<span class="w"> </span>/root/netbird-state/
<span class="gp">[root@pikvm ~]# </span>ro
</code></pre></div>
</div>
<hr>
<h2 id="configuring-a-client-device">Configuring a client device<a class="headerlink" href="#configuring-a-client-device" title="Permanent link"></a></h2>
<ul>
<li><a href="https://www.netbird.io/download">Download</a> and install the NetBird client
on the system you are using (not the system you want to control).</li>
<li>Check the <a href="https://app.netbird.io/">NetBird dashboard</a> to see your connected peers.</li>
<li>Open <code>https://&lt;netbird_kvm_ip&gt;</code> in your browser to access the PiKVM web interface.</li>
</ul>
<hr>
<h2 id="troubleshooting">Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permanent link"></a></h2>
<ul>
<li>
<p><strong>Service fails with <code>status=209/STDOUT</code></strong>: The service is trying to write
logs to a file on the read-only filesystem. Make sure the systemd override
includes <code>--log-file syslog</code> as described above.</p>
</li>
<li>
<p><strong><code>mount: tmpfs: mount failed</code></strong>: The tmpfs mount in the overlay script is
failing. Check that <code>/tmp</code> is writable and that the script is executable
(<code>chmod +x /usr/local/bin/setup-netbird-overlay.sh</code>).</p>
</li>
<li>
<p><strong>DNS lookup failures (<code>DeadlineExceeded</code>)</strong>: If NetBird cannot reach
<code>api.netbird.io</code>, check that your PiKVM has working DNS resolution:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>curl<span class="w"> </span>-v<span class="w"> </span>--max-time<span class="w"> </span><span class="m">10</span><span class="w"> </span>https://api.netbird.io:443
</code></pre></div>
<p>If DNS is broken, verify <code>/etc/resolv.conf</code> contains a valid nameserver.
A stale NetBird daemon process can also cause this; restart the service:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>systemctl<span class="w"> </span>restart<span class="w"> </span>netbird@netbird
</code></pre></div>
</li>
<li>
<p><strong>Need to re-authenticate after reboot</strong>: You forgot to persist the state.
Run <code>netbird up --setup-key &lt;KEY&gt; --disable-dns</code> again, then persist:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>rw
<span class="gp">[root@pikvm ~]# </span>cp<span class="w"> </span>-a<span class="w"> </span>/tmp/netbird-state/.<span class="w"> </span>/root/netbird-state/
<span class="gp">[root@pikvm ~]# </span>ro
</code></pre></div>
</li>
<li>
<p>If something does not work, the usual advice is to completely remove NetBird
and perform a clean installation:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>rw
<span class="gp">[root@pikvm ~]# </span>netbird<span class="w"> </span>down
<span class="gp">[root@pikvm ~]# </span>systemctl<span class="w"> </span>stop<span class="w"> </span>netbird@netbird
<span class="gp">[root@pikvm ~]# </span>systemctl<span class="w"> </span>disable<span class="w"> </span>netbird@netbird<span class="w"> </span>netbird-overlay
<span class="gp">[root@pikvm ~]# </span>pacman<span class="w"> </span>-Rns<span class="w"> </span>netbird-bin
<span class="gp">[root@pikvm ~]# </span>rm<span class="w"> </span>-rf<span class="w"> </span>/var/lib/netbird<span class="w"> </span>/root/netbird-state
<span class="gp">[root@pikvm ~]# </span>rm<span class="w"> </span>-rf<span class="w"> </span>/etc/systemd/system/netbird@.service.d
<span class="gp">[root@pikvm ~]# </span>reboot
</code></pre></div>
<p>Now follow the instructions from the beginning to re-install.</p>
</li>
</ul></div>
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
<button type="button" class="md-top md-icon" data-md-component="top" hidden="">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"></path></svg>
Back to top
</button>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
<div class="md-copyright__highlight">
Copyright © 2018-2026 Maxim Devaev
</div>
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"annotate": null, "base": "..", "features": ["navigation.indexes", "navigation.sections", "navigation.top", "navigation.expand", "search.highlight", "search.share", "search.suggest", "content.code.copy"], "search": "../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script src="../assets/javascripts/bundle.79ae519e.min.js"></script>
<script src="../_assets/add_paragraphs.js"></script>
<script src="../_assets/scroll_to_summary.js"></script>
<script id="init-glightbox">const lightbox = GLightbox({"touchNavigation": false, "loop": false, "zoomable": true, "draggable": true, "openEffect": "zoom", "closeEffect": "zoom", "slideEffect": "slide"});
document$.subscribe(()=>{ lightbox.reload(); });
</script></body></html>
Reference in New Issue View Git Blame Copy Permalink