github/pikvm
4
0
Fork 0
mirror of https://github.com/pikvm/pikvm.git synced 2024-04-21 12:41:58 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
gh-pages
pikvm/first_steps/index.html
T
 3d28c5f30a Deployed 80ded40 with MkDocs version: 1.5.3
2024-04-16 17:15:09 +00:00

2028 lines
47 KiB
HTML
Raw Permalink 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="Open and cheap DIY IP-KVM on Raspberry Pi">
<meta name="author" content="Maxim Devaev">
<link rel="canonical" href="https://pikvm.github.io/pikvm/first_steps/">
<link rel="prev" href="../v1/">
<link rel="next" href="../auth/">
<link rel="icon" href="../_assets/favicon.ico">
<meta name="generator" content="mkdocs-1.5.3, mkdocs-material-9.5.18">
<title>First steps - PiKVM Handbook</title>
<link rel="stylesheet" href="../assets/stylesheets/main.66ac8b77.min.css">
<link rel="stylesheet" href="../assets/stylesheets/palette.06af60db.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&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>
</head>
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="pink">
<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="#first-steps" 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 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></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">
First steps
</span>
</div>
</div>
</div>
<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.516 6.516 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 5Z"/></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.516 6.516 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 5Z"/></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 11h12Z"/></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-.7 0-.24-.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.91 1.61 0 2.92-1.3 2.92-2.91A2.92 2.92 0 0 0 18 16.08Z"/></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 12 19 6.41Z"/></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" 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 6.5.2 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 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></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 6.5.2 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 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></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--active md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1" checked>
<label class="md-nav__link" for="__nav_1" id="__nav_1_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_1_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_1">
<span class="md-nav__icon md-icon"></span>
Getting started
</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_1_1" >
<label class="md-nav__link" for="__nav_1_1" id="__nav_1_1_label" tabindex="0">
<span class="md-ellipsis">
Device guides
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_1_1_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_1_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 & Plus
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../v3/" class="md-nav__link">
<span class="md-ellipsis">
PiKVM V3 HAT
</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--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">
First steps
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
First steps
</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="#first-power-on" class="md-nav__link">
<span class="md-ellipsis">
First power on
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#getting-access-to-pikvm" class="md-nav__link">
<span class="md-ellipsis">
Getting access to PiKVM
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#configuring-pikvm" class="md-nav__link">
<span class="md-ellipsis">
Configuring PiKVM
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#structure-of-configuration-files" class="md-nav__link">
<span class="md-ellipsis">
Structure of configuration files
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#whats-next" class="md-nav__link">
<span class="md-ellipsis">
What's next?
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#faq-and-troubleshooting" class="md-nav__link">
<span class="md-ellipsis">
FAQ and Troubleshooting
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../auth/" class="md-nav__link">
<span class="md-ellipsis">
Authentication
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../faq/" class="md-nav__link">
<span class="md-ellipsis">
FAQ & Troubleshooting
</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">
Networking
</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>
Networking
</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_2_1" >
<label class="md-nav__link" for="__nav_2_1" id="__nav_2_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_2_1_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_2_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="../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>
</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="../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_3" >
<label class="md-nav__link" for="__nav_3" id="__nav_3_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_3_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3">
<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="../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="../webrtc/" class="md-nav__link">
<span class="md-ellipsis">
H.264 / WebRTC
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../video/" class="md-nav__link">
<span class="md-ellipsis">
Working with video
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../audio/" class="md-nav__link">
<span class="md-ellipsis">
HDMI audio
</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">
Peripheral devices
</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>
Peripheral devices
</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_4_1" >
<label class="md-nav__link" for="__nav_4_1" id="__nav_4_1_label" tabindex="0">
<span class="md-ellipsis">
Keyboard & mouse
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_1_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_4_1">
<span class="md-nav__icon md-icon"></span>
Keyboard & 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="../usb_dynamic/" class="md-nav__link">
<span class="md-ellipsis">
Dynamic USB configuration
</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_5" >
<label class="md-nav__link" for="__nav_5" id="__nav_5_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_5_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_5">
<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="../on_boot_config/" class="md-nav__link">
<span class="md-ellipsis">
On-boot configuration
</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 & 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_6" >
<label class="md-nav__link" for="__nav_6" id="__nav_6_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_6_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_6">
<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_7" >
<label class="md-nav__link" for="__nav_7" id="__nav_7_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_7_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_7">
<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>
</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="#first-power-on" class="md-nav__link">
<span class="md-ellipsis">
First power on
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#getting-access-to-pikvm" class="md-nav__link">
<span class="md-ellipsis">
Getting access to PiKVM
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#configuring-pikvm" class="md-nav__link">
<span class="md-ellipsis">
Configuring PiKVM
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#structure-of-configuration-files" class="md-nav__link">
<span class="md-ellipsis">
Structure of configuration files
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#whats-next" class="md-nav__link">
<span class="md-ellipsis">
What's next?
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#faq-and-troubleshooting" class="md-nav__link">
<span class="md-ellipsis">
FAQ and Troubleshooting
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<div><h1 id="first-steps">First steps<a class="headerlink" href="#first-steps" title="Permanent link"></a></h1>
<hr>
<h2 id="first-power-on">First power on<a class="headerlink" href="#first-power-on" title="Permanent link"></a></h2>
<ol>
<li>
<p>Optional: <a href="../on_boot_config/">setting up Wi-Fi or static IP</a> before booting.<br>
<em>Remember that there is nothing more reliable than wired Ethernet.</em></p>
</li>
<li>
<p><strong>Power up the device.</strong></p>
</li>
<li>
<p><strong>Do not turn off the device until it's fully booted for the first time.</strong><br>
<em>After turning on the power, PiKVM OS will generate unique SSH keys and certificates
and perform all necessary operations on the memory card. It takes a few minutes.</em></p>
</li>
</ol>
<hr>
<h2 id="getting-access-to-pikvm">Getting access to PiKVM<a class="headerlink" href="#getting-access-to-pikvm" title="Permanent link"></a></h2>
<p>By default, PiKVM receives a dynamic IP address via DHCP. PiKVM V3+ devices show it on the built-in OLED display.</p>
<details class="example">
<summary>PiKVM without OLED: finding device in the network</summary>
<p>To determine the IP address of your PiKVM, use one of the following methods:</p>
<ul>
<li><strong>Common way:</strong> Open the web interface of your router and find the list of issued IP addresses there.</li>
<li><strong>Linux-only:</strong> Use command <code>arp-scan --localnet</code>.</li>
<li><strong>Linux, MacOS, Windows:</strong> Download and run <a href="https://angryip.org">Angry IP Scanner</a>.</li>
<li><strong>Windows PowerShell:</strong> Use command <code>arp -a</code>.</li>
</ul>
<p>In order to find PiKVM using the ARP commands, you need to look for the following MACs: <code>B8:27:EB</code>, <code>DC:A6:32</code> or <code>E4:5F:01</code>.</p>
</details>
<p>For future examples, let's assume that PiKVM has received the address <code>192.168.0.100</code>,
which you have successfully detected using the instructions above. The device has also been assigned a hostname <code>pikvm</code>.</p>
<details class="example">
<summary>Access to PiKVM Web Interface</summary>
<p><strong>We recommend using the latest Google Chrome or Chromium</strong>, as they support the largest number of PiKVM features.
Safari and Firefox are in second place. Internet Explorer and the pre-Chromium versions of Microsoft Edge are not supported.</p>
<p>For the first time, it is better to use a browser without extensions or incognito mode,
as some extensions may disrupt the work of PiKVM.</p>
<p><strong>Type the URL in the browser's address bar and press Enter: <code>https://192.168.0.100/</code> or <code>https://pikvm/</code>.</strong></p>
<p><strong>The default user is <code>admin</code>, the password is also <code>admin</code>, and no 2FA code.</strong></p>
<p>After logging in, you will get access to the menu with the main functions.
Using the Web Terminal, you can change system settings and passwords.</p>
<p><em>The latest versions of Google Chrome on Mac OS do not allow access to the page with a self-signed certificate,
which is used in PiKVM by default. You can proceed by typing <code>thisisunsafe</code> and Chrome will then load the page.</em></p>
</details>
<details class="example">
<summary>Access to PiKVM via SSH</summary>
<p>SSH is the most common remote access method in the Linux world. PiKVM is accessible via SSH. This method is used to manage the device:</p>
<ul>
<li><strong>Linux, MacOS:</strong> Open any terminal application and run: <code>ssh root@192.168.0.100</code> or <code>ssh root@pikvm</code>.</li>
<li><strong>Windows:</strong> Use <a href="https://www.putty.org/">PuTTY</a> for this.</li>
</ul>
<p><strong>The default <code>root</code> password is <code>root</code>.</strong></p>
</details>
<div class="admonition tip">
<p class="admonition-title">Obtaining root access</p>
<ul>
<li>If you have logged in via SSH, then most likely you are already <code>root</code>.</li>
<li>To get <code>root</code> in the Web Terminal, use command <code>su -</code> and enter the root password.</li>
</ul>
</div>
<p>PiKVM OS (and the underlying Arch Linux ARM upstream) often receives software updates.
After installation, it makes sense to update the OS.
It's best to do this now, when you have physical access to the device, because if something goes wrong
(for example, the power goes out during the update or some upstream change),
you will need to <a href="../flashing_os/">reflash the memory card</a>.</p>
<details class="example">
<summary>Updating PiKVM OS</summary>
<p>To update, run following commands under the <code>root</code> user:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>pikvm-update
</code></pre></div>
<p>If you encounter an error like:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>pikvm-update
<span class="go">bash: pikvm-update: command not found</span>
</code></pre></div>
<p>It's most likely you have an old OS release. You can update the OS as follows:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>curl<span class="w"> </span>https://files.pikvm.org/update-os.sh<span class="w"> </span><span class="p">|</span><span class="w"> </span>bash
</code></pre></div>
<p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p>
</details>
<p><strong>And now, after all...</strong></p>
<details class="danger">
<summary>✮ ✮ ✮ CHANGE THE PASSWORDS! ✮ ✮ ✮</summary>
<p>PiKVM comes with the following default passwords:</p>
<ul>
<li><strong>Linux admin</strong> (SSH, console, etc.): user <code>root</code>, password <code>root</code>.</li>
<li><strong>PiKVM Web Interface</strong> (<a href="../api/">API</a>, <a href="../vnc/">VNC</a>...): user <code>admin</code>, password <code>admin</code>, no 2FA code.</li>
</ul>
<p><strong>These are two separate entities with independent accounts.</strong></p>
<p>To change passwords, you will need to use the console access via SSH or the Web Terminal.
If you are using the Web Terminal, enter the <code>su -</code> command to get the <code>root</code> access (enter the <code>root</code> user password).</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>rw
<span class="gp">[root@pikvm ~]# </span>passwd<span class="w"> </span>root
<span class="gp">[root@pikvm ~]# </span>kvmd-htpasswd<span class="w"> </span><span class="nb">set</span><span class="w"> </span>admin
<span class="gp">[root@pikvm ~]# </span>ro
</code></pre></div>
<p>If you require additional user for the Web UI access, use the following:</p>
<div class="highlight"><pre><span></span><code><span class="gp">[root@pikvm ~]# </span>kvmd-htpasswd<span class="w"> </span><span class="nb">set</span><span class="w"> </span>&lt;user&gt;<span class="w"> </span><span class="c1"># Set a new user with password or change of an existing one</span>
<span class="gp">[root@pikvm ~]# </span>kvmd-htpasswd<span class="w"> </span>del<span class="w"> </span>&lt;user&gt;<span class="w"> </span><span class="c1"># Remove/delete a user</span>
</code></pre></div>
<p><strong>Optionally you can enable the <a href="../auth/#two-factor-authentication">two-factor authentication</a> for more security.</strong></p>
<p><em>Changing the <a href="../vnc/">VNCAuth passkey</a> and <a href="../ipmi/">IPMI password</a> at the first start of PiKVM is not required,
since these services are disabled by default. But it is here just so that you remember their existence.</em></p>
</details>
<hr>
<h2 id="configuring-pikvm">Configuring PiKVM<a class="headerlink" href="#configuring-pikvm" title="Permanent link"></a></h2>
<p>Most of the PiKVM settings are done through configuration files. All configuration changes must be made from under the <code>root</code> user (i.e. the administrator).</p>
<p>The PiKVM memory card is mounted in read-only mode. It protects the filesystem from damage in case of sudden power outage. To edit any files and make changes, it is necessary to remount the file system to the read-write mode.</p>
<div class="admonition tip">
<p class="admonition-title">Enabling write mode</p>
<ul>
<li>To enable write-mode, run command <code>rw</code> (under <code>root</code>).</li>
<li>To disable it, run command <code>ro</code>.</li>
<li>If you receive the message "Device is busy", perform <code>reboot</code>.</li>
</ul>
</div>
<p>In this handbook, you will often find instructions for editing configuration files. The simplest and most beginner-friendly text editor is <code>nano</code>, but you can also use <code>vim</code>.</p>
<details class="example">
<summary>Editing files in the Web Terminal</summary>
<div class="highlight"><pre><span></span><code><span class="gp">[kvmd-webterm@pikvm ~]$ </span>su<span class="w"> </span>-
<span class="gp">[root@pikvm ~]# </span>rw
<span class="gp">[root@pikvm ~]# </span>nano<span class="w"> </span>/etc/kvmd/override.yaml
<span class="gp">[root@pikvm ~]# </span>ro
<span class="gp">[root@pikvm ~]# </span><span class="nb">exit</span>
<span class="gp">[kvmd-webterm@pikvm ~]$</span>
</code></pre></div>
</details>
<hr>
<h2 id="structure-of-configuration-files">Structure of configuration files<a class="headerlink" href="#structure-of-configuration-files" title="Permanent link"></a></h2>
<p>Most of the PiKVM configuration files are located in the <code>/etc/kvmd</code> directory.</p>
<p>The <code>/etc/kvmd/main.yaml</code> file defines the platform config and <strong>you should never edit it</strong>. To redefine system parameters use the file <code>/etc/kvmd/override.yaml</code>. All other files that are also not recommended for editing have read-only permissions.</p>
<p>In the <code>/etc/kvmd/meta.yaml</code> file you can specify some information regarding the host that this PiKVM manages.</p>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>A complete list of all parameters can be viewed using the <code>kvmd -m</code> command.</p>
</div>
<p>Files with the suffix <code>*.yaml</code> uses the <a href="https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html">YAML syntax</a>
and describes a parameter tree with key-value pairs of different types.
To define the parameters within one section, an indent of 4 spaces is used.
Comments starts with the <code>#</code> symbol.</p>
<div class="admonition warning">
<p class="admonition-title">Only 4 spaces should be used for indentation</p>
<p>Be careful when editing YAML and follow this rule.
Invalid indentation or tabs instead of spaces will cause an error when starting the services.</p>
</div>
<details class="example">
<summary>Sections under the same keys should be merged</summary>
<ul>
<li>
<p><strong>Wrong:</strong></p>
<div class="highlight"><pre><span></span><code><span class="nt">kvmd</span><span class="p">:</span>
<span class="w"> </span><span class="nt">gpio</span><span class="p">:</span>
<span class="w"> </span><span class="nt">drivers</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
<span class="nt">kvmd</span><span class="p">:</span>
<span class="w"> </span><span class="nt">gpio</span><span class="p">:</span>
<span class="w"> </span><span class="nt">scheme</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
</code></pre></div>
</li>
<li>
<p><strong>Correct:</strong></p>
<div class="highlight"><pre><span></span><code><span class="nt">kvmd</span><span class="p">:</span>
<span class="w"> </span><span class="nt">gpio</span><span class="p">:</span>
<span class="w"> </span><span class="nt">drivers</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
<span class="w"> </span><span class="nt">scheme</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
</code></pre></div>
</li>
</ul>
</details>
<hr>
<h2 id="whats-next">What's next?<a class="headerlink" href="#whats-next" title="Permanent link"></a></h2>
<ul>
<li>Set up Internet access using <a href="../port_forwarding/">port forwarding</a> or <a href="../tailscale/">Tailscale VPN</a>.</li>
<li>Explore PiKVM features using the table of contents on the left.</li>
<li>Join our <a href="https://discord.gg/bpmXfz5">Discord</a> to contact the community and developers.</li>
<li>Check out the <a href="https://github.com/pikvm">GitHub</a> - PiKVM is a fully Open Source project!</li>
<li>For Mac OS client: <a href="https://github.com/pikvm/pikvm/issues/965">pin your PiKVM device as an app</a> for quick access.</li>
</ul>
<hr>
<h2 id="faq-and-troubleshooting">FAQ and Troubleshooting<a class="headerlink" href="#faq-and-troubleshooting" title="Permanent link"></a></h2>
<p>If you have any questions or run into problems, take a look at the <a href="../faq/">FAQ</a>.
Seriously, it's really useful!</p>
<p>For any other help and support, you can contact us via the <a href="https://discord.gg/bpmXfz5">Discord chat</a>.</p></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 8v12Z"/></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 &copy; 2018-2022 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">{"base": "..", "features": ["navigation.indexes", "navigation.sections", "navigation.top", "navigation.tracking", "navigation.expand", "search.highlight", "search.share", "search.suggest"], "search": "../assets/javascripts/workers/search.b8dbb3d2.min.js", "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"}}</script>
<script src="../assets/javascripts/bundle.3220b9d7.min.js"></script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink