mirror of
https://github.com/Ylianst/MeshCentral.git
synced 2025-11-23 11:07:40 -05:00
8813 lines
733 KiB
HTML
8813 lines
733 KiB
HTML
|
||
<!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="A remote monitoring and management tool">
|
||
|
||
|
||
<meta name="author" content="Ylianst and others">
|
||
|
||
|
||
<link rel="canonical" href="https://ylianst.github.io/MeshCentral/print_page/">
|
||
|
||
|
||
|
||
|
||
<link rel="icon" href="../images/favicon.ico">
|
||
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.6.22">
|
||
|
||
|
||
|
||
<title>Print Site - MeshCentral Documentation</title>
|
||
|
||
|
||
|
||
<link rel="stylesheet" href="../assets/stylesheets/main.84d31ad4.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=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
|
||
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
|
||
|
||
|
||
|
||
<link rel="stylesheet" href="../css/print-site.css">
|
||
|
||
<link rel="stylesheet" href="../css/print-site-material.css">
|
||
|
||
<link rel="stylesheet" href="../stylesheets/extra.css">
|
||
|
||
<script>__md_scope=new URL("/MeshCentral/",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>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
document.addEventListener('DOMContentLoaded', function () {
|
||
remove_material_navigation();remove_mkdocs_theme_navigation();generate_toc();
|
||
})
|
||
</script>
|
||
</head>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo">
|
||
|
||
|
||
<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="#section-1" class="md-skip">
|
||
Skip to content
|
||
</a>
|
||
|
||
</div>
|
||
<div data-md-component="announce">
|
||
|
||
</div>
|
||
|
||
|
||
|
||
|
||
<header class="md-header" data-md-component="header">
|
||
<nav class="md-header__inner md-grid" aria-label="Header">
|
||
<a href=".." title="MeshCentral Documentation" class="md-header__button md-logo" aria-label="MeshCentral Documentation" data-md-component="logo">
|
||
|
||
<img src="../images/favicon.ico" 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"/></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">
|
||
MeshCentral Documentation
|
||
</span>
|
||
</div>
|
||
<div class="md-header__topic" data-md-component="header-topic">
|
||
<span class="md-ellipsis">
|
||
|
||
Print Site
|
||
|
||
</span>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<form class="md-header__option" data-md-component="palette">
|
||
|
||
|
||
|
||
|
||
<input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to light mode" type="radio" name="__palette" id="__palette_0">
|
||
|
||
<label class="md-header__button md-icon" title="Switch to light mode" for="__palette_1" hidden>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg>
|
||
</label>
|
||
|
||
|
||
|
||
|
||
|
||
<input class="md-option" data-md-color-media="" data-md-color-scheme="slate" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to dark mode" type="radio" name="__palette" id="__palette_1">
|
||
|
||
<label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_0" hidden>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg>
|
||
</label>
|
||
|
||
|
||
</form>
|
||
|
||
|
||
|
||
<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"/></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"/></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"/></svg>
|
||
</label>
|
||
<nav class="md-search__options" aria-label="Search">
|
||
|
||
<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"/></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/Ylianst/MeshCentral" 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"/></svg>
|
||
</div>
|
||
<div class="md-source__repository">
|
||
Ylianst/MeshCentral
|
||
</div>
|
||
</a>
|
||
</div>
|
||
|
||
</nav>
|
||
|
||
</header>
|
||
|
||
<div class="md-container" data-md-component="container">
|
||
|
||
|
||
|
||
|
||
|
||
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
|
||
<div class="md-grid">
|
||
<ul class="md-tabs__list">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href=".." class="md-tabs__link">
|
||
|
||
|
||
|
||
Home
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="../install/abstract/" class="md-tabs__link">
|
||
|
||
|
||
|
||
Install
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="../meshcentral/" class="md-tabs__link">
|
||
|
||
|
||
|
||
MeshCentral
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="../meshcmd/" class="md-tabs__link">
|
||
|
||
|
||
|
||
Submodules and Features
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="../how-to-contribute/" class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
|
||
How to Contribute
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="../design/" class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
|
||
Design and Architecture
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="../other/adfs_sso_guide/" class="md-tabs__link">
|
||
|
||
|
||
|
||
Other
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
|
||
|
||
|
||
<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 md-nav--lifted" aria-label="Navigation" data-md-level="0">
|
||
<label class="md-nav__title" for="__drawer">
|
||
<a href=".." title="MeshCentral Documentation" class="md-nav__button md-logo" aria-label="MeshCentral Documentation" data-md-component="logo">
|
||
|
||
<img src="../images/favicon.ico" alt="logo">
|
||
|
||
</a>
|
||
MeshCentral Documentation
|
||
</label>
|
||
|
||
<div class="md-nav__source">
|
||
<a href="https://github.com/Ylianst/MeshCentral" 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"/></svg>
|
||
</div>
|
||
<div class="md-source__repository">
|
||
Ylianst/MeshCentral
|
||
</div>
|
||
</a>
|
||
</div>
|
||
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--nested">
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1" >
|
||
|
||
|
||
<label class="md-nav__link" for="__nav_1" id="__nav_1_label" tabindex="0">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Home
|
||
|
||
</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>
|
||
Home
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href=".." class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Abstract
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--nested">
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" >
|
||
|
||
|
||
<label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="0">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Install
|
||
|
||
</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>
|
||
Install
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../install/abstract/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Abstract
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../install/quickstart/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Quickstart
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--nested">
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_3" >
|
||
|
||
|
||
<label class="md-nav__link" for="__nav_2_3" id="__nav_2_3_label" tabindex="0">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Installation Guides
|
||
|
||
</span>
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_2_3_label" aria-expanded="false">
|
||
<label class="md-nav__title" for="__nav_2_3">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Installation Guides
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../install/abstract/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Abstract
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../install/advanced/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Advanced
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../install/container/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Container (Docker)
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../install/windows/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Windows
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--nested">
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_4" >
|
||
|
||
|
||
<label class="md-nav__link" for="__nav_2_4" id="__nav_2_4_label" tabindex="0">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Databases
|
||
|
||
</span>
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_2_4_label" aria-expanded="false">
|
||
<label class="md-nav__title" for="__nav_2_4">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Databases
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../install/database/mongodb/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
MongoDB
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../install/database/postgresql/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
PostgreSQL
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../install/database/mariadb/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
MariaDB/MySQL
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../install/database/local/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Local Databases
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--nested">
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_5" >
|
||
|
||
|
||
<label class="md-nav__link" for="__nav_2_5" id="__nav_2_5_label" tabindex="0">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Security
|
||
|
||
</span>
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_2_5_label" aria-expanded="false">
|
||
<label class="md-nav__title" for="__nav_2_5">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Security
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../install/security/crowdsec/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Crowdsec
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../install/security/secure/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Secure Installation
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--nested">
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
|
||
|
||
|
||
<label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
MeshCentral
|
||
|
||
</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>
|
||
MeshCentral
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
MeshCentral Guide
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/config/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
All Configuration Options
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/SSLnletsencrypt/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
SSL/TLS
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/agents/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Agent Information
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/assistant/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Assistant
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/codesigning/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Code Signing
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/debugging/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Debugging
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/devicetabs/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Device Tabs
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/plugins/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Plugins
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/security/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Security
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/tokens/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Tokens
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/faq/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
FAQ
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/tipsntricks/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Tips n Tricks
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../messaging/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Messaging
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/customization/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Customization
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcentral/openidConnectStrategy/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
OpenID Connect Strategy (OIDC)
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--nested">
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
|
||
|
||
|
||
<label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Submodules and Features
|
||
|
||
</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>
|
||
Submodules and Features
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshcmd/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
MeshCmd
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshctrl/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
MeshCtrl
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../meshrouter/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Mesh Router
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../intelamt/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Intel AMT
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../how-to-contribute/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
How to Contribute
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../design/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Design and Architecture
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--nested">
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7" >
|
||
|
||
|
||
<label class="md-nav__link" for="__nav_7" id="__nav_7_label" tabindex="0">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Other
|
||
|
||
</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>
|
||
Other
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../other/adfs_sso_guide/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
ADFS SSO Guide
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../other/meshcentral_satellite/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
MeshCentral Satellite
|
||
|
||
</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="#section-1" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
1 Home
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="1 Home">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#index" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
1.1 Abstract
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#section-2" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2 Install
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="2 Install">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#install-abstract" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.1 Abstract
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#install-quickstart" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.2 Quickstart
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#section-2-3" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.3 Installation Guides
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="2.3 Installation Guides">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#install-abstract" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.3.1 Abstract
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#install-advanced" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.3.2 Advanced
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#install-container" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.3.3 Container (Docker)
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#install-windows" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.3.4 Windows
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#section-2-4" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.4 Databases
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="2.4 Databases">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#install-database-mongodb" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.4.1 MongoDB
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#install-database-postgresql" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.4.2 PostgreSQL
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#install-database-mariadb" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.4.3 MariaDB/MySQL
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#install-database-local" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.4.4 Local Databases
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#section-2-5" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.5 Security
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="2.5 Security">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#install-security-crowdsec" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.5.1 Crowdsec
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#install-security-secure" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
2.5.2 Secure Installation
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#section-3" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3 MeshCentral
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="3 MeshCentral">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.1 MeshCentral Guide
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-config" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.2 All Configuration Options
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-sslnletsencrypt" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.3 SSL/TLS
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-agents" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.4 Agent Information
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-assistant" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.5 Assistant
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-codesigning" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.6 Code Signing
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-debugging" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.7 Debugging
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-devicetabs" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.8 Device Tabs
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-plugins" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.9 Plugins
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-security" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.10 Security
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-tokens" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.11 Tokens
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-faq" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.12 FAQ
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-tipsntricks" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.13 Tips n Tricks
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#messaging" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.14 Messaging
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-customization" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.15 Customization
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcentral-openidconnectstrategy" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
3.16 OpenID Connect Strategy (OIDC)
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#section-4" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
4 Submodules and Features
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="4 Submodules and Features">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshcmd" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
4.1 MeshCmd
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshctrl" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
4.2 MeshCtrl
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#meshrouter" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
4.3 Mesh Router
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#intelamt" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
4.4 Intel AMT
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#how-to-contribute" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
5 How to Contribute
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#design" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
6 Design and Architecture
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#section-7" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
7 Other
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="7 Other">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#other-adfs_sso_guide" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
7.1 ADFS SSO Guide
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#other-meshcentral_satellite" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
7.2 MeshCentral Satellite
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
<div class="md-content" data-md-component="content">
|
||
<article class="md-content__inner md-typeset">
|
||
|
||
|
||
|
||
|
||
|
||
<div id="print-site-page" class="print-site-enumerate-headings print-site-enumerate-figures">
|
||
<section class="print-page">
|
||
<div id="print-page-toc" data-toc-depth="3">
|
||
<nav role='navigation' class='print-page-toc-nav'>
|
||
<h1 class='print-page-toc-title'>Table of Contents</h1>
|
||
</nav>
|
||
</div>
|
||
</section>
|
||
|
||
<section class='print-page md-section' id='section-1' heading-number='1'>
|
||
<h1>Home<a class='headerlink' href='#section-1' title='Permanent link'></a>
|
||
</h1>
|
||
<section class="print-page" id="index" heading-number="1.1"><h1 id="index-meshcentral-documentation">MeshCentral Documentation</h1>
|
||
<h2 id="index-about">About</h2>
|
||
<p>MeshCentral is a full computer management web site. With MeshCentral, you can run your own web server to remotely manage and control computers on a local network or anywhere on the internet. Once you get the server started, create device group and download and install an agent on each computer you want to manage. A minute later, the new computer will show up on the web site and you can take control of it. MeshCentral includes full web-based remote desktop, terminal and file management capability.</p>
|
||
<p>For more information, <a href="https://meshcentral.com">visit MeshCentral.com</a>.</p>
|
||
<h2 id="index-social-media">🌐 Social Media</h2>
|
||
<p><img alt="YouTube" src="https://img.icons8.com/color/16/youtube-play.png" /> <a href="https://www.youtube.com/channel/UCJWz607A8EVlkilzcrb-GKg/videos">YouTube</a><br />
|
||
<img alt="Reddit" src="https://img.icons8.com/color/16/reddit.png" /> <a href="https://www.reddit.com/r/MeshCentral/">Reddit</a><br />
|
||
<img alt="Telegram" src="https://img.icons8.com/color/16/telegram-app.png" /> <a href="https://t.me/meshcentral">Telegram</a><br />
|
||
<img alt="Discord" src="https://img.icons8.com/color/16/discord-logo.png" /> <a href="https://discord.gg/wF9UT3Vjdj">Discord</a><br />
|
||
<img alt="BlueSky" src="https://img.icons8.com/color/16/internet--v1.png" /> <a href="https://bsky.app/profile/meshcentral.bsky.social">BlueSky</a><br />
|
||
<img alt="BlogSpot" src="https://img.icons8.com/color/16/blogger.png" /> <a href="https://meshcentral2.blogspot.com/">BlogSpot</a> </p>
|
||
<h2 id="index-documentation">📚 Documentation</h2>
|
||
<p>The <a href="#meshcentral">User's Guide</a> contains information every administrator should know including usage, the server configuration file, databases, TLS offloading, Lets Encrypt, IP Filtering, Email setup, embedding, server port aliasing, reverse proxy setup, multi factor authentication, branding & terms of use, HashiCorp Vault support, and SSO.</p>
|
||
<p>The <a href="#install-quickstart">Installation Guide</a> has detailed instructions for installing the MeshCentral Server on Windows 8.1, Windows 10, Windows 2012 R2, Amazon Linux 2, Raspberry Pi, Microsoft Azure, Google Cloud, Ubuntu 18, Ubuntu 16 and OpenBSD.</p>
|
||
<p>The <a href="#design">Design and Architecture Guide</a> is a short document that includes information on the design overview, dependencies, source code descriptions of each file, certificates, TLS security, the agent to server handshake, browser to agent relay and WebRTC and the messenger service.</p>
|
||
<h2 id="index-video-tutorials">📺 Video Tutorials</h2>
|
||
<p>You can watch many tutorial videos on the <a href="https://www.youtube.com/channel/UCJWz607A8EVlkilzcrb-GKg/videos">MeshCentral YouTube Channel</a>. Here are some essential ones to get you started :</p>
|
||
<p><strong><a href="https://www.youtube.com/results?search_query=MeshCentral+Installation">MeshCentral - Installation</a></strong><br />
|
||
Installing MeshCentral on <strong>Windows</strong>, <strong>Linux</strong>, and <strong>macOS</strong>.</p>
|
||
<p><strong><a href="https://www.youtube.com/results?search_query=MeshCentral+Basics">MeshCentral - Basics</a></strong><br />
|
||
Learn how to install the agent and use remote <strong>desktop</strong>, <strong>terminal</strong>, and <strong>file access</strong> features.</p>
|
||
<p><strong><a href="https://www.youtube.com/results?search_query=MeshCentral+Two+Factor+Authentication">MeshCentral - Two Factor Authentication</a></strong><br />
|
||
Secure your MeshCentral instance with <strong>two-factor authentication</strong>.</p>
|
||
<p><strong><a href="https://www.youtube.com/results?search_query=MeshCentral+NGINX+Reverse+Proxy">MeshCentral - NGINX Reverse Proxy</a></strong><br />
|
||
Configure MeshCentral with an <strong>NGINX reverse proxy</strong> for better security and scalability.</p>
|
||
<p><strong><a href="https://www.youtube.com/results?search_query=MeshCentral+Android">MeshCentral - Android</a></strong><br />
|
||
Install and use the <strong>MeshCentral Android agent</strong> for mobile device management.</p>
|
||
<p><strong><a href="https://www.youtube.com/results?search_query=MeshCentral+Router+Port+Mapping">MeshCentral - Basics</a></strong><br />
|
||
Use <strong>MeshCentral Router</strong> to <strong>port map TCP connections</strong> securely.</p>
|
||
<h2 id="index-feedback">💬 Feedback</h2>
|
||
<p>If you encounter a problem or have a suggestion to improve the product, you may file an <a href="https://github.com/Ylianst/MeshCentral/issues/">GitHub Issue</a>.<br>
|
||
If you are filing a problem report, you should include:</p>
|
||
<ul>
|
||
<li>The version of the software you are using.<blockquote>
|
||
<p>For example: 1.1.46</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>The Operating System and version.<blockquote>
|
||
<p>For example: Debian 12</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>Any troubleshooting you took to resolve the issue yourself.<blockquote>
|
||
<p>For example: Reinstalling MeshCentral (including OS)</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>Any other similar reports.<blockquote>
|
||
<p>For example: other GitHub issues.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>The observed output.</li>
|
||
<li>The expected output.</li>
|
||
</ul>
|
||
<p>If you are having issues with the following other products, you should file a report on their respective issue pages
|
||
<a href="https://github.com/Ylianst/MeshAgent/issues">MeshAgent</a>
|
||
<a href="https://github.com/Ylianst/MeshCentralRouter/issues">MeshRouter</a>
|
||
License</p>
|
||
<p>This software is licensed under <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache 2.0</a>.</p></section></section>
|
||
<section class='print-page md-section' id='section-2' heading-number='2'>
|
||
<h1>Install<a class='headerlink' href='#section-2' title='Permanent link'></a>
|
||
</h1>
|
||
<section class="print-page" id="install-abstract" heading-number="2.1"><h1 id="install-abstract-installation">Installation</h1>
|
||
<h2 id="install-abstract-abstract">🧾 Abstract</h2>
|
||
<p>These guides are specifically intended to help users install and configure MeshCentral.<br>
|
||
Once installed, you can take a look at the MeshCentral user’s guide,<br>
|
||
for information on how to configure MeshCentral for your specific use.<br>
|
||
In this document, we will look at installing MeshCentral on different operating systems like:</p>
|
||
<p>And remember! The <code>config.json</code> is case insensitive in its keys.</p>
|
||
<ul>
|
||
<li>
|
||
<p>📢 <strong><a href="#install-quickstart">Quick-start</a></strong></p>
|
||
</li>
|
||
<li>
|
||
<p>🧐 <strong><a href="#install-advanced">Advanced Information</a></strong></p>
|
||
</li>
|
||
<li>
|
||
<p>🪟 <strong><a href="#install-windows">Windows-specific</a></strong></p>
|
||
</li>
|
||
</ul></section><section class="print-page" id="install-quickstart" heading-number="2.2"><h1 id="install-quickstart-quickstart">Quickstart</h1>
|
||
<h2 id="install-quickstart-quick-start-guide-basic-npm-installation">🚀 Quick Start Guide: Basic NPM Installation</h2>
|
||
<p>MeshCentral is platform-agnostic, running almost anywhere thanks to being primarily written in JavaScript. This guide covers the simplest way to get started using <strong>NPM</strong>.</p>
|
||
<h3 id="install-quickstart-basic-setup">🛠️ Basic Setup</h3>
|
||
<p>The only prerequisites are <strong>Node.js</strong> and <strong>npm</strong>.</p>
|
||
<hr />
|
||
<h4 id="install-quickstart-1-install-nodejs">1. Install Node.js</h4>
|
||
<ul>
|
||
<li><strong>Linux:</strong> Find installation instructions for your distribution <a href="https://nodejs.org/en/download/package-manager/all">here</a>.</li>
|
||
<li><strong>Windows:</strong> Download the installer from the official site <a href="https://nodejs.org/en">here</a>.</li>
|
||
</ul>
|
||
<blockquote>
|
||
<p>🪟 <strong>Windows Users:</strong> If you prefer an automated setup, you can skip the manual installation and download the <strong>Windows MeshCentral Installer</strong>. However, this is <strong>not recommended for advanced users</strong>.
|
||
<a href="https://meshcentral.com/tools/MeshCentralInstaller.exe">Download Windows MeshCentral Installer</a></p>
|
||
</blockquote>
|
||
<hr />
|
||
<h4 id="install-quickstart-2-install-and-start-meshcentral">2. Install and Start MeshCentral</h4>
|
||
<p>Create a dedicated directory (e.g., <code>/opt/meshcentral</code>) and run the following commands in your terminal.</p>
|
||
<blockquote>
|
||
<p>⚠️ <strong>Do not</strong> use <code>sudo</code> with the <code>npm install meshcentral</code> command.</p>
|
||
</blockquote>
|
||
<div class="highlight"><pre><span></span><code><span class="c1"># Example: Create and move into the directory</span>
|
||
mkdir<span class="w"> </span>-p<span class="w"> </span>/opt/meshcentral
|
||
<span class="nb">cd</span><span class="w"> </span>/opt/meshcentral
|
||
|
||
<span class="c1"># Install the MeshCentral package</span>
|
||
npm<span class="w"> </span>install<span class="w"> </span>meshcentral
|
||
|
||
<span class="c1"># Start the server</span>
|
||
node<span class="w"> </span>node_modules/meshcentral
|
||
</code></pre></div>
|
||
<p>That's it! MeshCentral will now set itself up and begin managing computers on your <strong>local network</strong> that have the MeshAgent installed.</p>
|
||
<h4 id="install-quickstart-running-as-a-service">Running as a Service</h4>
|
||
<p>To run MeshCentral as a persistent background service (recommended for production environments), use the --install argument when starting the server. Consult the MeshCentral documentation for OS-specific service setup details.</p>
|
||
<hr />
|
||
<h3 id="install-quickstart-configuration-and-customization">⚙️ Configuration and Customization</h3>
|
||
<h4 id="install-quickstart-default-mode-and-initial-access">Default Mode and Initial Access</h4>
|
||
<p>By default, MeshCentral starts in <strong>LAN-only mode</strong>. Agents use local network multicasting to find the server.</p>
|
||
<ul>
|
||
<li>The first user account you create upon accessing the server will automatically become the <strong>server administrator</strong>. Access the login page in your web browser and create your account right away.</li>
|
||
<li>Once installed, server settings are stored in the <strong><code>config.json</code></strong> file, which is located inside the <strong><code>meshcentral-data</code></strong> folder.</li>
|
||
</ul>
|
||
<h4 id="install-quickstart-advanced-configuration">Advanced Configuration</h4>
|
||
<p>The <strong><code>config.json</code></strong> file holds hundreds of options for deep customization, including:</p>
|
||
<ul>
|
||
<li>Switching the server from LAN-only to <strong>WAN/Hybrid mode</strong> by setting a known DNS name.</li>
|
||
<li>Customizing the server with your own <strong>branding</strong>.</li>
|
||
<li>Setting up an <strong>SMTP email server</strong> or <strong>SMS services</strong>.</li>
|
||
</ul>
|
||
<p>The configuration file must be valid <strong>JSON</strong>. You can use an online tool or utilities like <code>jq</code> to validate its format.</p>
|
||
<p>You can find sample configuration files on the GitHub repository for reference:</p>
|
||
<ul>
|
||
<li><a href="https://github.com/Ylianst/MeshCentral/blob/master/sample-config.json">Simple sample config</a></li>
|
||
<li><a href="https://github.com/Ylianst/MeshCentral/blob/master/sample-config-advanced.json">Advanced sample config</a></li>
|
||
<li><a href="https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json">Full config schema</a></li>
|
||
</ul>
|
||
<hr />
|
||
<h3 id="install-quickstart-database-and-scaling-notes">Database and Scaling Notes</h3>
|
||
<ul>
|
||
<li><strong>Database:</strong> By default, MeshCentral uses <strong>NeDB</strong>, its built-in database. For advanced use cases and better performance, it's recommended to switch to <strong>MongoDB</strong> or an SQL-based solution like <strong>Postgresql</strong>.</li>
|
||
<li><strong>Hardware:</strong> MeshCentral is very lightweight. You can run a server capable of managing a few hundred devices on a small platform like a <strong>Raspberry Pi</strong> or an <strong>AWS t3.nano</strong> instance running Linux.</li>
|
||
<li><strong>Service Mode:</strong> To run the server as a background service, start it with the <code>--help</code> argument to view options for background installation.</li>
|
||
</ul>
|
||
<p>For a visual guide, check out the official <a href="https://www.youtube.com/@MeshCentral/videos">YouTube Tutorial Videos</a>.</p>
|
||
<p>\<div class="video-wrapper">
|
||
\<iframe src="<a href="https://www.youtube.com/embed/LSiWuu71k_U">https://www.youtube.com/embed/LSiWuu71k_U</a>" frameborder="0" allowfullscreen>\</iframe>
|
||
\</div></p>
|
||
<hr />
|
||
<p>Do you want to know more about configuring the server for WAN access or switching to a different database?</p></section>
|
||
<section class='print-page md-section' id='section-2-3' heading-number='2.3'>
|
||
<h1>Installation Guides<a class='headerlink' href='#section-2-3' title='Permanent link'></a>
|
||
</h1>
|
||
<section class="print-page" id="install-abstract" heading-number="2.3.1"><h1 id="install-abstract-installation">Installation</h1>
|
||
<h2 id="install-abstract-abstract">🧾 Abstract</h2>
|
||
<p>These guides are specifically intended to help users install and configure MeshCentral.<br>
|
||
Once installed, you can take a look at the MeshCentral user’s guide,<br>
|
||
for information on how to configure MeshCentral for your specific use.<br>
|
||
In this document, we will look at installing MeshCentral on different operating systems like:</p>
|
||
<p>And remember! The <code>config.json</code> is case insensitive in its keys.</p>
|
||
<ul>
|
||
<li>
|
||
<p>📢 <strong><a href="#install-quickstart">Quick-start</a></strong></p>
|
||
</li>
|
||
<li>
|
||
<p>🧐 <strong><a href="#install-advanced">Advanced Information</a></strong></p>
|
||
</li>
|
||
<li>
|
||
<p>🪟 <strong><a href="#install-windows">Windows-specific</a></strong></p>
|
||
</li>
|
||
</ul></section><section class="print-page" id="install-advanced" heading-number="2.3.2"><h1 id="install-advanced-npm-installation-for-advanced-users">📦 NPM Installation for Advanced Users</h1>
|
||
<p><img alt="" src="../install/images/2022-05-16-23-47-36.jpg" /></p>
|
||
<h2 id="install-advanced-prerequisites-and-verification">Prerequisites and Verification</h2>
|
||
<p>Before beginning the installation, ensure <strong>Node.js</strong> and <strong>NPM</strong> (Node Package Manager) are installed on your host operating system.</p>
|
||
<p>If your server is behind an HTTP/HTTPS proxy, you may need to configure NPM's proxy settings.</p>
|
||
<h3 id="install-advanced-1-verify-nodejs-and-npm">1. Verify Node.js and NPM</h3>
|
||
<p>Open your command-line terminal (CMD/PowerShell on Windows, or Shell on Linux) and run the following commands to check the installed versions:</p>
|
||
<ul>
|
||
<li><strong>Node.js:</strong>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>-v
|
||
</code></pre></div></li>
|
||
<li><strong>NPM:</strong>
|
||
<div class="highlight"><pre><span></span><code>npm<span class="w"> </span>-v
|
||
</code></pre></div></li>
|
||
</ul>
|
||
<hr />
|
||
<h3 id="install-advanced-2-configure-proxy-settings-if-applicable">2. Configure Proxy Settings (If Applicable)</h3>
|
||
<p>If your server requires a proxy to access the internet, you must set the proxy configurations for NPM. <strong>Skip this step if not needed.</strong></p>
|
||
<div class="highlight"><pre><span></span><code><span class="c1"># Set HTTP proxy</span>
|
||
npm<span class="w"> </span>config<span class="w"> </span><span class="nb">set</span><span class="w"> </span>proxy<span class="w"> </span>http://proxy.com:88
|
||
<span class="c1"># Set HTTPS proxy</span>
|
||
npm<span class="w"> </span>config<span class="w"> </span><span class="nb">set</span><span class="w"> </span>https-proxy<span class="w"> </span>http://proxy.com:88
|
||
</code></pre></div>
|
||
<hr />
|
||
<h2 id="install-advanced-meshcentral-installation">MeshCentral Installation</h2>
|
||
<h3 id="install-advanced-3-install-meshcentral">3. Install MeshCentral</h3>
|
||
<p>Create a dedicated directory for the installation, change into it, and use NPM to install the MeshCentral package.</p>
|
||
<p><strong>Recommendation:</strong> On Linux, use the <code>/opt</code> directory.</p>
|
||
<blockquote>
|
||
<p>⚠️ <strong>Important:</strong> Do not use <code>sudo</code> when executing the <code>npm install meshcentral</code> command.</p>
|
||
</blockquote>
|
||
<div class="highlight"><pre><span></span><code><span class="c1"># Create the directory</span>
|
||
mkdir<span class="w"> </span>-p<span class="w"> </span>/opt/meshcentral
|
||
<span class="c1"># Move into the directory</span>
|
||
<span class="nb">cd</span><span class="w"> </span>/opt/meshcentral
|
||
<span class="c1"># Install MeshCentral</span>
|
||
npm<span class="w"> </span>install<span class="w"> </span>meshcentral
|
||
</code></pre></div>
|
||
<hr />
|
||
<h3 id="install-advanced-4-start-the-server">4. Start the Server</h3>
|
||
<p>Once the download is complete, start the MeshCentral server.</p>
|
||
<blockquote>
|
||
<p>⚠️ <strong>Crucial:</strong> <strong>Do not</strong> <code>cd</code> into the <code>node_modules/meshcentral</code> directory to run the server. Running it from the directory <strong>above</strong> <code>node_modules</code> is required for features like auto-install and self-update to function correctly.</p>
|
||
</blockquote>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span><span class="o">[</span>arguments<span class="o">]</span>
|
||
</code></pre></div>
|
||
<blockquote>
|
||
<p><strong>LAN-Only Mode:</strong> If you run the command without arguments, MeshCentral will default to <strong>LAN-only mode</strong>, meaning you can only manage computers on the local network.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<h3 id="install-advanced-5-configure-for-waninternet-access-optional">5. Configure for WAN/Internet Access (Optional)</h3>
|
||
<p>To manage computers over the internet (<strong>WAN</strong> or <strong>Hybrid Mode</strong>), your server needs a <strong>static IP</strong> or a <strong>DNS record</strong> that resolves to its public address. This is how remote mesh agents "call home."</p>
|
||
<p>While command-line parameters exist, it's <strong>highly recommended to use a configuration file</strong> for persistent settings.</p>
|
||
<p>Here are examples of starting the server and generating initial certificates for a public address:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="c1"># Using a domain name</span>
|
||
node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--cert<span class="w"> </span>servername.domain.com
|
||
<span class="c1"># Using an IP address</span>
|
||
node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--cert<span class="w"> </span><span class="m">1</span>.2.3.4
|
||
</code></pre></div>
|
||
<blockquote>
|
||
<p><strong>Note:</strong> The first time you run in WAN or Hybrid Mode, MeshCentral will generate necessary <strong>certificates</strong>, which may take a few minutes.</p>
|
||
</blockquote>
|
||
<p>Once running, immediately create your <strong>admin account</strong> by navigating to <code>https://127.0.0.1</code> (or your public hostname) in a web browser.</p></section><section class="print-page" id="install-container" heading-number="2.3.3"><h1 id="install-container-container-oci-specification">🐳 Container (OCI-specification).</h1>
|
||
<p><a href="https://opencontainers.org/">Open Container Initiative</a></p>
|
||
<p>The following section explains possible ways to install MeshCentral locally with the use of Docker or Podman.
|
||
For the syntax, docker will be used as default. This is done because podman also supports this syntax.<br></p>
|
||
<p>🔗 References:</p>
|
||
<ul>
|
||
<li><a href="https://www.docker.com/">Docker</a> </li>
|
||
<li><a href="https://podman.io/">Podman</a></li>
|
||
</ul>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>Do not use the built-in MeshCentral update functionality (when using containers).<br>
|
||
Update the container the 'docker way', by updating the image itself.</p>
|
||
</div>
|
||
<h3 id="install-container-basic-tags">🏷️ Basic Tags:</h3>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Tag-name</th>
|
||
<th>Explanation</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>master</code></td>
|
||
<td>This tag belongs to the image which is built on every new commit to the main branch, therefor it has the latest code.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>latest</code></td>
|
||
<td>This tag takes the latest released version of MeshCentral.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>1.1.51</code></td>
|
||
<td>You can also specify the specific MeshCentral release with its tag, for example: <code>ghcr.io/ylianst/meshcentral:1.1.43</code></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h3 id="install-container-all-tags">All Tags</h3>
|
||
<p>All master tags below follow the master branch of MeshCentral, the latest and version numbered versions follow the releases.</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Tag-name</th>
|
||
<th>Explanation</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>master-slim</code></td>
|
||
<td>Docker image with no database packages present, which makes it the most lean. Uses NeDB.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>master-mongodb</code></td>
|
||
<td>Docker image with the MongoDB packages installed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>master-postgresql</code></td>
|
||
<td>Docker image with the PostgreSQL packages installed</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>master-mysql</code></td>
|
||
<td>Docker image with the MySQL packages installed</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>1.1.51-slim</code> and <code>latest-slim</code></td>
|
||
<td>Docker image with no database packages present, which makes it the most lean. Uses NeDB.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>1.1.51-mongodb</code> and <code>latest-mongodb</code></td>
|
||
<td>Docker image with the MongoDB packages installed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>1.1.51-postgresql</code> and <code>latest-postgresql</code></td>
|
||
<td>Docker image with the PostgreSQL packages installed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>1.1.51-mysql</code> and <code>latest-mysql</code></td>
|
||
<td>Docker image with the MySQL packages installed.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note:</strong>
|
||
Refer to <a href="https://github.com/Ylianst/MeshCentral/pkgs/container/meshcentral">this page</a> for more information on the container status.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<h2 id="install-container-dockerpodman">🐋 Docker/Podman</h2>
|
||
<p>For single-machine setups such as Docker and Podman.</p>
|
||
<h3 id="install-container-pulling-the-image">Pulling the image:</h3>
|
||
<p>To pull the container image use the following container registry.</p>
|
||
<div class="highlight"><pre><span></span><code>docker<span class="w"> </span>pull<span class="w"> </span>ghcr.io/ylianst/meshcentral:latest
|
||
</code></pre></div>
|
||
<h3 id="install-container-docker-cli">Docker CLI:</h3>
|
||
<p>If you want to run the container from the Terminal, you can use the following command:</p>
|
||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 1</span>
|
||
<span class="normal"> 2</span>
|
||
<span class="normal"> 3</span>
|
||
<span class="normal"> 4</span>
|
||
<span class="normal"> 5</span>
|
||
<span class="normal"> 6</span>
|
||
<span class="normal"> 7</span>
|
||
<span class="normal"> 8</span>
|
||
<span class="normal"> 9</span>
|
||
<span class="normal">10</span></pre></div></td><td class="code"><div><pre><span></span><code>docker<span class="w"> </span>run<span class="w"> </span>-d<span class="w"> </span><span class="se">\</span>
|
||
<span class="w"> </span>--name<span class="w"> </span>meshcentral<span class="w"> </span><span class="se">\</span>
|
||
<span class="w"> </span>--restart<span class="w"> </span>unless-stopped<span class="w"> </span><span class="se">\</span>
|
||
<span class="w"> </span>-p<span class="w"> </span><span class="m">80</span>:80<span class="w"> </span><span class="se">\</span>
|
||
<span class="w"> </span>-p<span class="w"> </span><span class="m">443</span>:443<span class="w"> </span><span class="se">\</span>
|
||
<span class="w"> </span>-v<span class="w"> </span>data:/opt/meshcentral/meshcentral-data<span class="w"> </span><span class="se">\</span>
|
||
<span class="w"> </span>-v<span class="w"> </span>user_files:/opt/meshcentral/meshcentral-files<span class="w"> </span><span class="se">\</span>
|
||
<span class="w"> </span>-v<span class="w"> </span>backup:/opt/meshcentral/meshcentral-backups<span class="w"> </span><span class="se">\</span>
|
||
<span class="w"> </span>-v<span class="w"> </span>web:/opt/meshcentral/meshcentral-web<span class="w"> </span><span class="se">\</span>
|
||
<span class="w"> </span>ghcr.io/ylianst/meshcentral:latest
|
||
</code></pre></div></td></tr></table></div>
|
||
<h3 id="install-container-docker-compose">Docker Compose:</h3>
|
||
<p>If you want to use a docker compose yaml file, please refer to the example below.</p>
|
||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 1</span>
|
||
<span class="normal"> 2</span>
|
||
<span class="normal"> 3</span>
|
||
<span class="normal"> 4</span>
|
||
<span class="normal"> 5</span>
|
||
<span class="normal"> 6</span>
|
||
<span class="normal"> 7</span>
|
||
<span class="normal"> 8</span>
|
||
<span class="normal"> 9</span>
|
||
<span class="normal">10</span>
|
||
<span class="normal">11</span>
|
||
<span class="normal">12</span>
|
||
<span class="normal">13</span>
|
||
<span class="normal">14</span>
|
||
<span class="normal">15</span>
|
||
<span class="normal">16</span>
|
||
<span class="normal">17</span>
|
||
<span class="normal">18</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nt">services</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">meshcentral</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ghcr.io/ylianst/meshcentral:latest</span>
|
||
<span class="w"> </span><span class="nt">environment</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">DYNAMIC_CONFIG=false</span><span class="w"> </span><span class="c1"># Show the option but disable it by default, for safety.</span>
|
||
<span class="w"> </span><span class="nt">volumes</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">meshcentral-data:/opt/meshcentral/meshcentral-data</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">meshcentral-files:/opt/meshcentral/meshcentral-files</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">meshcentral-web:/opt/meshcentral/meshcentral-web</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">meshcentral-backups:/opt/meshcentral/meshcentral-backups</span>
|
||
<span class="w"> </span><span class="nt">ports</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">"80:80"</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">"443:443"</span>
|
||
<span class="nt">volumes</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">meshcentral-data</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">meshcentral-files</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">meshcentral-web</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">meshcentral-backups</span><span class="p">:</span>
|
||
</code></pre></div></td></tr></table></div>
|
||
<p>Refer to <a href="https://github.com/Ylianst/MeshCentral/blob/5032755c2971955161105922e723461385a6c874/docker/Dockerfile#L70-L123">the Dockerfile</a> for its environment variables.</p>
|
||
<h2 id="install-container-kubernetes">☸️ Kubernetes</h2>
|
||
<h3 id="install-container-_1"></h3>
|
||
<blockquote>
|
||
<p>Using YAML deployment files.</p>
|
||
</blockquote>
|
||
<h2 id="install-container-extra-sources">📚 Extra sources</h2>
|
||
<blockquote>
|
||
<p><a href="https://github.com/Ylianst/MeshCentral/tree/master/docker">Github Docker Resources</a></p>
|
||
</blockquote></section><section class="print-page" id="install-windows" heading-number="2.3.4"><h1 id="install-windows-quickstart">Quickstart</h1>
|
||
<h2 id="install-windows-quick-start-on-windows-with-the-installer">🪟 Quick Start on Windows with the Installer</h2>
|
||
<p>For Microsoft Windows users, the easiest way to install MeshCentral is by using the dedicated installer tool. This tool automates the setup, including checking for and installing <strong>Node.js</strong> if necessary.</p>
|
||
<p>You can download the MeshCentral installer from the official website or by clicking <a href="https://www.meshcommander.com/meshcentral2">this link</a>.</p>
|
||
<blockquote>
|
||
<p><strong>Recommendation:</strong> We advise running the installer on a modern version of Windows (e.g., Windows 8.1, Windows 10, or Windows Server 2012 or newer).</p>
|
||
</blockquote>
|
||
<h3 id="install-windows-installation-prompts-explained">Installation Prompts Explained</h3>
|
||
<p>The installer will guide you through a few key settings:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th style="text-align: left;">Setting</th>
|
||
<th style="text-align: left;">Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td style="text-align: left;"><strong>Multi-user Server</strong></td>
|
||
<td style="text-align: left;"><strong>Enabled (Checked):</strong> The server is open to the public. Users can create accounts and manage their own devices. <strong>Disabled (Unchecked):</strong> The server is limited to a single-user mode, with no login screen, accessible only from the server host machine.</td>
|
||
</tr>
|
||
<tr>
|
||
<td style="text-align: left;"><strong>Auto-update Server</strong></td>
|
||
<td style="text-align: left;"><strong>Enabled:</strong> The server automatically checks for new releases daily (typically between 00:00 and 01:00 local time) and performs an update. The server will be inaccessible during the update process.</td>
|
||
</tr>
|
||
<tr>
|
||
<td style="text-align: left;"><strong>Server Mode</strong></td>
|
||
<td style="text-align: left;">Choose how agents find the server:</td>
|
||
</tr>
|
||
<tr>
|
||
<td style="text-align: left;"><em>LAN Mode</em></td>
|
||
<td style="text-align: left;">Recommended for small, local networks. The server does not need a fixed IP or DNS name.</td>
|
||
</tr>
|
||
<tr>
|
||
<td style="text-align: left;"><em>WAN/Hybrid Mode</em></td>
|
||
<td style="text-align: left;">Required for managing devices over the internet. You <strong>must</strong> enter the server's public <strong>DNS name</strong> or <strong>static IP address</strong> into the <strong>Server Name</strong> field. This name must be correct or agents will fail to connect. If unsure, start with <strong>LAN Mode</strong>.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Once installed, MeshCentral runs as a <strong>background Windows Service</strong> and can be accessed via the web browser link provided by the installer.</p>
|
||
<h3 id="install-windows-updating-and-maintenance">Updating and Maintenance</h3>
|
||
<p>The installation tool can be run again at any time to:</p>
|
||
<ul>
|
||
<li><strong>Perform a Server Update:</strong> The tool compares your installed version to the latest one on NPM.</li>
|
||
<li><strong>Re-install</strong> the server.</li>
|
||
<li><strong>Un-install</strong> the server.</li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="install-windows-windows-defender-firewall-settings">🔒 Windows Defender Firewall Settings</h2>
|
||
<p>The installer automatically configures the <strong>Windows Defender Firewall</strong> to allow MeshCentral to accept incoming connections.</p>
|
||
<p>By default, MeshCentral uses the following ports:
|
||
* <strong>TCP Ports:</strong> <strong>80</strong> (HTTP), <strong>443</strong> (HTTPS), and <strong>4433</strong> (Intel® AMT CIRA).
|
||
* <strong>UDP Port:</strong> <strong>16990</strong> (Added for server discovery in LAN or Hybrid mode).</p>
|
||
<p>If you performed an advanced NPM installation or need to change the default ports, you may need to manually modify these firewall rules.</p>
|
||
<h3 id="install-windows-accessing-firewall-settings">Accessing Firewall Settings</h3>
|
||
<ol>
|
||
<li>Open <strong>Control Panel</strong>.</li>
|
||
<li>Go to <strong>System and Security</strong>.</li>
|
||
<li>Click <strong>Windows Defender Firewall</strong>.</li>
|
||
<li>Click <strong>Advanced Settings</strong> on the left side.</li>
|
||
<li>Select <strong>Inbound Rules</strong>.</li>
|
||
</ol>
|
||
<p>If you used the installer, you should see rules named <strong><code>MeshCentral Server TCP ports</code></strong> and optionally <strong><code>MeshCentral Server UDP ports</code></strong>.</p>
|
||
<h3 id="install-windows-1-editing-existing-rules">1. Editing Existing Rules</h3>
|
||
<p>To change the allowed ports (e.g., if you changed the MeshCentral configuration):
|
||
1. <strong>Double-click</strong> the existing rule (e.g., <code>MeshCentral Server TCP ports</code>).
|
||
2. Go to the <strong>Protocols and Ports</strong> tab.
|
||
3. Modify the <strong>Local ports</strong> field.</p>
|
||
<h3 id="install-windows-2-adding-new-rules">2. Adding New Rules</h3>
|
||
<p>To create a new inbound firewall rule:
|
||
1. Click <strong>New Rule...</strong> on the right side.
|
||
2. Select <strong>Port</strong> and click <strong>Next</strong>.
|
||
3. Choose either <strong>TCP</strong> or <strong>UDP</strong>.
|
||
4. Select <strong>Specific local ports</strong> and enter the port numbers (e.g., <code>80, 443, 4433</code>). Click <strong>Next</strong>.
|
||
5. Ensure <strong>Allow the connection</strong> is selected and click <strong>Next</strong>.
|
||
6. Select the profiles (Domain, Private, Public) where the rule should apply and click <strong>Next</strong>.
|
||
7. Enter a descriptive <strong>Name</strong> for the rule and click <strong>Finish</strong>.</p></section></section>
|
||
<section class='print-page md-section' id='section-2-4' heading-number='2.4'>
|
||
<h1>Databases<a class='headerlink' href='#section-2-4' title='Permanent link'></a>
|
||
</h1>
|
||
<section class="print-page" id="install-database-mongodb" heading-number="2.4.1"><h1 id="install-database-mongodb-this-section-will-go-into-how-to-configure-mongodb-as-a-database-backend">This section will go into how to configure MongoDB as a database backend.</h1>
|
||
<p>Following <a href="https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json">the schema</a> we make the following changes to our <code>config.json</code>.<br>
|
||
Some requires keys have been omitted to further the focus on database configuration. Don't remove these as well.</p>
|
||
<hr />
|
||
<h3 id="install-database-mongodb-meshcentral-cheatsheet">MeshCentral Cheatsheet:</h3>
|
||
<p>MongoDB is configured using the MongoDB connection string.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"mongoDb"</span><span class="p">:</span><span class="w"> </span><span class="s2">"mongodb://localhost:27017/meshcentral"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"_letsencrypt"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div></section><section class="print-page" id="install-database-postgresql" heading-number="2.4.2"><h1 id="install-database-postgresql-this-section-will-go-into-how-to-configure-postgresql-as-a-database-backend">This section will go into how to configure PostgreSQL as a database backend.</h1>
|
||
<p>Following <a href="https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json">the schema</a> we make the following changes to our <code>config.json</code>.<br>
|
||
Some requires keys have been omitted to further the focus on database configuration. Don't remove these as well.</p>
|
||
<hr />
|
||
<h3 id="install-database-postgresql-meshcentral-cheatsheet">MeshCentral Cheatsheet:</h3>
|
||
<p>The postgres installation inside <code>settings</code> is rather straightforward if you are familiar with it on MeshCentral its side.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"postgres"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"host"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my-postgresql-hostname"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="s2">"5432"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"user"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my-postgresql-user"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"password"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my-postgresql-password"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"database"</span><span class="p">:</span><span class="w"> </span><span class="s2">"meshcentral-database"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"_letsencrypt"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<blockquote>
|
||
<p>More options are available if needed. Refer to the schema above.</p>
|
||
</blockquote>
|
||
<h3 id="install-database-postgresql-postgres-cheatsheet">Postgres Cheatsheet</h3>
|
||
<div class="highlight"><pre><span></span><code><span class="c1"># Log into the server</span>
|
||
psql<span class="w"> </span>-U<span class="w"> </span>postgres
|
||
</code></pre></div>
|
||
<div class="highlight"><pre><span></span><code><span class="c1">-- Create the database user</span>
|
||
<span class="n">postgres</span><span class="o">=#</span><span class="w"> </span><span class="k">CREATE</span><span class="w"> </span><span class="k">USER</span><span class="w"> </span><span class="n">meshcentral</span><span class="w"> </span><span class="k">WITH</span><span class="w"> </span><span class="n">PASSWORD</span><span class="w"> </span><span class="s1">'your-very-strong-password'</span><span class="p">;</span>
|
||
<span class="k">CREATE</span><span class="w"> </span><span class="k">ROLE</span>
|
||
|
||
<span class="c1">-- Create the database and set the above user as owner</span>
|
||
<span class="n">postgres</span><span class="o">=#</span><span class="w"> </span><span class="k">CREATE</span><span class="w"> </span><span class="k">DATABASE</span><span class="w"> </span><span class="n">meshcentral</span><span class="w"> </span><span class="k">OWNER</span><span class="w"> </span><span class="n">meshcentral</span><span class="p">;</span>
|
||
<span class="k">CREATE</span><span class="w"> </span><span class="k">DATABASE</span>
|
||
|
||
<span class="c1">-- Exit the database</span>
|
||
<span class="n">postgres</span><span class="o">=#</span><span class="w"> </span><span class="n">exit</span>
|
||
</code></pre></div></section><section class="print-page" id="install-database-mariadb" heading-number="2.4.3"><h1 id="install-database-mariadb-this-section-will-go-into-how-to-configure-mysqlmariadb-as-a-database-backend">This section will go into how to configure MySQL/MariaDB as a database backend.</h1>
|
||
<p>Following <a href="https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json">the schema</a> we make the following changes to our <code>config.json</code>.<br>
|
||
Some requires keys have been omitted to further the focus on database configuration. Don't remove these as well.</p>
|
||
<hr />
|
||
<h3 id="install-database-mariadb-meshcentral-cheatsheet">MeshCentral Cheatsheet:</h3>
|
||
<p>Database specific:</p>
|
||
<p>MariaDB:
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"mariaDB"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"host"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my-mariadb-hostname"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3306"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"user"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my-mariadb-user"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"password"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my-mariadb-password"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"database"</span><span class="p">:</span><span class="w"> </span><span class="s2">"meshcentral-database"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"_letsencrypt"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div></p>
|
||
<p>Mysql:
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"mySQL"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"host"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my-mysql-hostname"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3306"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"user"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my-mysql-user"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"password"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my-mysql-password"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"database"</span><span class="p">:</span><span class="w"> </span><span class="s2">"meshcentral-database"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"_letsencrypt"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div></p>
|
||
<h3 id="install-database-mariadb-mariadbmysql-cheatsheet">MariaDB/MySQL Cheatsheet:</h3>
|
||
<p><div class="highlight"><pre><span></span><code>mariadb<span class="w"> </span>-u<span class="w"> </span>root<span class="w"> </span>-p
|
||
</code></pre></div>
|
||
or
|
||
<div class="highlight"><pre><span></span><code>mysql<span class="w"> </span>-u<span class="w"> </span>root<span class="w"> </span>-p
|
||
</code></pre></div></p>
|
||
<div class="highlight"><pre><span></span><code><span class="c1">-- Create the database</span>
|
||
<span class="k">CREATE</span><span class="w"> </span><span class="k">DATABASE</span><span class="w"> </span><span class="n">meshcentral</span><span class="p">;</span>
|
||
|
||
<span class="c1">-- Create the user (restricting login to localhost)</span>
|
||
<span class="k">CREATE</span><span class="w"> </span><span class="k">USER</span><span class="w"> </span><span class="s1">'meshcentral'</span><span class="o">@</span><span class="s1">'localhost'</span><span class="w"> </span><span class="n">IDENTIFIED</span><span class="w"> </span><span class="k">BY</span><span class="w"> </span><span class="s1">'my-very-secure-password'</span><span class="p">;</span>
|
||
|
||
<span class="c1">-- Grant privileges</span>
|
||
<span class="k">GRANT</span><span class="w"> </span><span class="k">ALL</span><span class="w"> </span><span class="k">PRIVILEGES</span><span class="w"> </span><span class="k">ON</span><span class="w"> </span><span class="n">meshcentral</span><span class="p">.</span><span class="o">*</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="s1">'meshcentral'</span><span class="o">@</span><span class="s1">'localhost'</span><span class="p">;</span>
|
||
|
||
<span class="c1">-- Apply changes</span>
|
||
<span class="n">FLUSH</span><span class="w"> </span><span class="k">PRIVILEGES</span><span class="p">;</span>
|
||
</code></pre></div></section><section class="print-page" id="install-database-local" heading-number="2.4.4"><h1 id="install-database-local-this-section-will-go-into-how-to-configure-a-local-database-as-backend">This section will go into how to configure a local database as backend.</h1>
|
||
<p>Following <a href="https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json">the schema</a> we make the following changes to our <code>config.json</code>.<br>
|
||
Some requires keys have been omitted to further the focus on database configuration. Don't remove these as well.</p>
|
||
<p>By default MeshCentral uses NeDB so therefor to change that to another database type, do the following:</p>
|
||
<hr />
|
||
<h3 id="install-database-local-meshcentral-cheatsheet">MeshCentral Cheatsheet:</h3>
|
||
<p>Sqlite3:
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"sqlite3"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"meshcentral-db"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"_letsencrypt"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div></p>
|
||
<p>Acebase:
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"acebase"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"sponsor"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"_letsencrypt"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Omitted these keys to focus on the database"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div></p></section></section>
|
||
<section class='print-page md-section' id='section-2-5' heading-number='2.5'>
|
||
<h1>Security<a class='headerlink' href='#section-2-5' title='Permanent link'></a>
|
||
</h1>
|
||
<section class="print-page" id="install-security-crowdsec" heading-number="2.5.1"><h1 id="install-security-crowdsec-crowdsec">🛡️ Crowdsec</h1>
|
||
<p>MeshCentral has built-in support for a CrowdSec bouncer. This allows MeshCentral to get threat signals from the community and block or CAPTCHA requests coming from known bad IP addresses.</p>
|
||
<h2 id="install-security-crowdsec-video-walkthru">🎬 Video Walkthru</h2>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/TVKF9gBJFCE" frameborder="0" allowfullscreen></iframe>
|
||
</div></section><section class="print-page" id="install-security-secure" heading-number="2.5.2"><h1 id="install-security-secure-secure">Secure</h1>
|
||
<h2 id="install-security-secure-increased-security-installation-on-debianubuntu">🔒 Increased Security Installation on Debian/Ubuntu</h2>
|
||
<p>For enhanced security on Debian-based Linux distributions (like Ubuntu), it's best practice to run <strong>MeshCentral</strong> under a dedicated, low-privilege user account. This prevents the server from making unauthorized changes to the system.</p>
|
||
<blockquote>
|
||
<p>⚠️ <strong>Important:</strong> Running with restricted privileges disables MeshCentral's <strong>self-update capability</strong>. Updates must be performed manually. Additionally, this setup <strong>requires using an external database (like MongoDB)</strong> because the primary data folder will be read-only.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<h3 id="install-security-secure-1-create-a-low-privilege-user">1. Create a Low-Privilege User</h3>
|
||
<p>Start by creating a system user named <code>meshcentral</code>. This user will be restricted from logging in and changing files outside its designated directory.</p>
|
||
<div class="highlight"><pre><span></span><code>sudo<span class="w"> </span>useradd<span class="w"> </span>-r<span class="w"> </span>-d<span class="w"> </span>/opt/meshcentral<span class="w"> </span>-s<span class="w"> </span>/sbin/nologin<span class="w"> </span>meshcentral
|
||
</code></pre></div>
|
||
<h3 id="install-security-secure-2-install-meshcentral">2. Install MeshCentral</h3>
|
||
<p>Next, create the installation directory and install the package using NPM.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="c1"># Create the installation folder</span>
|
||
sudo<span class="w"> </span>mkdir<span class="w"> </span>/opt/meshcentral
|
||
|
||
<span class="c1"># Change to the installation directory</span>
|
||
<span class="nb">cd</span><span class="w"> </span>/opt/meshcentral
|
||
|
||
<span class="c1"># Install MeshCentral (as the created user)</span>
|
||
sudo<span class="w"> </span>-u<span class="w"> </span>meshcentral<span class="w"> </span>npm<span class="w"> </span>install<span class="w"> </span>meshcentral
|
||
</code></pre></div>
|
||
<h3 id="install-security-secure-3-initialize-data-folders">3. Initialize Data Folders</h3>
|
||
<p>Run the server once under the new low-privilege user to generate the necessary data folders and install any initial dependencies.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="c1"># Run once as the meshcentral user</span>
|
||
sudo<span class="w"> </span>-u<span class="w"> </span>meshcentral<span class="w"> </span>node<span class="w"> </span>./node_modules/meshcentral
|
||
</code></pre></div>
|
||
<p>Once the server is running and the folders have been created, press <strong>CTRL-C</strong> to stop the process.</p>
|
||
<h3 id="install-security-secure-4-restrict-permissions">4. Restrict Permissions</h3>
|
||
<p>Now, set the ownership and permissions to ensure the <code>meshcentral</code> user has <strong>read-only access</strong> to the application code, enhancing security.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="c1"># Change ownership of all files to the meshcentral user and group</span>
|
||
sudo<span class="w"> </span>chown<span class="w"> </span>-R<span class="w"> </span>meshcentral:meshcentral<span class="w"> </span>/opt/meshcentral
|
||
|
||
<span class="c1"># Set read/execute permissions for the meshcentral user on data folders</span>
|
||
<span class="c1"># Note: meshcentral-* refers to meshcentral-data, meshcentral-files, etc.</span>
|
||
sudo<span class="w"> </span>chmod<span class="w"> </span>-R<span class="w"> </span><span class="m">755</span><span class="w"> </span>/opt/meshcentral/
|
||
</code></pre></div>
|
||
<h3 id="install-security-secure-5-adjust-write-permissions-for-functionality-optional">5. Adjust Write Permissions for Functionality (Optional)</h3>
|
||
<p>In a restricted environment, you need to explicitly grant write access to specific subfolders the server needs to modify during operation.</p>
|
||
<h4 id="install-security-secure-a-file-uploaddownload">A. File Upload/Download</h4>
|
||
<p>If you plan to use MeshCentral's file transfer features, the server needs to read and write to the <code>meshcentral-files</code> folder:</p>
|
||
<div class="highlight"><pre><span></span><code>sudo<span class="w"> </span>chmod<span class="w"> </span>-R<span class="w"> </span><span class="m">755</span><span class="w"> </span>/opt/meshcentral/meshcentral-files
|
||
</code></pre></div>
|
||
<h4 id="install-security-secure-b-lets-encrypt-support">B. Let's Encrypt Support</h4>
|
||
<p>If you plan to use MeshCentral's built-in <strong>Let's Encrypt</strong> support, you must make its certificate folder writable to avoid <code>ACCES: permission denied</code> exceptions:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="c1"># Create the necessary sub-folders if they don't exist</span>
|
||
sudo<span class="w"> </span>mkdir<span class="w"> </span>-p<span class="w"> </span>/opt/meshcentral/meshcentral-data/letsencrypt
|
||
|
||
<span class="c1"># Grant write access to the letsencrypt folder</span>
|
||
sudo<span class="w"> </span>chmod<span class="w"> </span>-R<span class="w"> </span><span class="m">775</span><span class="w"> </span>/opt/meshcentral/meshcentral-data/letsencrypt
|
||
</code></pre></div>
|
||
<h3 id="install-security-secure-6-manual-server-update">6. Manual Server Update</h3>
|
||
<p>Because the <code>meshcentral</code> user lacks write access to the <code>/node_modules</code> directory, the server cannot update itself. To perform a manual update:</p>
|
||
<ol>
|
||
<li>Use <code>systemctl</code> (or your service manager) to <strong>stop</strong> the MeshCentral server process.</li>
|
||
<li>Run the following commands:</li>
|
||
</ol>
|
||
<!-- end list -->
|
||
|
||
<div class="highlight"><pre><span></span><code><span class="nb">cd</span><span class="w"> </span>/opt/meshcentral
|
||
|
||
<span class="c1"># Update the MeshCentral package via NPM (requires sudo/root privileges)</span>
|
||
sudo<span class="w"> </span>npm<span class="w"> </span>install<span class="w"> </span>meshcentral
|
||
|
||
<span class="c1"># Re-set ownership to the meshcentral user</span>
|
||
sudo<span class="w"> </span>chown<span class="w"> </span>-R<span class="w"> </span>meshcentral:meshcentral<span class="w"> </span>/opt/meshcentral
|
||
</code></pre></div>
|
||
<ol>
|
||
<li>Use <code>systemctl</code> to <strong>restart</strong> the MeshCentral server.</li>
|
||
</ol>
|
||
<p>This process updates the server to the latest version on NPM and reapplies the strict permissions.</p></section></section></section>
|
||
<section class='print-page md-section' id='section-3' heading-number='3'>
|
||
<h1>MeshCentral<a class='headerlink' href='#section-3' title='Permanent link'></a>
|
||
</h1>
|
||
<section class="print-page" id="meshcentral" heading-number="3.1"><h1 id="meshcentral-meshcentral-guide">MeshCentral Guide</h1>
|
||
<h2 id="meshcentral-abstract">🧾 Abstract</h2>
|
||
<p>This user guide contains all essential information for the user to make full use of MeshCentral, a free open source web-based remote computer management software. The guide provides quick steps to setup administrative groups to remote control and manage computers in local network environments or via the Internet. Latter parts of the document will cover some advanced topics. The reader is expected to already have some of the basic understanding on computer networking, operating system and network security.</p>
|
||
<h2 id="meshcentral-introduction">📘 Introduction</h2>
|
||
<p>MeshCentral is a free open source web-based remote computer management software. You could setup your own management server on a local network or on the internet and remote control and manage computers that runs either Windows* or Linux* OS. </p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-22-11-41.jpg" /></p>
|
||
<p>To begin, a base or management server will be required. A management server could be any computing device (PC or VM) that has sufficient compute, storage and reliable network components to host an environment for MeshCentral and deliver good performance during remote management exercise. Whilst there are many configurations available for advanced users, typical server setup would only take just a few minutes to complete. </p>
|
||
<p>At a high level, there are only four (4) main steps : <strong><em>Setup</em></strong>, <strong><em>Install</em></strong>, <strong><em>Connect</em></strong>, and <strong><em>Control</em></strong>. </p>
|
||
<ol>
|
||
<li>Setup the MeshCentral server on VM or PC</li>
|
||
<li>Log on to MeshCentral portal with a valid account, creates an administrative mesh to collect all end-points (systems to be managed)</li>
|
||
<li>Generates an agent and installs it on a target or each end-point that immediately attempts a connection back to MeshCentral server. </li>
|
||
<li>Controls/manages assets or end-points that are available in respective administrative mesh</li>
|
||
</ol>
|
||
<h2 id="meshcentral-video-walkthru">🎬 Video Walkthru</h2>
|
||
<div class="video-wrapper">
|
||
<iframe src="https://www.youtube.com/embed/D9Q7M7PdTg0" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<h2 id="meshcentral-server-installation">🖥️ Server Installation</h2>
|
||
<p>Because the MeshCentral server is written in NodeJS it can be installed on many operating systems including Windows, Linux. Please refer to the MeshCentral Installer’s Guide available at <a href="https://www.meshcommander.com/meshcentral2">https://www.meshcommander.com/meshcentral2</a> for information on how to install the server.</p>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note:</strong></p>
|
||
<p>For information on how to install the server, please refer to the <strong>MeshCentral Installer’s Guide</strong> available at:<br />
|
||
<a href="https://www.meshcommander.com/meshcentral2">https://www.meshcommander.com/meshcentral2</a></p>
|
||
</blockquote>
|
||
<hr />
|
||
<p>The server can be installed both on a local area network for local computer management and in the cloud for management of computers over the Internet. You can also install it on small IoT devices like a Raspberry Pi all the way to big servers. It’s recommended to get started with a test setup to get a feel for this server. Once installed, come back to this document for configuring and using your new server.</p>
|
||
<h2 id="meshcentral-basic-usage">🚀 Basic Usage</h2>
|
||
<p>In this section we will cover the basics of MeshCentral in your newly setup server. </p>
|
||
<h3 id="meshcentral-launch">Launch</h3>
|
||
<p>Start your web browser and access MeshCentral via IP address/URL, <code>http://serverFQDN/</code>. If MeshCentral is running locally, enter <code>http://127.0.0.1/</code>. MeshCentral will redirect the browser to HTTPS if the server was accessed with HTTP. Once on HTTPS you will likely see this message:
|
||
<img alt="" src="../meshcentral/images/2022-05-18-22-16-11.jpg" /></p>
|
||
<p>This is because by default MeshCentral is using a self-signed certificate that is not known to the browser as a “trusted” or “trustworthy” certificate. To prevent this warning from recurring, the following chapter will provide useful steps that can be considered. </p>
|
||
<hr />
|
||
<h4 id="meshcentral-proceeding-with-browser-security-warnings">Proceeding with Browser Security Warnings</h4>
|
||
<h5 id="meshcentral-firefox">Firefox</h5>
|
||
<p>To continue on <strong>Firefox</strong>:</p>
|
||
<ol>
|
||
<li>Click on <em>Advanced</em></li>
|
||
<li>Select <em>Add Exception</em></li>
|
||
<li>Click <em>Confirm Security Exception</em></li>
|
||
</ol>
|
||
<h5 id="meshcentral-chrome">Chrome</h5>
|
||
<p>To continue on <strong>Chrome</strong>:</p>
|
||
<ol>
|
||
<li>Click on <em>Advanced</em></li>
|
||
<li>Click <em>Proceed to <code>http://serverIP</code> (unsafe)</em></li>
|
||
</ol>
|
||
<hr />
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note:</strong></p>
|
||
<p>You can also get to a device by specifying the device name in the URL by adding <em><code>?viewmode=10&gotodevicename=MyComputer</code></em> to the URL of the MeshCentral web page.
|
||
The new <em><code>gotodevicename</code></em> will find a device with the specified name and navigate to that device’s page.
|
||
This is perfect for integrating MeshCentral with other solutions but be aware that a computer name is not a unique identifier and so, <em><code>&gotonode=</code></em> is always the preferred way to access a device. This feature also works on the mobile web site.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<h3 id="meshcentral-create-account">Create Account</h3>
|
||
<p>Create an account by clicking “Create One” and click “Create Account” once the text fields had been populated correctly. As shown in the following image : </p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-22-20-08.jpg" /></p>
|
||
<h3 id="meshcentral-new-device-group">New device group</h3>
|
||
<p>Once logged in, create a new device group. This is a group of computers that we want to manage. To proceed, </p>
|
||
<ol>
|
||
<li>Click on “Click here to create a new group of devices”, </li>
|
||
<li>Key in a suitable “Name”, .e.g. “SampleGroup”</li>
|
||
<li>Leave “Type” to default “Manage using a software agent” and click ‘OK”. </li>
|
||
</ol>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-22-23-59.jpg" /></p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>There are two types of groups: <br>
|
||
- <strong>Software Agent Group</strong>: Commonly used to manage computers. Administrator must install a “remote management agent” on the remote computers. <br>
|
||
- <strong>Intel® AMT Agent-less Group</strong>: Exclusive for remote computers that has Intel® AMT activated and needs to be managed independent of a “remote management agent”.</p>
|
||
</div>
|
||
<h3 id="meshcentral-add-device">Add device</h3>
|
||
<p>To add devices into new mesh</p>
|
||
<ol>
|
||
<li>Click “Add Agent”, </li>
|
||
<li>Select the right Operating Systems (Windows* OS) and download the Mesh Agent executable. </li>
|
||
<li>Copy the Mesh Agent file into remote computers with Windows* OS</li>
|
||
</ol>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-22-25-39.jpg" />
|
||
4. Run Mesh Agent and Click “install”</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-22-26-14.jpg" /></p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Mesh Agent is available for Windows<em>* and Linux</em>*.</p>
|
||
<ul>
|
||
<li>
|
||
<p><em>For Windows</em>*, the mesh agent doesn’t contain any sensitive data and can copied and reused on many Windows* computers.</p>
|
||
</li>
|
||
<li>
|
||
<p><em>For Linux</em>*, instead of an executable, an installation script is provided to add remote computers.</p>
|
||
</li>
|
||
</ul>
|
||
<p>The script checks the type of computer and installs the proper agent automatically. </p>
|
||
</div>
|
||
<h3 id="meshcentral-after-agent-install">After agent install</h3>
|
||
<p>Once the agents are installed, it will take up to a minute before the computer shows up on the user’s account automatically. Click on each computer to access it and user can rename the each computer with a unique name and icons. </p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-22-27-25.jpg" /></p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-22-29-12.jpg" /></p>
|
||
<h3 id="meshcentral-manage-computer">Manage Computer</h3>
|
||
<p>Click on any computer and go into the “Desktop” and “Files” tabs to remotely manage the computer or perform file transfer.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-22-29-40.jpg" /></p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-22-29-47.jpg" /></p>
|
||
<p>For advance users with console/command line interface experience, go into “Terminal” to perform scripting or quick tasks with CLI tools. </p>
|
||
<h3 id="meshcentral-desktop-control">Desktop Control</h3>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/alknFiojQPM" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<p>Depending on how the agent is connected to the server, there are multiple methods to remote control :</p>
|
||
<ul>
|
||
<li><em>Mesh Agent</em>,</li>
|
||
<li><em>RDP</em>, </li>
|
||
<li><em>and AMT</em></li>
|
||
</ul>
|
||
<p>For RDP connections, if you have previously saved the credentials that is usable by all users on the system. If you want to remove those saved credentials that's under the <code>General Tab</code> > <code>Credentials</code>. Click pen to clear them.</p>
|
||
<h2 id="meshcentral-server-certificate">🔐 Server Certificate</h2>
|
||
<p>As seen in the previous chapter, MeshCentral is setup with a self-signed certificate by default and the web browser will issue a warning concerning the validity of the certificate. </p>
|
||
<p>Users have few ways to handle this certificate warning:</p>
|
||
<ul>
|
||
<li>Ignore the warning and proceed with an exception in a recurring fashion. However, traffic from the server to the web browser remains encrypted. User must check the validity of the certificate presented by the website and compare with <code>“webserver-cert-public.crt”</code> file in the <code>“meshcentral-data”</code> folder of the server.</li>
|
||
<li>Add webserver’s root certificate into web browser’s trust list. Click on “Root Certificate” link at the bottom right of login page to download the root certificate of the web server and then add/import this as a trusted certificate into web browser. Some web browser may require a restart before the certificate installation takes effect. </li>
|
||
<li>If you own a domain name that points to your MeshCentral server, you can get a free trusted certificate using Let’s Encrypt (https://letsencrypt.org/). See the section on Let’s Encrypt in this document for more information on this option. MeshCentral has built-in support for Let’ Encrypt.</li>
|
||
</ul>
|
||
<div class="admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>Before adding/importing the certificate, user must check the validity of the certificate presented by the website and compare with <code>“root-cert-public.crt”</code> file in the <code>“meshcentral-data”</code> folder of the server. </p>
|
||
</div>
|
||
<p>For large scale deployments or setup, a legitimate trusted certificate is highly recommended for your web server. This way, any web browser that navigates to this web server will be able to readily verify its authenticity.</p>
|
||
<ul>
|
||
<li>If a legitimate trusted certificate is available, replace <code>“webserver-cert-public.crt”</code> and `“webserver-cert-private.key” with your certificate. These files are located in “meshcentral-data” folder of the server. </li>
|
||
<li>If intermediate certificates are needed, add the files <code>“webserver-cert-chain1.crt”</code>, <code>“webserver-cert-chain2.crt”</code>, <code>“webserver-cert-chain3.crt”</code> respectively with the intermediate certificates.</li>
|
||
</ul>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>If you are using TLS offloading, see the section on “TLS Offloading” cover in the latter parts of this document.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<h2 id="meshcentral-files-and-folder-structure">📁 Files and Folder Structure</h2>
|
||
<p>It’s important to know the basic file and folder structure from which MeshCentral was installed as shown below</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-22-32-35.jpg" /></p>
|
||
<p>Right after running the <code>npm install meshcentral</code> command, the node_module folder will be created which contains meshcentral and all of its dependent modules. When the server executes for the first time, both meshcentral-data and meshcentral-files folders will be created.</p>
|
||
<div class="admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>User must periodically backup both meshcentral-data and meshcentral-files which contains all of server’s data.</p>
|
||
</div>
|
||
<p>The <code>“meshcentral-data”</code> folder will contain:</p>
|
||
<ul>
|
||
<li>
|
||
<p><strong><code>meshcentral.db</code></strong> :</p>
|
||
<p>The server’s database file which contains all of the user and computer information. This includes account information and other sensitive information.</p>
|
||
</li>
|
||
<li>
|
||
<p><strong><code>Five .key and .crt files</code></strong>:</p>
|
||
<p>These are the server’s certificates and private keys. They are used to securely identify the server. The .key files must not be obtained by anyone else since they could be used to impersonate the server.</p>
|
||
</li>
|
||
<li>
|
||
<p><strong><code>config.json file</code></strong>:</p>
|
||
<p>This is the server’s configuration file. It first starts with a sample configuration that you can change. In a following section, we will discuss how to edit this file to customize the server.</p>
|
||
</li>
|
||
</ul>
|
||
<p>The <code>“meshcentral-files”</code> folder contains user files that have been uploaded to the server. This folder can be quite large, especially if no user space quota is set in the config.json file. Users can upload a significant amount of files on the server.</p>
|
||
<div class="admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>Back-up the “meshcentral-data” folder since this is the folder needed to reconstruct the server if something goes wrong. Without it, user will to start over. Recommended to apply suitable encryption on both folders given that they contain sensitive data.</p>
|
||
</div>
|
||
<h2 id="meshcentral-server-configuration-file">⚙️ Server Configuration File</h2>
|
||
<p>In the “meshcentral-data” folder, there is a file called config.json that contains the main configuration of the server. A sample configuration file could look like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"mesh.myserver.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="mi">8080</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"redirport"</span><span class="p">:</span><span class="w"> </span><span class="mi">81</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MyServer"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"title2"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Servername"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"userQuota"</span><span class="p">:</span><span class="w"> </span><span class="mi">1048576</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"meshQuota"</span><span class="p">:</span><span class="w"> </span><span class="mi">248576</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"newAccounts"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">1</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"Customer1"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Customer1"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"title2"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Extra String"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"newAccounts"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">0</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"peers"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"serverId"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"Server1"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"servers"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Server1"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"wss://192.168.1.100:443/"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"Server2"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"wss://192.168.1.101:443/"</span><span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>First, we will look at each of the top levels of the configuration file. The tops levels are <code>“settings”</code>, <code>“domains”</code>, <code>“peers”</code>, and <code>“smtp”</code> as shown in the table below.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18_223720.jpg" /></p>
|
||
<h3 id="meshcentral-settings">Settings</h3>
|
||
<p>As indicated before, the settings section of the config.json is equivalent to passing arguments to the server at runtime. In tha folowing table is a list of settings that are available for the user : </p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th><strong>Setting</strong></th>
|
||
<th><strong>Description</strong></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><strong>Cert</strong></td>
|
||
<td>Sets the DNS name of the server. If this name is not set, the server will run in "LAN mode". When set, the server"s web certificate will use this name and the server will instruct agents and browsers to connect to that DNS name. You must set a server DNS name to run in "WAN mode". MeshCentral will not configure your DNS server. The DNS name must be configured separately.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Port</strong></td>
|
||
<td>This sets the main web port used by the MeshCentral server and it"s the same port that users and mesh agents will connect to. The default port is 443, but if the port is busy, the next available higher port is used (.e.g. 444)</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>AliasPort</strong></td>
|
||
<td>Sets the main port that will be used by the server externally. By default is the same as "Port" above, but can be set to be different when next. See "Server port aliasing" section for more details.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>RedirPort</strong></td>
|
||
<td>This is the port for redirecting traffic in the web server. When the server is configured with HTTPS, users that uses HTTP will be redirected to HTTPS. Port 80 is the default port. So, redirection will happen from port 80 to port 443.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>MpsPort</strong></td>
|
||
<td>Port for Intel" AMT Management Presence Server to receive Intel" AMT CIRA (Client Initiated Remote Access) connections. The default is port 4433. This port is disabled in LAN mode. If user don"t plan on using Intel" AMT for management, this port can be left as-is.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>TLSOffload</strong></td>
|
||
<td>By default this option is set to "false". If set to "true", server will run both web port and the Intel AMT MPS port without TLS with the assumption that a TLS offloading is taking care of this task. For further details, see the "TLS Offloading" section. This option can also be set to the IP address of the reverse-proxy in order to indicate to MeshCental to only trust HTTP X-Forwarded headers coming from this IP address. See the "Reverse-Proxy Setup" section for an example.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>SelfUpdate</strong></td>
|
||
<td>When set to "true" the server will check for a new version and attempt to self-update automatically a bit after midnight local time every day. If set to a specific version such as "1.1.21" the server will immediately update to the specified version on startup if it's not already at this version.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>SessionKey</strong></td>
|
||
<td>This is the encryption key used to secure the user"s login session. It will encrypt the browser cookie. By default, this value is randomly generated each time the server starts. If many servers are used with a load balancer, all servers should use the same session key. In addition, one can set this key so that when the server restarts, users do not need to re-login to the server.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Minify</strong></td>
|
||
<td>Default value is 0, when set to 1 the server will serve "minified" web pages, that is, web pages that have all comments, white spaces and other unused characters removed. This reduces the data size of the web pages by about half and reduced the number requests made by the browser. The source code of the web page will not be easily readable, adding "&nominify=1" at the end of the URL will override this option.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>User</strong></td>
|
||
<td>Specify a username that browsers will be automatically logged in as. Useful to skip the login page and password prompts. Used heavily during development of MeshCentral.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>NoUsers</strong></td>
|
||
<td>By default this option is "false" and if set to "true", server will only accept users from localhost (127.0.0.1) and will not have a login page. Instead, a single user is always logged in. This mode is useful if user opts to setup MeshCentral as a local tool instead of as a multi-user server</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>MpsCert</strong></td>
|
||
<td>Specifies the official name of the Intel AMT MPS server. If not specified, this is the same as the official server name specified by "cert". This option is generally used with MPS aliasing, see the "Server port aliasing" section for more information.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>MpsAliasPort</strong></td>
|
||
<td>Specify an alias port for the MPS server. See the section on "Server port aliasing" for use of this option.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>ExactPorts</strong></td>
|
||
<td>If this option is set to "true", only the exact port will be used. By default, if a port is in use, the server will try to bind the next available higher port. This is true for the "port", "redirport" and "mpsport" settings.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Lanonly</strong></td>
|
||
<td>Server"s default mode if not set with "--cert" option. If this option is set to "true", Intel" AMT MPS will be disabled, server name and fixed IP option will be hidden. Mesh agents will search for the server using multicast on the network.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Wanonly</strong></td>
|
||
<td>A recommended option when running MeshCentral in the cloud. If set to "true", server will run as a cloud service and assumes LAN features are disabled. For this option to work, the server must have a fixed IP or DNS record using the "--cert"" option. In this mode, LAN discovery features are disabled.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>AllowFraming</strong></td>
|
||
<td>By default is set to "false". If set to "true", web pages will be served in a way that allows them to be placed within an iframe of another web page. This is useful when you wish to add MeshCentral features into another website.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>AllowLoginToken</strong></td>
|
||
<td>By default is set to "false". If set to "true", the server allows login tokens to be used in the URL as a replacement for user login. This is useful along with "allowFraming" option to embed MeshCentral features into another website.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>MongoDB</strong></td>
|
||
<td>Used to specify the MongoDB connection string. If not specified, MeshCentral will use the NeDB database with the file meshcentral.db in the meshcentral-data folder. To setup MongoDB, please refer to the Database section of this document.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>MongoDBCol</strong></td>
|
||
<td>Used to specify the MongoDB collection name in the database. By default this value is "meshcentral". See Database section for more details on MongoDB setup.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>DbEncryptKey</strong></td>
|
||
<td>Specifies a password used to encrypt the database when NeDB is in use. If wanting to encrypt an existing database, use the "dbexport" and "dbimport" to save and reload the database with the encryption password set.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>WebRTC</strong></td>
|
||
<td>Set to "true" or "false" depending if you want to allow the server to setup WebRTC communication. If WebRTC is setup, management traffic will flow directly between the browser and mesh agent, bypassing the server completely. The default is false now, but will be switched to true when WebRTC is ready for production.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>ClickOnce</strong></td>
|
||
<td>Set to "true" or "false" to allow or disallow browser ClickOnce features. When enabled, browsers running on Windows will be shown extra options to allow RDP and other sessions thru the MeshCentral server. This requires ClickOnce browser support that is built-in to IE and available as add-in to Chrome and Firefox. Default is true.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<div class="admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>Changes in config.json will NOT take effect until server is restarted.</p>
|
||
</div>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>We recommend the user to use a non-production server to experiment the setting options above.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<h3 id="meshcentral-domains">Domains</h3>
|
||
<p>In the domains section, you can set options for the default domain ("") in addition to creating new domains to establish a multi-tenancy server. For standard configuration, the root domain and other domains will be accessible like this :</p>
|
||
<ul>
|
||
<li>
|
||
<p>🔗 <a href="https://servername:8080/">https://servername:8080/</a> — <em>Default domain</em></p>
|
||
</li>
|
||
<li>
|
||
<p>🔗 <a href="https://servername:8080/customer1">https://servername:8080/customer1</a> — <em>Customer1 domain</em></p>
|
||
</li>
|
||
<li>
|
||
<p>🔗 <a href="https://servername:8080/customer2">https://servername:8080/customer2</a> — <em>Customer2 domain</em></p>
|
||
</li>
|
||
</ul>
|
||
<p>When a user setup many domains, the server considers each domain separately and each domain has separate user accounts, administrators, etc. If a domain has no users, the first created account will be administrator for that domain.</p>
|
||
<p>Each domain has sub-settings as follows:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th><strong><em>Sub Settings</em></strong></th>
|
||
<th><strong><em>Description</em></strong></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><strong>Title & Title2</strong></td>
|
||
<td>This are the strings that will be displayed at the banner of the website. By default title is set to “MeshCentral” and title2 is set to a version number</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>UserQuota</strong></td>
|
||
<td>This is the maximum amount of data in kilobytes that can be placed in the “My Files” tab for a user account.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>MeshQuota</strong></td>
|
||
<td>This is the maximum amount of data in kilobytes that can be placed in the “My Files” tab for a given mesh</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>NewAccounts</strong></td>
|
||
<td>If set to zero (0)</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>UserAllowedIP</strong></td>
|
||
<td>Allows user to set a list of allowed IP addresses. See section on server IP filtering.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Auth</strong></td>
|
||
<td>This mode is often used in corporate environments. When server is running on Windows and this value is set to “sspi”, domain control authentication to the website is performed. In this mode, no login screen is displayed and browser will authenticate using the user’s domain credentials.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Dns</strong></td>
|
||
<td>The DNS record for this domain. If specified, the domain is accessed using a DNS record like “customer1.servername.com” instead of “servername/customer1”. This feature requires the DNS server to be configured to point this server with a valid DNS record.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>CertUrl</strong></td>
|
||
<td>Load the TLS certificate for this domain from this https url. For example “https://127.0.0.1:123”. This option is useful when used along with the “TlsOffload” option. When MeshCentral is not doing any TLS but has a reverse-proxy or TLS offload device doing this work in front of the server, you can use this to have MeshCentral load the certificate from the server in front of MeshCentral.<br><br>This is needed because when agents connect, they need to be told that the certificate they saw upon connecting is the correct one. Using this, MeshCentral will know what certificate the agents are expected to see.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>PasswordRequirements</strong></td>
|
||
<td>Used to specify the minimum password requirements for user authentication to this domain. By default, no password requirements are enforced but the user will see a password strength indicator that is not backed by any verifiable data.<br><br>The value must be set to an object, for example:<br><br><code>{ ""min"": 8, ""max"": 128, ""upper"": 1, ""lower"": 1, ""numeric"": 1, ""nonalpha"": 1 }</code><br><br>This indicated that passwords must be at least 8 characters long and have at least one upper case, one lower case, one numeric and one non-alphanumeric character. You can also set the maximum length of the password, however MeshCentral has already a limit of 256 characters. Specifying anything above this will have no effect.<br><br>Note that password requirements for Intel® AMT are defined by Intel and so, Intel® AMT passwords will always be verified using a separate set of requirements.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>When the DNS value is set for a domain, user can’t access the domain using “servername/customer1” instead it must be accessed with the valid DNS record and the DNS server should be setup to have two or more DNS records pointing to the same IP address.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<p>In this mode, the server will serve a different TLS certificate depending on what DNS record is used to access the server.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-33-08.jpg" /></p>
|
||
<p>As shown in the example above, we have two names that point to the same IP address. Since the configuration specifies the “dns” value, the second domain is only shown when the right name is used. We use “meshcentral” and “devbox” for DNS names, but in practice the user will use fully qualified domain names (FQDN) like “meshcentral.com” or “devbox.meshcentral.com”.</p>
|
||
<h2 id="meshcentral-server-peering">🤝 Server Peering</h2>
|
||
<p>MeshCentral supports server peering. User could setup up many servers to share the task of handling incoming connections from managed clients and consoles. For server peering to function, all servers must have access to the same database, use the same certificates, the same configuration (with the exception of the server name) and servers must be able to communicate with each other behind a load balancer.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-34-22.jpg" /></p>
|
||
<p>Hence, the user is expected to have good understanding on networking, server administration and applications to accomplish this setup. This document will not get into the details of setting up a load-balancer. </p>
|
||
<div class="admonition recommended">
|
||
<p class="admonition-title">Recommended</p>
|
||
<p>Before setting up MeshCentral peering, database migration from NeDB database to MongoDB with replication/sharding option enabled is highly recommend. See: Setting up MeshCentral with MongoDB (section 8.4)</p>
|
||
</div>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-35-19.jpg" /></p>
|
||
<p>The setup flow above guides the user to pull together server peering setup with Meshcentral. (2) Shared storage is compulsory to host user files and it must be accessible from all of the servers. If the server is expected for critical work, replicated shared storage should be considered.</p>
|
||
<p>When Meshcentral is ready for peering setup (5), replicate the “meshcentral-data” directory on each server and configure the “peers” section of the config.json file as shown below. </p>
|
||
<div class="highlight"><pre><span></span><code><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"peers"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"serverId"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"Server1"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"servers"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Server1"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"wss://192.168.1.100:443/"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"Server2"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"wss://192.168.1.101:443/"</span><span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>The configuration above assumes that server1 has an IP address of <code>192.168.1.100</code> and server2 has <code>192.168.1.101</code> respectively. The "serverId" value is a short and unique identifier for each server and it is optional. If it's not specified, the computer hostname is used instead. </p>
|
||
<p>The “servers” section of the configuration file should have the identifier of the server followed by each websocket URL and port (generally 443) of the peer servers. If the servers are running with <code>--tlsoffload</code>, then use “ws://” for the URL instead of <code>wss://</code>. </p>
|
||
<p>When the MongoDB is setup for the first time, a unique identifier is generated and written into the DB. To prevent situations where two servers with different database from peering together, during peering process, each server will validate among each other if they have the same unique DB identifier. Peering connection will only succeed if this condition is met. </p>
|
||
<p>Once peered, all of the servers should act like one single host, no matter which server the user(s) are connected to.</p>
|
||
<h2 id="meshcentral-email-setup">📧 Email Setup</h2>
|
||
<p>We highly recommend the use of an email server (SMTP) because we could allow MeshCentral to verify user account’s email address by sending a confirmation request to the user to complete the account registration and for password recovery, should a user forget account password as illustrated below</p>
|
||
<p>A verification email is sent when a new account is created or if the user requests it in the “My Account” tab.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-00-05.jpg" /></p>
|
||
<p>The password recovery flow when “Reset Account” is triggered at the login page.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-00-18.jpg" /></p>
|
||
<p>Both account verification and password recovery are triggered automatically once SMTP mail server configuration is included into the config.json file.</p>
|
||
<h4 id="meshcentral-smtp-userpass">SMTP: User/Pass</h4>
|
||
<h5 id="meshcentral-normal-server">Normal Server</h5>
|
||
<p>Update the config.json with “smtp” section as shown below and restart the server. </p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"smtp"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"host"</span><span class="p">:</span><span class="w"> </span><span class="s2">"smtp.server.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="mi">25</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"from"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myaddress@server.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"user"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myaddress@server.com"</span><span class="p">,</span><span class="w"> </span><span class="err">#</span><span class="w"> </span><span class="err">Op</span><span class="kc">t</span><span class="err">io</span><span class="kc">nal</span>
|
||
<span class="w"> </span><span class="nt">"pass"</span><span class="p">:</span><span class="w"> </span><span class="s2">"mypassword"</span><span class="p">,</span><span class="w"> </span><span class="err">#</span><span class="w"> </span><span class="err">Op</span><span class="kc">t</span><span class="err">io</span><span class="kc">nal</span>
|
||
<span class="w"> </span><span class="nt">"tls"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w"> </span><span class="err">#</span><span class="w"> </span><span class="err">Op</span><span class="kc">t</span><span class="err">io</span><span class="kc">nal</span><span class="p">,</span><span class="w"> </span><span class="err">de</span><span class="kc">fault</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Please map the host, port values to connect to the right host that provides this SMTP service. For “from” value, administrators may put something like donotreply@server.com, but often times it needs to be a valid address since SMTP server will not send out messages with an invalid reply address. </p>
|
||
<p>Some SMTP servers will require a valid username and password to login to the mail server. This is to prevent unauthorized e-mail correspondence. TLS option can be set to ‘true’ if the SMTP server requires TLS.</p>
|
||
<h5 id="meshcentral-gmail">Gmail</h5>
|
||
<p>One option is to configure MeshCentral work with Google Gmail by setting <code>host</code> with smtp.gmail.com, and <code>port</code> with 587. In the config.json file, use user’s Gmail address for both <code>from</code> and “user” and Gmail password in the “pass” value. You will also need to enable “Less secure app access” in for this Google account. It’s in the account settings, security section:</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-01-19.jpg" /></p>
|
||
<p>If a Google account is setup with 2-factor authentication, the option to allow less secure applications not be available. Because the Google account password is in the MeshCentral config.json file and that strong authentication can’t be used, it’s preferable to use a dedicated Google account for MeshCentral email.</p>
|
||
<h4 id="meshcentral-smtp-oauth-authentication">SMTP: OAuth Authentication</h4>
|
||
<h5 id="meshcentral-gmail_1">Gmail</h5>
|
||
<p>Google has announced that less secure app access will be phased out. For Google Workspace or G-Suite accounts, the following process can be used to allow OAuth2 based authentication with Google's SMTP server. It is likely a very similar process for regular Gmail accounts.</p>
|
||
<p>Start by visiting the Google API console:</p>
|
||
<blockquote>
|
||
<p>🔗 <a href="https://console.developers.google.com/">Google Developers Console</a></p>
|
||
</blockquote>
|
||
<p>First, you will create a new project. Name it something unique in case you need to create more in the future. In this example, I've named the project "MeshCentral"</p>
|
||
<p><img alt="" src="../meshcentral/images/gc-newproject.jpg" /></p>
|
||
<p>Click on the "OAuth Consent Screen" link, Under "APIs and Services" from the left hand menu:</p>
|
||
<p><img alt="" src="../meshcentral/images/gc-oauthconsent.jpg" /></p>
|
||
<p>If you have a Google Workspace account, you will have the option to choose "Internal" application and skip the next steps. If not, you will be required to provide Google with information about why you want access, as well as verifying domain ownership. </p>
|
||
<p><img alt="" src="../meshcentral/images/oauth-internal-external.jpg" /></p>
|
||
<p>Add the Gmail address under which you have created this project to the fields labelled ‘User support email’ and ‘Developer contact information’ so that you will be allowed for authentication. After that, you will want to add a scope for your app, so that your token is valid for gmail:</p>
|
||
<p><img alt="" src="../meshcentral/images/gc-oauthscopes.jpg" /></p>
|
||
<p>Once this is complete, the next step will be to add credentials. </p>
|
||
<p><img alt="" src="../meshcentral/images/gc-oauthcredentials.jpg" /></p>
|
||
<p>Choose OAuth Client</p>
|
||
<p>You will obtain a Client ID and a Client secret once you've completed the process. Be sure to store the secret immediately, as you won't be able to retreive it after you've dismissed the window.</p>
|
||
<p>Next, you will need to visit the Google OAuth Playground:</p>
|
||
<p>https://developers.google.com/oauthplayground</p>
|
||
<p><img alt="" src="../meshcentral/images/gc-playground.webp" /></p>
|
||
<p>Enter your Client ID and secret from the last step. On the left side of the page, you should now see a text box that allows you to add your own scopes. Enter <code>https://mail.google.com</code> and click Authorize API.</p>
|
||
<p>You will need to follow the instructions provided to finish the authorization process. Once that is complete, you should receive a refresh token. The refresh token, Client ID and Client Secret are the final items we need to complete the SMTP section of our config.json. It should now look something like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"smtp"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"host"</span><span class="p">:</span><span class="w"> </span><span class="s2">"smtp.gmail.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="mi">587</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"from"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my@googleaccount.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"auth"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"clientId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<YOUR-CLIENT-ID>"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientSecret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<YOUR-CLIENT-SECRET>"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"refreshToken"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<YOUR-REFRESH-TOKEN>"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"user"</span><span class="p">:</span><span class="w"> </span><span class="s2">"noreply@authorizedgooglealias.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"emailDelaySeconds"</span><span class="p">:</span><span class="w"> </span><span class="mi">10</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"tls"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"verifyEmail"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Regardless of what SMTP account is used, MeshCentral will perform a test connection to make sure the server if working as expected when starting. Hence, the user will be notified if Meshcentral and SMTP server has been configured correctly as shown below.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-01-43.jpg" /></p>
|
||
<p>After successfully configuring the Gmail SMTP server, switch the OAuth 'Publishing Status' from <code>Testing</code> to <code>In Production</code>. This step prevents the need for frequent refresh token generation. Verification of your project isn't required to make this change.</p>
|
||
<p><img alt="" src="../meshcentral/images/in-production.jpg" /></p>
|
||
<h2 id="meshcentral-database">🛢️ Database</h2>
|
||
<p>A critical component of MeshCentral is the database. The database stores all of the user account information, groups and node data, historical power and event, etc. By default MeshCentral uses <a href="https://github.com/louischatriot/nedb">NeDB</a> that is written entirely in NodeJS and is setup automatically when MeshCentral is installed with the npm tool. The file <code>meshcentral.db</code> will be created in the “meshcentral-data” folder when MeshCentral is first launched. This database works well for small deployments scenarios.</p>
|
||
<p>Besides NeDB, MeshCentral fully supports MongoDB for larger deployments or deployments that require robust reliability or load-balancing. In this section we will see look at how to export and import the database file with a JSON file and how to configure MongoDB.</p>
|
||
<h3 id="meshcentral-database-export">Database Export</h3>
|
||
<p>User could use a practical approach to migrate from NeDB to MongoDB, by exporting the entire content of the existing NeDB into JSON file, setup the new MongoDB and import that JSON file to create the schemas in MongoDB. </p>
|
||
<p>To export the database, stop the MeshCentral server and run the server again with <code>--dbexport</code> and a JSON file called <code>meshcentral.db.json</code> will be created in the <code>meshcentral-data</code> folder as shown below.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-37-31.jpg" /></p>
|
||
<p>Alternatively, user can also specify the full export path for the JSON file as shown below.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-37-40.jpg" /></p>
|
||
<h3 id="meshcentral-database-import">Database Import</h3>
|
||
<p>Importing the MeshCentral database is useful when transitioning between database softwares (NeDB to/from MongoDB) or when importing the database from MeshCentral1 via migration tool.</p>
|
||
<div class="admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>Importing a JSON file will overwrite the entire content of the database. A starting empty database is recommended.</p>
|
||
</div>
|
||
<p>When you are ready to import a JSON file into the database, run meshcentral with <code>--dbimport</code> as shown below. If path is not specified, the application will default to use <code>meshcentral.db.json</code> that is in <code>meshcentral-data</code> folder. </p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-38-45.jpg" /></p>
|
||
<p>Alternatively, user can specify the full path of the import JSON as shown below. </p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-39-03.jpg" /></p>
|
||
<h3 id="meshcentral-viewing-the-database">Viewing the Database</h3>
|
||
<p>For debugging purposes, Meshcentral allow users to have quick preview of certain frequently accessed data in the database with the following options:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th><strong><em>Option</em></strong></th>
|
||
<th><strong><em>Description</em></strong></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><strong><code>--showusers</code></strong></td>
|
||
<td>List of all users in the database.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong><code>--showmeshes</code></strong></td>
|
||
<td>List of all meshes in the database.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong><code>--shownodes</code></strong></td>
|
||
<td>List of all nodes in the database</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong><code>--showevents</code></strong></td>
|
||
<td>List all events in the database</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong><code>--showpower</code></strong></td>
|
||
<td>List all power events in the database.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong><code>--showall</code></strong></td>
|
||
<td>List all records in the database.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>For example, you can show the list of users with the <code>--showusers</code></p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-41-23.jpg" /></p>
|
||
<h3 id="meshcentral-mongodb-setup">MongoDB Setup</h3>
|
||
<p>MongoDB is useful when setting up MeshCentral for two or more peer servers given that all peer servers much have access to the same database. NeDB and MongoDB have similar access interfaces hence the DB migration from one to the other is straight forward. Installing MongoDB depends on its host OS so do check for available download options at mongodb.com.
|
||
In this guide, we will focus on the 64-bit windows with SSL support installer. </p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-41-58.jpg" /></p>
|
||
<p>After completing the installation step,</p>
|
||
<ol>
|
||
<li>Stop any instance of Meshcentral that is running locally or in any machine</li>
|
||
<li>Start a terminal or Windows Command prompt (CMD), </li>
|
||
<li>Create a folder “c:\data\db” </li>
|
||
<li>
|
||
<p>Go to the MongoDB bin folder and run <code>mongod --bind 127.0.0.1</code>. </p>
|
||
<p>This execute the database engine and store the database data in the default location “/data/db” path and bind a loopback on the local port “127.0.0.1”.</p>
|
||
<hr />
|
||
</li>
|
||
</ol>
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong> </p>
|
||
<p>We recommend the user to use a non-production server to experiment the setting options above.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-42-51.jpg" /></p>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>Upon successful execution, MongoDB will wait for connections on its default port 27017.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<ol>
|
||
<li>
|
||
<p>Now run MeshCentral with the command below, it will tell Meshcentral to connect to MongoDB and use “meshcentral” DB. MongoDB will create this DB if it does not exist.</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>meshcentral<span class="w"> </span>--mongodb<span class="w"> </span>mongodb://127.0.0.1:27017/meshcentral
|
||
</code></pre></div>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-46-26.jpg" /></p>
|
||
</li>
|
||
<li>
|
||
<p>Alternatively, to transition an existing meshcentral DB from NeDB and to MongoDB, just run commands below:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>meshcentral<span class="w"> </span>--dbexport
|
||
</code></pre></div>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>meshcentral<span class="w"> </span>--mongodb<span class="w"> </span>mongodb://127.0.0.1:27017/meshcentral<span class="w"> </span>--dbimport
|
||
</code></pre></div>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>meshcentral<span class="w"> </span>--mongodb<span class="w"> </span>mongodb://127.0.0.1:27017/meshcentral
|
||
</code></pre></div>
|
||
</li>
|
||
<li>
|
||
<p>We recommend the user to include MongoDB configuration into the server’s configuration “config.json” to avoid specifying the “--mongodb" each time MeshCentral is executed as shown below </p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"mongodb"</span><span class="p">:</span><span class="w"> </span><span class="s2">"mongodb://127.0.0.1:27017/meshcentral"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"mongodbcol"</span><span class="p">:</span><span class="w"> </span><span class="s2">"meshcentral"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
</li>
|
||
</ol>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>By default, MeshCentral will create a single collections called “meshcentral” in the specified database. If user want to specify a different collection name, use “--mongodbcol" or “mongodbcol” for settings like shown above.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<p>If you are using MongoDB with authentication, you can change the URL a little to add the username and password, for example:</p>
|
||
<div class="highlight"><pre><span></span><code>mongodb://username:password@127.0.0.1:27017/meshcentral
|
||
</code></pre></div>
|
||
<p>You can also provide extra connection parameters like this:</p>
|
||
<div class="highlight"><pre><span></span><code>mongodb://username:password@127.0.0.1:27017/meshcentral?authMechanism=MONGODB-CR&authSource=db
|
||
</code></pre></div>
|
||
<h2 id="meshcentral-running-state-less">🌀 Running State-less</h2>
|
||
<p>By default, MeshCentral will read its configuration information from the <code>meshcentral-data</code> folder. The most important file in that folder being the <code>config.json</code> file, but the folder also contains certificates, branding images, terms of service and more.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-49-37.jpg" /></p>
|
||
<p>After the configuration is read, MeshCentral will connect to its database and continue to start the server. For most user’s this is a perfectly acceptable way to setup the server. However, in some cases, it’s advantageous to setup the server “state-less”. That is, there is no local configuration files at all and everything is in the database. Two examples of this would be when running MeshCentral is a Docker container where we don’t want the container to have any state or for compliance with security specifications where the database is “encrypted at rest”. In this cases, we will load the configuration files into the database and MeshCentral will only be told how to connect to the database.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-49-53.jpg" /></p>
|
||
<p>When loading configuration information into the database, MeshCentral requires that a configuration file password be used to encrypt the configuration files in the database. This provides an additional layer of security on top of any authentication and security already provided by the database, if such security has been setup.</p>
|
||
<p>To make this happen, we will be using the following command line options from MeshCentral:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th><strong><em>Command</em></strong></th>
|
||
<th><strong><em>Description</em></strong></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><strong><code>--configkey (key)</code></strong></td>
|
||
<td>Specifies the encryption password that will be used to read or write the configuration files to the database.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong><code>--dblistconfigfiles</code></strong></td>
|
||
<td>List the names and size of all configuration files in the database.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong><code>--dbshowconfigfile (filename)</code></strong></td>
|
||
<td>Show the content of a specified filename from the database. --configkey is required.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong><code>--dbdeleteconfigfiles</code></strong></td>
|
||
<td>Delete all configuration files from the database.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong><code>--dbpushconfigfiles '*' or (folder path)</code></strong></td>
|
||
<td>Push a set of configuration files into the database, removing any existing files in the process. When * is specified, the “meshcentral-data” folder up pushed into the database. --configkey is required.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong><code>--dbpullconfigfiles (folder path)</code></strong></td>
|
||
<td>Get all of the configuration files from the database and place them in the specified folder. Files in the target folder may be overwritten. --configkey is required.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong><code>--loadconfigfromdb (key)</code></strong></td>
|
||
<td>Runs MeshCentral server using the configuration files found in the database. The configkey may be specified with this command or --configkey can be used.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Once we have MeshCentral running as expected using the <code>meshcentral-data</code> folder, we can simply push that configuration into the database and run using the database alone like this:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>./node_modules/meshcentral<span class="w"> </span>--dbpushconfigfiles<span class="w"> </span><span class="s1">'*'</span><span class="w"> </span>--configkey<span class="w"> </span>mypassword
|
||
</code></pre></div>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>./node_modules/meshcentral<span class="w"> </span>--loadconfigfromdb<span class="w"> </span>mypassword<span class="w"> </span>--mongodb<span class="w"> </span><span class="s2">"mongodb://127.0.0.1:27017/meshcentral"</span>
|
||
</code></pre></div>
|
||
<p>This first line will load many of the “meshcentral-data” files into the database. At this point, we can back up the <code>meshcentral-data</code> folder and remove it. Then run the second line to start the server. Here we use MongoDB, but if one uses NeDB, the <code>meshcentral.db</code> file in the “meshcentral-data” folder will still be needed.</p>
|
||
<p>Note that MeshCentral does not currently support placing a Let’s Encrypt certificate in the database. Generally, one would use a reverse proxy with Let’s Encrypt support and TLS offload in the reverse proxy and then run MeshCentral in state-less mode in a Docket container.</p>
|
||
<h2 id="meshcentral-commandline-options">⌨️ Commandline Options</h2>
|
||
<p>In general, doing <code>--option value</code> is the same as adding <code>"option": value</code> in the settings section of the config.json.</p>
|
||
<p>Here are the most common options found by running <code>meshcentral --help</code></p>
|
||
<div class="highlight"><pre><span></span><code>Run as a background service
|
||
--install/uninstall Install MeshCentral as a background service.
|
||
--start/stop/restart Control MeshCentral background service.
|
||
|
||
Run standalone, console application
|
||
--user [username] Always login as [username] if account exists.
|
||
--port [number] Web server port number.
|
||
--redirport [number] Creates an additional HTTP server to redirect users to the HTTPS server.
|
||
--exactports Server must run with correct ports or exit.
|
||
--noagentupdate Server will not update mesh agent native binaries.
|
||
--nedbtodb Transfer all NeDB records into current database.
|
||
--listuserids Show a list of a user identifiers in the database.
|
||
--cert [name], (country), (org) Create a web server certificate with [name] server name.
|
||
country and organization can optionally be set.
|
||
|
||
Server recovery commands, use only when MeshCentral is offline.
|
||
--createaccount [userid] Create a new user account.
|
||
--resetaccount [userid] Unlock an account, disable 2FA and set a new account password.
|
||
--adminaccount [userid] Promote account to site administrator.
|
||
</code></pre></div>
|
||
<h2 id="meshcentral-tls-offloading">🔒 TLS Offloading</h2>
|
||
<p>A good way for MeshCentral to handle a high traffic is to setup a TLS offload device at front of the server that takes care of doing all the TLS negotiation and encryption so that the server could offload this. There are many vendors who offer TLS or SSL offload as a software module (Nginx<em> or Apache</em>) so please contact your network administrator for the best solution that suits your setup. </p>
|
||
<p>As shown in the picture below, TLS traffic will come from the Internet and security will be handled by a device ahead of the server and MeshCentral only has to deal with TCP connections.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-53-04.jpg" /></p>
|
||
<p>To make this work, it is important the server is setup with <code>--tlsoffload</code>. This indicates the server that TLS is already being taken care of and MeshCentral does not have to deal with it. MeshCentral will continue to listen to port 80, 443 and 4433. </p>
|
||
<p>However, incoming port 443 (main web port) and 4433 (Intel® AMT MPS port) will not have TLS but MeshCentral will still put many HTTPS flags in its responses on port 443. By default, if a user accesses http://127.0.0.1:443 without TLS offloader setting, the browser is expected to display warnings. To make this work, TLS offloader device’s ports and functions should be configured correctly like below </p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th><strong><em>Port</em></strong></th>
|
||
<th><strong><em>Function Description</em></strong></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><strong>80</strong></td>
|
||
<td>Directly forwards port 80 to MeshCentral port 80</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>443</strong></td>
|
||
<td>Handle TLS using a web certificate and forward to MeshCentral port 443</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>4433</strong></td>
|
||
<td>Handle TLS using MPS certificate and forward to MeshCentral port 4433</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>If possible, port 443 should be configured with a legitimate trusted certificate and the public part of the certificate named as <code>webserver-cert-public.crt</code> must be placed inside of <code>meshcentral-data</code> folder of the server. When the server is executed in tlsoffload mode, only the public part of the web certificate is used by the server.</p>
|
||
<p>For Intel® AMT MPS port 4433, the certificate files “mpsserver-cert-public.crt” and “mpsserver-cert-public.key” must be copied from the “meshcentral-data” folder and loaded into the TLS offload module.</p>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>Please consult the TLS offloader user manual from the respective vendor to configure TLS offloading feature correctly.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<h2 id="meshcentral-lets-encrypt-support">📜 Let’s Encrypt support</h2>
|
||
<p>MeshCentral makes use of HTTPS to authenticate and encrypt management traffic over the network. By default, a self-signed certificate is used for the MeshCentral HTTPS server. That certificate is not trusted by browsers and so, you get a warning message when visiting the web site. You can solve this but obtaining a free trusted certificate from <a href="https://letsencrypt.org/">Let's Encrypt</a>. There are some limitations and so, it’s best to get familiar with this service before starting. You will also need a valid domain name that you own and that points to your MeshCentral server.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-55-26.jpg" /></p>
|
||
<p>Before moving forward with this section, make sure your MeshCentral server is working correctly, has a domain name pointing to it and that the HTTP redirection server on port 80 is enabled and working. MeshCentral’s HTTP port 80 server will be used in the process to prove to Let’s Encrypt that we have control over the domain. At any point, you may try to use <a href="https://letsdebug.net/">letsdebug.net</a> to see if your domain is setup correctly and/or debug any issues. When ready, add the “letsencrypt” section to the config.json file like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"RedirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">80</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"letsencrypt"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"email"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myemail@myserver.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"names"</span><span class="p">:</span><span class="w"> </span><span class="s2">"domain1.com,domain2.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"rsaKeySize"</span><span class="p">:</span><span class="w"> </span><span class="mi">3072</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"production"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>The only mandatory field is the email address, please enter a valid one.</p>
|
||
<p>The names section is a list of domain names the requested certificate will be valid for. This must be a list of DNS names that are already pointing to your server. It’s important to understand you are not requesting these DNS names, rather, Let’s Encrypt will makes requests to prove control over all of these domain name before issuing the certificate. All the domain names you enter must point to the server and HTTP port 80 must be reachable over the internet. If you don’t specify names, the default MeshCentral certificate name is used, that is the configured <code>--cert [name]</code>.</p>
|
||
<p>The RSA key size can only be 2048 or 3072, with the default being 3072. This is the number of bit used for the RSA key in the certificate. Bigger is more secure, but takes more time to compute.</p>
|
||
<p>Lastly the production key, by default this is false. When set to false, MeshCentral will query the Let’s Encrypt staging server for a certificate. It’s highly recommended to try this first and make sure everything works before getting a real certificate. Keep production to false, run thru the process at least once and make sure everything works. You will get a new certificate installed on the HTTPS server signed by a staging Let’s Encrypt certificate authority.</p>
|
||
<p>The Let’s Encrypt certificates and files will be created in the “meshcentral-data” folder. Make sure to keep regular backups of the “meshcentral-data” folder and all sub-folders.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-56-29.jpg" /></p>
|
||
<p>Once you placed the “letsencrypt” section in config.json, restart the server. The request to the Let’s Encrypt server may take a few minutes to a few hours. It’s best to have your DNS server name pointing to your server for over a day before doing this. Once the new certificate is received, the server will automatically restart and browsing to HTTPS on your server will show the new certificate. Here is what it looks like on FireFox:</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-56-59.jpg" /></p>
|
||
<p>If you successfully setup a Let’s Encrypt certificate using the Let’s Encrypt staging server (“production”: false) and everything looks good, stop the server, remove the “letsencrypt” folder in “meshcentral-data”, change production to “true” and start the server again. You should get a real certificate in a few minutes to a few hours. MeshCentral will automatically renew the certificate a few days before it expires. The MeshCentral self-signed certificate will still be present in the “meshcentral-data” folder, this is normal and there is no need to manually copy the Let’s Encrypt certificate to the “meshcentral-data” folder. If something goes wrong with the Let’s Encrypt certificate, the server will fall back to using the self-signed one.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Please be patient with Let’s Encrypt certificate requests and make sure you correctly get a staging certificate before setting production to true.</p>
|
||
</div>
|
||
<p>If Let’s Encrypt works for you, please consider donating to them as they provide a critical service to the Internet community.</p>
|
||
<h2 id="meshcentral-server-ip-filtering">🛡️ Server IP filtering</h2>
|
||
<p>For improved security, it’s good to limit access to MeshCentral with IP address. For example, we want to allow mesh agents and Intel AMT computers to connect from anywhere, but whitelist IP address for users that we allow to access MeshCentral. </p>
|
||
<p>MeshCentral provides IP filtering option in the <code>config.json</code> file for each domain. For an example, we can set IP address whitelist for the default domain like as shown below.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"userallowedip"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"1.2.3.4,1.2.3.5"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>IP addresses are separated by a comma. As a result, only users coming these IP addresses will be able to see the server’s login page as illustrated below. Other IP addresses will be blocked effectively.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-18-23-59-28.jpg" /></p>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>When IP address whitelist is effective, Mesh Agent connection from any IP address will be not affected. </p>
|
||
</blockquote>
|
||
<hr />
|
||
<p>You can also use files for IP lists</p>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"userAllowedIp"</span><span class="p">:</span><span class="w"> </span><span class="s2">"file:userallowedips.txt"</span><span class="p">,</span>
|
||
<span class="nt">"userBlockedIp"</span><span class="p">:</span><span class="w"> </span><span class="s2">"file:userblockedips.txt"</span><span class="p">,</span>
|
||
<span class="nt">"agentAllowedIp"</span><span class="p">:</span><span class="w"> </span><span class="s2">"file:agentallowedips.txt"</span>
|
||
</code></pre></div>
|
||
<p>Place the file in the <code>meshcentral-data</code> folder.</p>
|
||
<p>All the lines that start with a number or <code>:</code> will be used, everything else is ignored. So, you can put comments anyway you like, but probably best to start then with a <code>#</code> or something to make it clear.</p>
|
||
<div class="highlight"><pre><span></span><code># My list of blocked IP's
|
||
185.101.70.0/24
|
||
185.46.85.0/24
|
||
37.9.44.0/24
|
||
37.9.45.0/24
|
||
5.189.205.0/24
|
||
5.189.206.0/24
|
||
5.189.207.0/24
|
||
5.62.153.0/24
|
||
5.62.156.0/24
|
||
5.62.158.0/24
|
||
|
||
# One more list
|
||
5.8.44.0/24
|
||
5.8.45.0/24
|
||
5.8.46.0/24
|
||
79.110.28.0/24
|
||
79.110.31.0/24
|
||
91.204.14.0/24
|
||
95.181.218.0/24
|
||
95.85.81.0/24
|
||
</code></pre></div>
|
||
<h2 id="meshcentral-embedding-meshcentral">🧩 Embedding MeshCentral</h2>
|
||
<p>One interesting way to use MeshCentral is to embed its features into another web site. In other words, certain feature of MeshCentral can be selectively embedded into another website such as Remote Desktop or File Transfer. </p>
|
||
<p>This allows another site to take care of the user accounts and business processes while MeshCentral takes care of remote management. In the example below, a user logs into an existing web site and received a page with MeshCentral remote desktop embedded into it.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-02-03.jpg" /></p>
|
||
<p>To make this work, a following key alignment is required :</p>
|
||
<ol>
|
||
<li>
|
||
<p>When a user requests the business website, the business web server must return the user a web page containing an iframe with a URL that points to the MeshCentral server.</p>
|
||
</li>
|
||
<li>
|
||
<p>The URL must contain both a login token and embedding options. The login token tells MeshCentral under what MeshCentral account this request should be made.</p>
|
||
</li>
|
||
<li>
|
||
<p>The login token replaces the login screen of MeshCentral. Then, the embedding options can be used to specify no page title, header and footer to be displayed. This way, the page given by MeshCentral will fit nicely into the iframe. </p>
|
||
</li>
|
||
</ol>
|
||
<p>In this section we will review both the login token and embedding options mentioned above. </p>
|
||
<h3 id="meshcentral-login-token">Login Token</h3>
|
||
<p>With MeshCentral, it’s possible to login to the main web page without even seeing the login screen. Of course, you can do this by specifying <code>--nousers</code> or <code>--user admin</code> when you run the server, but these approach are not secure as it removes user authentication for those accessing the server.</p>
|
||
<p>With login tokens feature, a token can be generated to be used for a short time to login and skip the login page. This is perfect for embedding MeshCentral usages into other web site and probably for other applications. </p>
|
||
<p>To enable this feature, configure <code>config.json</code> file to allow login tokens. </p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"allowLoginToken"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"allowFraming"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Set both allowLoginToken and allowFraming to <code>true</code> to use login tokens along with framing MeshCentral within another web page. </p>
|
||
<p>Next, create a token. Execute MeshCentral with the <code>--logintoken [userid]</code> switch and userid value with the example below:</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-03-32.jpg" /></p>
|
||
<p>The <code>userid</code> is actually a combination of three values - user, domain, and username in a single string <code>user/domain/username</code>. The example above is using a default domain which is empty hence, the userid will be just `user//admin” to request for login token. Domains are only used if the server in multi-tenancy mode as discussed in previous chapters.</p>
|
||
<p>The resulting hashed base64 encoded blob can be used as a login token for 1 hour. Simply add the “?login=” followed by the token value generated to the URL of the webserver. For an e.g. https://localhost/?login=23tY7@wNbPoPLDeXVMRmTKKrqVEJ3OkJ. The login page is expected to be skipped and automatically login the user admin. This is just a manual attempt to token based login. </p>
|
||
<p>Now, to have this work seamlessly with a different website, we should generate a login token key. A token key can be used to generate login tokens whenever needed for MeshCentral. Generate this key with <code>--loginTokenKey</code> switch as shown below</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-03-46.jpg" /></p>
|
||
<p>The generated masker key must be placed in a secure location within the business website. </p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-03-58.jpg" /></p>
|
||
<p>As illustrated above, we see the business site using the token key to generate a login token and embed it into the response web page. The user’s browser then loads the iframe that includes both the URL with the login token for MeshCentral. MeshCentral can then verify the token and allow the web page to load as expected. </p>
|
||
<h3 id="meshcentral-embedding-options">Embedding Options</h3>
|
||
<p>There are multiple options available for user to explicitly choose the features that will be loaded from MeshCentral to the business website. The argument in the in the URL can dictate which web page should display and how. The three embedding URL arguments are Viewmode, Hide and Node. </p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Embedding Options / URL Argument</th>
|
||
<th>Description</th>
|
||
<th>Values</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><strong>viewmode</strong></td>
|
||
<td>Indicates the information to show. This is an integer value, possible values are:</td>
|
||
<td>1 = Devices tab<br>2 = Account tab<br>3 = Events Live<br>4 = Users General<br>5 = Server files tab<br>6 = Server General<br>10 = Device general information<br>11 = Device remote desktop<br>12 = Device terminal<br>13 = Device files<br>14 = Device Intel AMT console<br>15 = Device Mesh Agent console<br>16 = Device events<br>17 = Device info<br>19 = Device plugins<br>20 = Mesh General<br>21 = Mesh Summary<br>30 = User General<br>31 = User Events<br>40 = Server Stats<br>41 = Server Trace<br>42 = Server Plugins<br>50 = Users Groups<br>52 = Users Recordings<br>60 = Events Report<br>115 = Server Console<br><br><strong>Note</strong>: For values 10-19, a node identifier must be specified. For values 20-29, a mesh identifier must be specified. For values 30-39, a user identifier must be specified. For values 50-59, a user group identifier may be required.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>hide</strong></td>
|
||
<td>Indicates which portion of the web page to hide. This is a bitmask integer hence it will need the sum of values. For example: To hide all of the values, add 1+2+4+8 and use 15 as the value.</td>
|
||
<td>1 = Hide the page header<br>2 = Hide the page tab<br>4 = Hide the page footer<br>8 = Hide the page title<br>16 = Hide the left tool bar<br>32 = Hide back buttons</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>node</strong></td>
|
||
<td>Optional unless Viewmode is set to value of 10-19. Indicates which node to show on the screen. For example, if we want to embed the remote desktop page for a given node and hide the header, tabs, footer and page title, we could have this URL: <code>https://localhost/?node=UkSNlz7t...2Sve6Srl6FltDd&viewmode=11&hide=15</code></td>
|
||
<td>Node or NodeID is a long base64 encoded SHA384 value</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>Typically, the URL for the website is followed by “?” then a set of name=value pairs separated by <code>&</code>. </p>
|
||
</blockquote>
|
||
<hr />
|
||
<p>Based on the URL https://localhost/?node=UkSNlz7t...2Sve6Srl6FltDd&viewmode=11&hide=15 , the nodeID starts with “UkSNlz7t”. We shortened the value in this example, but it’s normally a long base64 encoded SHA384 value. The Viewmode set to 11 which is the remote desktop page and Hide set to 15 to hide everything. Hence the user may see as illustrated below. </p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-19-29.jpg" /></p>
|
||
<p>Only the remote desktop viewer will be displayed embedded within an iframe.</p>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>User must set “allowFraming” to true in the config.json of the server. This is in addition to the Node, Viewmode and Hide arguments, the login token must be specified to add complex features into another website.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<h2 id="meshcentral-server-port-aliasing">🔀 Server port aliasing</h2>
|
||
<p>In some cases, you may be setting up a server on a private network that uses non-standard ports, but use a router or firewall in front to perform port mapping. So, even if the server privately uses non-standard ports, the public ports are the standard ports 80 and 443. You have to tell MeshCentral to bind to private ports but pretend it’s using the other standard ports when communicating publicly. To make this work, MeshCentral supports port aliasing.</p>
|
||
<p>For example you can run :</p>
|
||
<div class="highlight"><pre><span></span><code><span class="w"> </span>node<span class="w"> </span>meshcentral<span class="w"> </span>--redirport<span class="w"> </span><span class="m">2001</span><span class="w"> </span>--port<span class="w"> </span><span class="m">2002</span><span class="w"> </span>--aliasport<span class="w"> </span><span class="m">443</span>
|
||
</code></pre></div>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-19-46.jpg" /></p>
|
||
<p>Here, the server binds the HTTP and HTTPS ports to 2001 and 2002, but the server will externally indicate to MeshAgents and browsers that they must connect to port 443.</p>
|
||
<p>In a different situation, you may want to setup a server so that both Mesh Agents and Intel AMT connect back to the server on port 443. This is useful because some corporation have firewalls that restrict outgoing connections to only port 80 and 443. By default, MeshCentral will be setup to have MeshAgents connection on port 443 and Intel AMT on port 4433.</p>
|
||
<p>In the following picture we have a usual server running with :</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>meshcentral<span class="w"> </span>--cert<span class="w"> </span>Server1<span class="w"> </span>--port<span class="w"> </span><span class="m">443</span><span class="w"> </span>--mpsport<span class="w"> </span><span class="m">4433</span>
|
||
</code></pre></div>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-21-19.jpg" /></p>
|
||
<p>We can setup the server so that MeshAgent and Intel AMT will connect on port 443 of two different IP address or names like this:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>meshcentral<span class="w"> </span>--cert<span class="w"> </span>Server1<span class="w"> </span>--mpscert<span class="w"> </span>Server2<span class="w"> </span>--port<span class="w"> </span><span class="m">443</span><span class="w"> </span>--mpsport<span class="w"> </span><span class="m">4433</span><span class="w"> </span>--mpsaliasport<span class="w"> </span><span class="m">443</span>
|
||
</code></pre></div>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-21-54.jpg" /></p>
|
||
<p>In the second example, the server on the right is running HTTPS on port 443 and MPS on port 4433 as usual, but the MPS is now presenting a certificate that has the name <code>Server2</code> on it. The server will also configure Intel AMT CIRA to connect to <code>Server2:443</code>.</p>
|
||
<p>A router or firewall that is located in front of the MeshCentral server needs to be configured correctly to forwarding :</p>
|
||
<p><div class="highlight"><pre><span></span><code>Server1:443<span class="w"> </span>-><span class="w"> </span><span class="m">443</span><span class="w"> </span>on<span class="w"> </span>MeshCentral
|
||
</code></pre></div>
|
||
<div class="highlight"><pre><span></span><code>Server2:443<span class="w"> </span>-><span class="w"> </span><span class="m">4433</span><span class="w"> </span>on<span class="w"> </span>MeshCentral
|
||
</code></pre></div></p>
|
||
<p>The routing of IP and ports by the firewall shown on the picture must be configured separately from MeshCentral using separate software. Typically, routers or firewalls have the proper controls to configure this type of traffic routes.</p>
|
||
<h2 id="meshcentral-web-relay-using-dns-names-and-multiple-web-relays">📡 Web relay using DNS names and multiple web relays</h2>
|
||
<p>MeshCentral has a web relay feature that allows a user to access remote web sites thru the MeshCentral server without having to install MeshCentral Router. Web relay also allow you to use an alternate DNS name instead of a different web relay port which has a few advantages. You can also use multiple alternate DNS names which can be used at the same time to provide users with many HTTP/HTTPS relays.</p>
|
||
<h2 id="meshcentral-video-walkthrus">🎬 Video Walkthrus</h2>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/GU7MQjkPSd8" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/INOvsHXNOKY" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<h2 id="meshcentral-device-groups-with-relay-agent">🖧 Device Groups with Relay Agent</h2>
|
||
<p>MeshCentral supports the local device group allowing devices that do not have an agent to be managed thru MeshCentral with regular SSH, SFTP, RDP, VNC protocols. Until now, the MeshCentral server had to be in LAN or Hybrid modes to support his device group and the managed devices had to be on the same network as the MeshCentral server. Starting with v1.0.11, users can create a local device group specifying a MeshAgent as a relay. This makes it possible to manage agent-less devices from anywhere on the Internet even if the server is in WAN mode. Simply install a single device with a MeshAgent on a network and create a local device group with that device as the relay.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-31-10-30-07.jpg" /></p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-31-10-30-42.jpg" /></p>
|
||
<p>To enable SSH support, add this line to the domain section of your <code>config.json</code>:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"ssh"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-video-walkthru_1">Video Walkthru</h3>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/TtW5-g6SeZQ" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<h3 id="meshcentral-raritan-and-webpowerswitch-with-relay">Raritan and WebPowerSwitch with Relay</h3>
|
||
<p>In addition to local device groups, the IP-KVM/Power switch device group was also improved to support a MeshAgent as a relay. This is big news for Raritan IP-KVM switch owners as you can now monitor your IP-KVM ports and access them remotely from the Internet. The same can be done with WebPowerSwitch allowing full out-of-band remote access to devices from anywhere in the world.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-31-10-30-50.jpg" /></p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-31-10-31-00.jpg" /></p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-31-10-32-46.jpg" /></p>
|
||
<h2 id="meshcentral-nginx-reverse-proxy-setup">🧭 NGINX Reverse-Proxy Setup</h2>
|
||
<h3 id="meshcentral-video-walkthru_2">Video Walkthru</h3>
|
||
<div class="video-wrapper">
|
||
<iframe src="https://www.youtube.com/embed/YSmiLyKSX2I" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<p>Sometimes it’s useful to setup MeshCentral with a reverse-proxy in front of it. This is useful if you need to host many services on a single public IP address, if you want to offload TLS and perform extra web caching. In this section we will setup NGINX, a popular reverse-proxy, in front of MeshCentral. NGNIX is available at: <a href="https://www.nginx.com/">Nginx</a></p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-23-11.jpg" /></p>
|
||
<p>In this example, we will :</p>
|
||
<ul>
|
||
<li>Run MeshCentral on non-standard ports, but alias HTTPS to port 443.</li>
|
||
<li>NGINX will be using standard ports 80 and 443.</li>
|
||
<li>We will have NGINX perform all TLS authentication & encryption.</li>
|
||
<li>MeshCentral will read the NGINX web certificate so agents will perform correct server authentication.</li>
|
||
<li>NGINX will be setup with long timeouts, because agents have long standard web socket connections.</li>
|
||
</ul>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>With SELinux, NGINX reverse proxy requires 'setsebool -P httpd_can_network_relay 1'
|
||
Caution: httpd_can_network_relay only allows certain ports
|
||
Confirm you are using ports from this subset in MeshCentral
|
||
If you want to use a different port then you will need to add it to http_port_t</p>
|
||
</div>
|
||
<p>Let’s get started by configuring MeshCentral with the following values in <code>config.json</code>:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myservername.domain.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">4430</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"AliasPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"RedirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">800</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"AgentPong"</span><span class="p">:</span><span class="w"> </span><span class="mi">300</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"TlsOffload"</span><span class="p">:</span><span class="w"> </span><span class="s2">"127.0.0.1"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"certUrl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://127.0.0.1:443/"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>With this configuration, MeshCentral will be using port 4430 instead of port 443, but because “TlsOffload” is set, TLS will not be performed on port 4430. The server name is set to <code>myservername.domain.com</code>, so that is the name that MeshCentral will give to agents to connect to. Also, the alias port is set to 443. So agents will be told to connect to “myservername.domain.com:443”.</p>
|
||
<p>The “AgentPong” line instructs the server to send data to the agent each 300 seconds and the agent by default will send data to the server every 120 seconds. As long as NGINX timeouts are longer than this, connections should remain open.</p>
|
||
<p>When agents connect, they will see the NGINX TLS certificate on port 443. MeshCentral needs to know about the NGINX certificate so that it can tell the agents this is the correct certificate they should expect to see. So, “certUrl” is used to tell MeshCentral where to get the certificates that agents will see when connecting.</p>
|
||
<p>When NGINX forwards connections to MeshCentral, extra X-Forwarded headers will be added to each request. MeshCentral needs to know if these headers can be trusted or not. By setting “TlsOffload” to “127.0.0.1”, MeshCentral is told to trust these headers when requests come from “127.0.0.1”.</p>
|
||
<p>In this example, make sure to change “127.0.0.1” to the IP address of NGINX and “Cert” to the external DNS name of the NGINX server.</p>
|
||
<p>Next, we need to configure and launch NGINX. Here is an ngnix.conf to get started:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="err">worker_processes</span><span class="w"> </span><span class="mi">1</span><span class="err">;</span>
|
||
|
||
<span class="err">eve</span><span class="kc">nts</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">worker_co</span><span class="kc">nne</span><span class="err">c</span><span class="kc">t</span><span class="err">io</span><span class="kc">ns</span><span class="w"> </span><span class="mi">1024</span><span class="err">;</span>
|
||
<span class="p">}</span>
|
||
|
||
<span class="err">h</span><span class="kc">tt</span><span class="err">p</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">#</span><span class="w"> </span><span class="err">HTTP</span><span class="w"> </span><span class="err">server.</span><span class="w"> </span><span class="err">I</span><span class="kc">n</span><span class="w"> </span><span class="kc">t</span><span class="err">his</span><span class="w"> </span><span class="err">example</span><span class="p">,</span><span class="w"> </span><span class="err">we</span><span class="w"> </span><span class="err">use</span><span class="w"> </span><span class="err">a</span><span class="w"> </span><span class="err">wildcard</span><span class="w"> </span><span class="err">as</span><span class="w"> </span><span class="err">server</span><span class="w"> </span><span class="kc">na</span><span class="err">me.</span>
|
||
<span class="w"> </span><span class="err">server</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">lis</span><span class="kc">ten</span><span class="w"> </span><span class="mi">80</span><span class="err">;</span>
|
||
<span class="w"> </span><span class="err">server_</span><span class="kc">na</span><span class="err">me</span><span class="w"> </span><span class="err">_;</span>
|
||
|
||
<span class="w"> </span><span class="err">loca</span><span class="kc">t</span><span class="err">io</span><span class="kc">n</span><span class="w"> </span><span class="err">/</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">proxy_pass</span><span class="w"> </span><span class="err">h</span><span class="kc">tt</span><span class="err">p</span><span class="p">:</span><span class="c1">//127.0.0.1:800/;</span>
|
||
<span class="w"> </span><span class="err">proxy_h</span><span class="kc">tt</span><span class="err">p_versio</span><span class="kc">n</span><span class="w"> </span><span class="mf">1.1</span><span class="err">;</span>
|
||
|
||
<span class="w"> </span><span class="err">#</span><span class="w"> </span><span class="err">I</span><span class="kc">nf</span><span class="err">orm</span><span class="w"> </span><span class="err">MeshCe</span><span class="kc">ntral</span><span class="w"> </span><span class="err">abou</span><span class="kc">t</span><span class="w"> </span><span class="kc">t</span><span class="err">he</span><span class="w"> </span><span class="err">real</span><span class="w"> </span><span class="err">hos</span><span class="kc">t</span><span class="p">,</span><span class="w"> </span><span class="err">por</span><span class="kc">t</span><span class="w"> </span><span class="err">a</span><span class="kc">n</span><span class="err">d</span><span class="w"> </span><span class="err">pro</span><span class="kc">t</span><span class="err">ocol</span>
|
||
<span class="w"> </span><span class="err">proxy_se</span><span class="kc">t</span><span class="err">_header</span><span class="w"> </span><span class="err">X</span><span class="mi">-</span><span class="err">Forwarded</span><span class="mi">-</span><span class="err">Hos</span><span class="kc">t</span><span class="w"> </span><span class="err">$hos</span><span class="kc">t</span><span class="p">:</span><span class="err">$server_por</span><span class="kc">t</span><span class="err">;</span>
|
||
<span class="w"> </span><span class="err">proxy_se</span><span class="kc">t</span><span class="err">_header</span><span class="w"> </span><span class="err">X</span><span class="mi">-</span><span class="err">Forwarded</span><span class="mi">-</span><span class="err">For</span><span class="w"> </span><span class="err">$proxy_add_x_</span><span class="kc">f</span><span class="err">orwarded_</span><span class="kc">f</span><span class="err">or;</span>
|
||
<span class="w"> </span><span class="err">proxy_se</span><span class="kc">t</span><span class="err">_header</span><span class="w"> </span><span class="err">X</span><span class="mi">-</span><span class="err">Forwarded</span><span class="mi">-</span><span class="err">Pro</span><span class="kc">t</span><span class="err">o</span><span class="w"> </span><span class="err">$scheme;</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
|
||
<span class="w"> </span><span class="err">#</span><span class="w"> </span><span class="err">HTTPS</span><span class="w"> </span><span class="err">server.</span><span class="w"> </span><span class="err">I</span><span class="kc">n</span><span class="w"> </span><span class="kc">t</span><span class="err">his</span><span class="w"> </span><span class="err">example</span><span class="p">,</span><span class="w"> </span><span class="err">we</span><span class="w"> </span><span class="err">use</span><span class="w"> </span><span class="err">a</span><span class="w"> </span><span class="err">wildcard</span><span class="w"> </span><span class="err">as</span><span class="w"> </span><span class="err">server</span><span class="w"> </span><span class="kc">na</span><span class="err">me.</span>
|
||
<span class="w"> </span><span class="err">server</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">lis</span><span class="kc">ten</span><span class="w"> </span><span class="mi">443</span><span class="w"> </span><span class="err">ssl;</span>
|
||
<span class="w"> </span><span class="err">server_</span><span class="kc">na</span><span class="err">me</span><span class="w"> </span><span class="err">_;</span>
|
||
|
||
<span class="w"> </span><span class="err">#</span><span class="w"> </span><span class="err">MeshCe</span><span class="kc">ntral</span><span class="w"> </span><span class="err">uses</span><span class="w"> </span><span class="err">lo</span><span class="kc">n</span><span class="err">g</span><span class="w"> </span><span class="err">s</span><span class="kc">tan</span><span class="err">di</span><span class="kc">n</span><span class="err">g</span><span class="w"> </span><span class="err">web</span><span class="w"> </span><span class="err">socke</span><span class="kc">t</span><span class="w"> </span><span class="err">co</span><span class="kc">nne</span><span class="err">c</span><span class="kc">t</span><span class="err">io</span><span class="kc">ns</span><span class="p">,</span><span class="w"> </span><span class="err">se</span><span class="kc">t</span><span class="w"> </span><span class="err">lo</span><span class="kc">n</span><span class="err">ger</span><span class="w"> </span><span class="kc">t</span><span class="err">imeou</span><span class="kc">ts</span><span class="err">.</span>
|
||
<span class="w"> </span><span class="err">proxy_se</span><span class="kc">n</span><span class="err">d_</span><span class="kc">t</span><span class="err">imeou</span><span class="kc">t</span><span class="w"> </span><span class="mi">330</span><span class="err">s;</span>
|
||
<span class="w"> </span><span class="err">proxy_read_</span><span class="kc">t</span><span class="err">imeou</span><span class="kc">t</span><span class="w"> </span><span class="mi">330</span><span class="err">s;</span>
|
||
|
||
<span class="w"> </span><span class="err">#</span><span class="w"> </span><span class="err">We</span><span class="w"> </span><span class="err">ca</span><span class="kc">n</span><span class="w"> </span><span class="err">use</span><span class="w"> </span><span class="kc">t</span><span class="err">he</span><span class="w"> </span><span class="err">MeshCe</span><span class="kc">ntral</span><span class="w"> </span><span class="err">ge</span><span class="kc">nerate</span><span class="err">d</span><span class="w"> </span><span class="err">cer</span><span class="kc">t</span><span class="err">i</span><span class="kc">f</span><span class="err">ica</span><span class="kc">te</span><span class="w"> </span><span class="err">&</span><span class="w"> </span><span class="err">key</span>
|
||
<span class="w"> </span><span class="err">ssl_cer</span><span class="kc">t</span><span class="err">i</span><span class="kc">f</span><span class="err">ica</span><span class="kc">te</span><span class="w"> </span><span class="err">webserver</span><span class="mi">-</span><span class="err">cer</span><span class="kc">t</span><span class="mi">-</span><span class="err">public.cr</span><span class="kc">t</span><span class="err">;</span>
|
||
<span class="w"> </span><span class="err">ssl_cer</span><span class="kc">t</span><span class="err">i</span><span class="kc">f</span><span class="err">ica</span><span class="kc">te</span><span class="err">_key</span><span class="w"> </span><span class="err">webserver</span><span class="mi">-</span><span class="err">cer</span><span class="kc">t</span><span class="mi">-</span><span class="err">priva</span><span class="kc">te</span><span class="err">.key;</span>
|
||
<span class="w"> </span><span class="err">ssl_sessio</span><span class="kc">n</span><span class="err">_cache</span><span class="w"> </span><span class="err">shared</span><span class="p">:</span><span class="err">WEBSSL</span><span class="p">:</span><span class="mi">10</span><span class="err">m;</span>
|
||
<span class="w"> </span><span class="err">ssl_ciphers</span><span class="w"> </span><span class="err">HIGH</span><span class="p">:</span><span class="err">!aNULL</span><span class="p">:</span><span class="err">!MD</span><span class="mi">5</span><span class="err">;</span>
|
||
<span class="w"> </span><span class="err">ssl_pre</span><span class="kc">fer</span><span class="err">_server_ciphers</span><span class="w"> </span><span class="err">o</span><span class="kc">n</span><span class="err">;</span>
|
||
|
||
<span class="w"> </span><span class="err">loca</span><span class="kc">t</span><span class="err">io</span><span class="kc">n</span><span class="w"> </span><span class="err">/</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">proxy_pass</span><span class="w"> </span><span class="err">h</span><span class="kc">tt</span><span class="err">p</span><span class="p">:</span><span class="c1">//127.0.0.1:4430/;</span>
|
||
<span class="w"> </span><span class="err">proxy_h</span><span class="kc">tt</span><span class="err">p_versio</span><span class="kc">n</span><span class="w"> </span><span class="mf">1.1</span><span class="err">;</span>
|
||
|
||
<span class="w"> </span><span class="err">#</span><span class="w"> </span><span class="err">Allows</span><span class="w"> </span><span class="err">websocke</span><span class="kc">ts</span><span class="w"> </span><span class="err">over</span><span class="w"> </span><span class="err">HTTPS.</span>
|
||
<span class="w"> </span><span class="err">proxy_se</span><span class="kc">t</span><span class="err">_header</span><span class="w"> </span><span class="err">Upgrade</span><span class="w"> </span><span class="err">$h</span><span class="kc">tt</span><span class="err">p_upgrade;</span>
|
||
<span class="w"> </span><span class="err">proxy_se</span><span class="kc">t</span><span class="err">_header</span><span class="w"> </span><span class="err">Co</span><span class="kc">nne</span><span class="err">c</span><span class="kc">t</span><span class="err">io</span><span class="kc">n</span><span class="w"> </span><span class="s2">"upgrade"</span><span class="err">;</span>
|
||
<span class="w"> </span><span class="err">proxy_se</span><span class="kc">t</span><span class="err">_header</span><span class="w"> </span><span class="err">Hos</span><span class="kc">t</span><span class="w"> </span><span class="err">$hos</span><span class="kc">t</span><span class="err">;</span>
|
||
|
||
<span class="w"> </span><span class="err">#</span><span class="w"> </span><span class="err">I</span><span class="kc">nf</span><span class="err">orm</span><span class="w"> </span><span class="err">MeshCe</span><span class="kc">ntral</span><span class="w"> </span><span class="err">abou</span><span class="kc">t</span><span class="w"> </span><span class="kc">t</span><span class="err">he</span><span class="w"> </span><span class="err">real</span><span class="w"> </span><span class="err">hos</span><span class="kc">t</span><span class="p">,</span><span class="w"> </span><span class="err">por</span><span class="kc">t</span><span class="w"> </span><span class="err">a</span><span class="kc">n</span><span class="err">d</span><span class="w"> </span><span class="err">pro</span><span class="kc">t</span><span class="err">ocol</span>
|
||
<span class="w"> </span><span class="err">proxy_se</span><span class="kc">t</span><span class="err">_header</span><span class="w"> </span><span class="err">X</span><span class="mi">-</span><span class="err">Forwarded</span><span class="mi">-</span><span class="err">Hos</span><span class="kc">t</span><span class="w"> </span><span class="err">$hos</span><span class="kc">t</span><span class="p">:</span><span class="err">$server_por</span><span class="kc">t</span><span class="err">;</span>
|
||
<span class="w"> </span><span class="err">proxy_se</span><span class="kc">t</span><span class="err">_header</span><span class="w"> </span><span class="err">X</span><span class="mi">-</span><span class="err">Forwarded</span><span class="mi">-</span><span class="err">For</span><span class="w"> </span><span class="err">$proxy_add_x_</span><span class="kc">f</span><span class="err">orwarded_</span><span class="kc">f</span><span class="err">or;</span>
|
||
<span class="w"> </span><span class="err">proxy_se</span><span class="kc">t</span><span class="err">_header</span><span class="w"> </span><span class="err">X</span><span class="mi">-</span><span class="err">Forwarded</span><span class="mi">-</span><span class="err">Pro</span><span class="kc">t</span><span class="err">o</span><span class="w"> </span><span class="err">$scheme;</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>As indicated in the comments of this NGINX configuration file, we set timeouts to be really long. We forward HTTP port 80 and HTTPS port 443 to the corresponding ports on MeshCentral. In this example, we happen to use the web certificates that where generated by MeshCentral, but any certificate is ok. We also add extra “X-Forward” headers, this tells MeshCentral information that would normally be hidden by NGINX, like the client’s IP address and more.</p>
|
||
<p>Now we are ready to start NGINX and MeshCentral. You should start NGINX first because MeshCentral will try to fetch the certificate from NGINX upon start. When starting MeshCentral, you should see something like this:</p>
|
||
<div class="highlight"><pre><span></span><code>MeshCentral<span class="w"> </span>HTTP<span class="w"> </span>redirection<span class="w"> </span>web<span class="w"> </span>server<span class="w"> </span>running<span class="w"> </span>on<span class="w"> </span>port<span class="w"> </span><span class="m">800</span>.
|
||
Loaded<span class="w"> </span>RSA<span class="w"> </span>web<span class="w"> </span>certificate<span class="w"> </span>at<span class="w"> </span>https://127.0.0.1:443/,<span class="w"> </span>SHA384:<span class="w"> </span>d9de9e27a229b5355708a3672fb23237cc994a680b3570d242a91e36b4ae5bc96539e59746e2b71eef3dbdabbf2ae138.
|
||
MeshCentral<span class="w"> </span>Intel<span class="o">(</span>R<span class="o">)</span><span class="w"> </span>AMT<span class="w"> </span>server<span class="w"> </span>running<span class="w"> </span>on<span class="w"> </span>myservername.domain.com:4433.
|
||
MeshCentral<span class="w"> </span>HTTP<span class="w"> </span>web<span class="w"> </span>server<span class="w"> </span>running<span class="w"> </span>on<span class="w"> </span>port<span class="w"> </span><span class="m">4430</span>,<span class="w"> </span><span class="nb">alias</span><span class="w"> </span>port<span class="w"> </span><span class="m">443</span>.
|
||
</code></pre></div>
|
||
<p>Notice on the second line, MeshCentral will have loaded the web certificate from NGNIX and display a matching hash. That is it, navigating to port 80 and 443 on NGINX should show the MeshCentral web page and agents should connect as expected.</p>
|
||
<h3 id="meshcentral-cira-setup-with-nginx">CIRA Setup with NGINX</h3>
|
||
<p>We can add on the section above and support reverse proxy for Intel® AMT Client Initiated more Access (CIRA) connecting that come to the server. Normally, CIRA connections come on port 4433 and use TLS.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-25-11.jpg" /></p>
|
||
<p>Since CIRA is a binary protocol, care must be taken to configure NGINX to handle the data as a TCP stream instead of HTTP. At the very bottom of the nginx.conf file, we can add the following:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="err">s</span><span class="kc">trea</span><span class="err">m</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">#</span><span class="w"> </span><span class="err">I</span><span class="kc">nternal</span><span class="w"> </span><span class="err">MPS</span><span class="w"> </span><span class="err">servers</span><span class="p">,</span><span class="w"> </span><span class="err">i</span><span class="kc">n</span><span class="w"> </span><span class="kc">t</span><span class="err">his</span><span class="w"> </span><span class="err">case</span><span class="w"> </span><span class="err">we</span><span class="w"> </span><span class="err">use</span><span class="w"> </span><span class="err">o</span><span class="kc">ne</span><span class="w"> </span><span class="err">MeshCe</span><span class="kc">ntral</span><span class="w"> </span><span class="err">MPS</span><span class="w"> </span><span class="err">server</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">o</span><span class="kc">n</span><span class="w"> </span><span class="err">our</span><span class="w"> </span><span class="err">ow</span><span class="kc">n</span><span class="w"> </span><span class="err">compu</span><span class="kc">ter</span><span class="err">.</span>
|
||
<span class="w"> </span><span class="err">ups</span><span class="kc">trea</span><span class="err">m</span><span class="w"> </span><span class="err">mpsservers</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">server</span><span class="w"> </span><span class="mf">127.0.0.1</span><span class="p">:</span><span class="mi">44330</span><span class="w"> </span><span class="err">max_</span><span class="kc">fa</span><span class="err">ils=</span><span class="mi">3</span><span class="w"> </span><span class="kc">fa</span><span class="err">il_</span><span class="kc">t</span><span class="err">imeou</span><span class="kc">t</span><span class="err">=</span><span class="mi">30</span><span class="err">s;</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
|
||
<span class="w"> </span><span class="err">#</span><span class="w"> </span><span class="err">We</span><span class="w"> </span><span class="err">ca</span><span class="kc">n</span><span class="w"> </span><span class="err">use</span><span class="w"> </span><span class="kc">t</span><span class="err">he</span><span class="w"> </span><span class="err">MeshCe</span><span class="kc">ntral</span><span class="w"> </span><span class="err">ge</span><span class="kc">nerate</span><span class="err">d</span><span class="w"> </span><span class="err">MPS</span><span class="w"> </span><span class="err">cer</span><span class="kc">t</span><span class="err">i</span><span class="kc">f</span><span class="err">ica</span><span class="kc">te</span><span class="w"> </span><span class="err">&</span><span class="w"> </span><span class="err">key</span>
|
||
<span class="w"> </span><span class="err">ssl_cer</span><span class="kc">t</span><span class="err">i</span><span class="kc">f</span><span class="err">ica</span><span class="kc">te</span><span class="w"> </span><span class="err">mpsserver</span><span class="mi">-</span><span class="err">cer</span><span class="kc">t</span><span class="mi">-</span><span class="err">public.cr</span><span class="kc">t</span><span class="err">;</span>
|
||
<span class="w"> </span><span class="err">ssl_cer</span><span class="kc">t</span><span class="err">i</span><span class="kc">f</span><span class="err">ica</span><span class="kc">te</span><span class="err">_key</span><span class="w"> </span><span class="err">mpsserver</span><span class="mi">-</span><span class="err">cer</span><span class="kc">t</span><span class="mi">-</span><span class="err">priva</span><span class="kc">te</span><span class="err">.key;</span>
|
||
<span class="w"> </span><span class="err">ssl_sessio</span><span class="kc">n</span><span class="err">_cache</span><span class="w"> </span><span class="err">shared</span><span class="p">:</span><span class="err">MPSSSL</span><span class="p">:</span><span class="mi">10</span><span class="err">m;</span>
|
||
<span class="w"> </span><span class="err">ssl_ciphers</span><span class="w"> </span><span class="err">HIGH</span><span class="p">:</span><span class="err">!aNULL</span><span class="p">:</span><span class="err">!MD</span><span class="mi">5</span><span class="err">;</span>
|
||
<span class="w"> </span><span class="err">ssl_pre</span><span class="kc">fer</span><span class="err">_server_ciphers</span><span class="w"> </span><span class="err">o</span><span class="kc">n</span><span class="err">;</span>
|
||
|
||
<span class="w"> </span><span class="err">#</span><span class="w"> </span><span class="err">MPS</span><span class="w"> </span><span class="err">server.</span>
|
||
<span class="w"> </span><span class="err">server</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">lis</span><span class="kc">ten</span><span class="w"> </span><span class="mi">4433</span><span class="w"> </span><span class="err">ssl;</span>
|
||
<span class="w"> </span><span class="err">proxy_pass</span><span class="w"> </span><span class="err">mpsservers;</span>
|
||
<span class="w"> </span><span class="err">proxy_</span><span class="kc">ne</span><span class="err">x</span><span class="kc">t</span><span class="err">_ups</span><span class="kc">trea</span><span class="err">m</span><span class="w"> </span><span class="err">o</span><span class="kc">n</span><span class="err">;</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
|
||
<span class="err">NGINX</span><span class="w"> </span><span class="err">will</span><span class="w"> </span><span class="err">lis</span><span class="kc">ten</span><span class="w"> </span><span class="err">o</span><span class="kc">n</span><span class="w"> </span><span class="err">por</span><span class="kc">t</span><span class="w"> </span><span class="mi">4433</span><span class="p">,</span><span class="w"> </span><span class="err">decryp</span><span class="kc">t</span><span class="w"> </span><span class="kc">t</span><span class="err">he</span><span class="w"> </span><span class="err">co</span><span class="kc">nne</span><span class="err">c</span><span class="kc">t</span><span class="err">io</span><span class="kc">n</span><span class="w"> </span><span class="err">a</span><span class="kc">n</span><span class="err">d</span><span class="w"> </span><span class="kc">f</span><span class="err">orward</span><span class="w"> </span><span class="err">i</span><span class="kc">t</span><span class="w"> </span><span class="kc">t</span><span class="err">o</span><span class="w"> </span><span class="mi">44330</span><span class="w"> </span><span class="err">o</span><span class="kc">n</span><span class="w"> </span><span class="kc">t</span><span class="err">he</span><span class="w"> </span><span class="err">loopback</span><span class="w"> </span><span class="err">i</span><span class="kc">nterfa</span><span class="err">ce.</span><span class="w"> </span><span class="err">We</span><span class="w"> </span><span class="err">are</span><span class="w"> </span><span class="err">goi</span><span class="kc">n</span><span class="err">g</span><span class="w"> </span><span class="kc">t</span><span class="err">o</span><span class="w"> </span><span class="err">be</span><span class="w"> </span><span class="err">used</span><span class="w"> </span><span class="kc">t</span><span class="err">he</span><span class="w"> </span><span class="err">“mpsserver”</span><span class="w"> </span><span class="err">cer</span><span class="kc">t</span><span class="err">i</span><span class="kc">f</span><span class="err">ica</span><span class="kc">te</span><span class="w"> </span><span class="kc">t</span><span class="err">ha</span><span class="kc">t</span><span class="w"> </span><span class="err">was</span><span class="w"> </span><span class="err">crea</span><span class="kc">te</span><span class="err">d</span><span class="w"> </span><span class="err">by</span><span class="w"> </span><span class="err">MeshCe</span><span class="kc">ntral</span><span class="w"> </span><span class="err">as</span><span class="w"> </span><span class="kc">t</span><span class="err">he</span><span class="w"> </span><span class="err">TLS</span><span class="w"> </span><span class="err">server</span><span class="w"> </span><span class="err">cer</span><span class="kc">t</span><span class="err">i</span><span class="kc">f</span><span class="err">ica</span><span class="kc">te</span><span class="w"> </span><span class="kc">f</span><span class="err">or</span><span class="w"> </span><span class="err">por</span><span class="kc">t</span><span class="w"> </span><span class="mf">4433.</span><span class="w"> </span><span class="err">Now</span><span class="p">,</span><span class="w"> </span><span class="err">we</span><span class="w"> </span><span class="err">jus</span><span class="kc">t</span><span class="w"> </span><span class="err">have</span><span class="w"> </span><span class="kc">t</span><span class="err">o</span><span class="w"> </span><span class="err">make</span><span class="w"> </span><span class="err">a</span><span class="w"> </span><span class="kc">fe</span><span class="err">w</span><span class="w"> </span><span class="err">cha</span><span class="kc">n</span><span class="err">ges</span><span class="w"> </span><span class="kc">t</span><span class="err">o</span><span class="w"> </span><span class="kc">t</span><span class="err">he</span><span class="w"> </span><span class="err">MeshCe</span><span class="kc">ntral</span><span class="w"> </span><span class="err">co</span><span class="kc">nf</span><span class="err">ig.jso</span><span class="kc">n</span><span class="w"> </span><span class="kc">f</span><span class="err">ile.</span>
|
||
|
||
<span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="nt">"myservername.domain.com"</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">4430</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"AliasPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"RedirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">800</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"TlsOffload"</span><span class="p">:</span><span class="w"> </span><span class="nt">"127.0.0.1"</span>
|
||
<span class="w"> </span><span class="nt">"MpsPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">44330</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"MpsAliasPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">4433</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"MpsTlsOffload"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"certUrl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://127.0.0.1:443/"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>In this new config.json, we added 3 lines. First, the MeshCentral Management Presence Server (MPS) is now on port 44330. However, the MpsAliasPort value indicates that externally, port 4433 will be used, so we need to configure Intel AMT to connect to port 4433. Lastly, we want to disable TLS support on port 44330 by setting “MpsTlsOffload” to true.</p>
|
||
<p>With this configuration, Intel AMT CIRA connections will come in and TLS will be handled by NGINX. With this setup, it’s not possible to configure Intel AMT CIRA to connect using mutual-TLS authentication, only username/password authentication is used.</p>
|
||
<h2 id="meshcentral-traefik-reverse-proxy-setup">🚦Traefik Reverse-Proxy Setup</h2>
|
||
<p>In this section, we will setup MeshCentral with Traefik, a popular reverse proxy software. This section will be much like the previous section setting up NGNIX but with a different software and configuration file. Traefik is open source and available at: https://traefik.io/</p>
|
||
<p>This section covers a really simple Traefik configuration. Traefik is capable of a lot more complex configurations.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-32-32.jpg" /></p>
|
||
<p>In this example, we will:</p>
|
||
<ul>
|
||
<li>MeshCentral on non-standard ports, but alias HTTPS to port 443.</li>
|
||
<li>Traefik will be using standard ports 80 and 443.</li>
|
||
<li>We will have Traefik perform all TLS authentication & encryption.</li>
|
||
<li>MeshCentral will read the NGINX web certificate so agents will perform correct server authentication.</li>
|
||
</ul>
|
||
<p>First we will start with the MeshCentral configuration, here is a minimal configuration that will work:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myservername.domain.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">4430</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"AliasPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"RedirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">800</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"TlsOffload"</span><span class="p">:</span><span class="w"> </span><span class="s2">"127.0.0.1"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"certUrl"</span><span class="p">:</span><span class="w"> </span><span class="nt">"https://127.0.0.1:443/"</span>
|
||
<span class="w"> </span><span class="nt">"AgentConfig"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"webSocketMaskOverride=1"</span><span class="w"> </span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note “agentConfig” line :</strong></p>
|
||
<p>Because Traefik does not support web socket connections that are not “masked”, we have to tell the Mesh Agents to mask web socket connections using this line. Once set, any new agent will be installed with the web socket masking turned on. Also note that we will be running MeshCentral on port HTTPS/4430 and HTTP/800. However, we also indicate to MeshCentral that HTTPS will really be on port 443 using the “AliasPort” line.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<p>The <code>TlsOffload</code> line indicates that MeshCentral should not perform TLS on port 4430. And the <code>certUrl</code> line indicates what URL can be used to load the external certificate that will be presented on port 443 in front of MeshCentral.</p>
|
||
<p>Now that we have MeshCentral setup, let’s take a look at a sample Traefik configuration file. In this case, we will manually configure the entrypoints, frontends and backends within the Traefik configuration file. There is a basic configuration file for Traefik 1.7:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">[</span><span class="err">global</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="err">checkNewVersio</span><span class="kc">n</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="w"> </span><span class="err">se</span><span class="kc">n</span><span class="err">dA</span><span class="kc">n</span><span class="err">o</span><span class="kc">n</span><span class="err">ymousUsage</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="kc">false</span>
|
||
|
||
<span class="p">[</span><span class="err">e</span><span class="kc">ntr</span><span class="err">yPoi</span><span class="kc">nts</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">[</span><span class="err">e</span><span class="kc">ntr</span><span class="err">yPoi</span><span class="kc">nts</span><span class="err">.h</span><span class="kc">tt</span><span class="err">p</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="err">address</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="s2">":80"</span>
|
||
<span class="w"> </span><span class="p">[</span><span class="err">e</span><span class="kc">ntr</span><span class="err">yPoi</span><span class="kc">nts</span><span class="err">.h</span><span class="kc">tt</span><span class="err">p.redirec</span><span class="kc">t</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="err">e</span><span class="kc">ntr</span><span class="err">yPoi</span><span class="kc">nt</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="s2">"https"</span>
|
||
<span class="w"> </span><span class="p">[</span><span class="err">e</span><span class="kc">ntr</span><span class="err">yPoi</span><span class="kc">nts</span><span class="err">.h</span><span class="kc">tt</span><span class="err">ps</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="err">address</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="s2">":443"</span>
|
||
<span class="w"> </span><span class="p">[</span><span class="err">e</span><span class="kc">ntr</span><span class="err">yPoi</span><span class="kc">nts</span><span class="err">.h</span><span class="kc">tt</span><span class="err">ps.</span><span class="kc">tls</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">[[</span><span class="err">e</span><span class="kc">ntr</span><span class="err">yPoi</span><span class="kc">nts</span><span class="err">.h</span><span class="kc">tt</span><span class="err">ps.</span><span class="kc">tls</span><span class="err">.cer</span><span class="kc">t</span><span class="err">i</span><span class="kc">f</span><span class="err">ica</span><span class="kc">tes</span><span class="p">]]</span>
|
||
<span class="w"> </span><span class="err">cer</span><span class="kc">t</span><span class="err">File</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="s2">"webserver-cert-public.crt"</span>
|
||
<span class="w"> </span><span class="err">keyFile</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="s2">"webserver-cert-private.key"</span>
|
||
|
||
<span class="p">[</span><span class="kc">f</span><span class="err">ile</span><span class="p">]</span>
|
||
|
||
<span class="p">[</span><span class="err">backe</span><span class="kc">n</span><span class="err">ds</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">[</span><span class="err">backe</span><span class="kc">n</span><span class="err">ds.backe</span><span class="kc">n</span><span class="err">d</span><span class="mi">1</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">[</span><span class="err">backe</span><span class="kc">n</span><span class="err">ds.backe</span><span class="kc">n</span><span class="err">d</span><span class="mf">1.</span><span class="err">heal</span><span class="kc">t</span><span class="err">hcheck</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="err">pa</span><span class="kc">t</span><span class="err">h</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="s2">"/health.ashx"</span>
|
||
<span class="w"> </span><span class="err">i</span><span class="kc">nter</span><span class="err">val</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="s2">"30s"</span>
|
||
|
||
<span class="w"> </span><span class="p">[</span><span class="err">backe</span><span class="kc">n</span><span class="err">ds.backe</span><span class="kc">n</span><span class="err">d</span><span class="mf">1.</span><span class="err">servers.server</span><span class="mi">1</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="err">url</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="s2">"http://127.0.0.1:4430"</span>
|
||
<span class="w"> </span><span class="err">weigh</span><span class="kc">t</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="mi">1</span>
|
||
|
||
<span class="p">[</span><span class="kc">fr</span><span class="err">o</span><span class="kc">nten</span><span class="err">ds</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">[</span><span class="kc">fr</span><span class="err">o</span><span class="kc">nten</span><span class="err">ds.</span><span class="kc">fr</span><span class="err">o</span><span class="kc">nten</span><span class="err">d</span><span class="mi">1</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="err">e</span><span class="kc">ntr</span><span class="err">yPoi</span><span class="kc">nts</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="p">[</span><span class="s2">"https"</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="err">backe</span><span class="kc">n</span><span class="err">d</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="s2">"backend1"</span>
|
||
<span class="w"> </span><span class="err">passHos</span><span class="kc">t</span><span class="err">Header</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">[</span><span class="kc">fr</span><span class="err">o</span><span class="kc">nten</span><span class="err">ds.</span><span class="kc">fr</span><span class="err">o</span><span class="kc">nten</span><span class="err">d</span><span class="mf">1.</span><span class="err">rou</span><span class="kc">tes</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">[</span><span class="kc">fr</span><span class="err">o</span><span class="kc">nten</span><span class="err">ds.</span><span class="kc">fr</span><span class="err">o</span><span class="kc">nten</span><span class="err">d</span><span class="mf">1.</span><span class="err">rou</span><span class="kc">tes</span><span class="err">.mai</span><span class="kc">n</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="err">rule</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="s2">"Host:myserver.domain.com,localhost"</span>
|
||
|
||
<span class="p">[</span><span class="err">api</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="err">e</span><span class="kc">ntr</span><span class="err">yPoi</span><span class="kc">nt</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="s2">"traefik"</span>
|
||
<span class="w"> </span><span class="err">dashboard</span><span class="w"> </span><span class="err">=</span><span class="w"> </span><span class="kc">true</span>
|
||
</code></pre></div>
|
||
<p>The enterPoints section shows we have two entry points, port 80 will be redirected to port 443. Traefik will perform this redirection so MeshCentral will never see port 80 connections. Port 443 will be setup using the given TLS certificates. In this example, we just used the certificate files generated by MeshCentral in the “meshcentral-data” folder. You can use the two certificate files as-is.</p>
|
||
<p>The backends section configures one MeshCentral server on port “4430”. Traefik will additionally check the health of the MeshCentral server periodically, every 30 seconds.</p>
|
||
<p>The frontends section is what routes the connections coming in the entry points to the backend servers. In this case, the HTTPS entry point is routed to the MeshCentral server is the hostname matches <code>myserver.domain.com</code> or <code>localhost</code>.</p>
|
||
<p>Finally, the API section creates a web portal on port 8080 for monitoring of Traefik.</p>
|
||
<h2 id="meshcentral-haproxy-reverse-proxy-setup">⚡ HAProxy Reverse-Proxy Setup</h2>
|
||
<p>In this section, we will setup MeshCentral with HAProxy, a small popular reverse proxy software. This section will be much like the previous sections setting up NGNIX and Traefik but with a different software and configuration file. HAProxy is free and available at: <a href="https://www.haproxy.org/">HAProxy Official Website</a></p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-34-54.jpg" /></p>
|
||
<p>This section covers a really simple configuration. HAProxy is capable of a lot more complex configurations. In the following example, HAProxy will perform TLS and forward the un-encrypted traffic to MeshCentral on port 444. HAProxy will add extra “X-Forwarded-Host” headers to the HTTP headers so that MeshCentral will know from the IP address the connection comes from.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-35-32.jpg" /></p>
|
||
<p>In the following configuration file, we have browser connections on port 80 being redirected to HTTPS port 443. We also have Let’s Encrypt cert bot for getting a real TLS certificate and “mesh.sample.com” being redirected to 127.0.0.1:444.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="l l-Scalar l-Scalar-Plain">global</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">log /dev/log local0</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">log /dev/log local1 notice</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">chroot /var/lib/haproxy</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">stats timeout 30s</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">user haproxy</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">group haproxy</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">daemon</span>
|
||
|
||
<span class="l l-Scalar l-Scalar-Plain">defaults</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">log global</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">mode http</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">option httplog</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">option dontlognull</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">option forwardfor</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">option http-server-close</span>
|
||
|
||
<span class="l l-Scalar l-Scalar-Plain">frontend http</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bind *:80</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">redirect scheme https code 301 if !{ ssl_fc }</span>
|
||
|
||
<span class="l l-Scalar l-Scalar-Plain">frontend https</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bind *:443 ssl crt /etc/haproxy/cert.pem</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">http-request add-header X-Forwarded-Proto https</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">acl acmepath path_beg /.well-known/acme-challenge/</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">acl meshcentralhost hdr(host) -i mesh.sample.com</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">acl meshcentralhost hdr(host) -i mesh.sample.com:443</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">use_backend acme if acmepath</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">use_backend meshcentral if meshcentralhost</span>
|
||
|
||
<span class="l l-Scalar l-Scalar-Plain">backend acme</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">server certbot localhost:54321</span>
|
||
|
||
<span class="l l-Scalar l-Scalar-Plain">backend meshcentral</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">http-request add-header X-Forwarded-Host %[req.hdr(Host)]</span>
|
||
<span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">server meshcentral 127.0.0.1:444</span>
|
||
</code></pre></div>
|
||
<p>On the MeshCentral side, we are not going to use port 80 and need the main HTTPS port to not perform TLS and listen on port 444.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myservername.domain.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">444</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"AliasPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"RedirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"TlsOffload"</span><span class="p">:</span><span class="w"> </span><span class="s2">"127.0.0.1"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"certUrl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://127.0.0.1:443/"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>We also specify “127.0.0.1” in TLS offload since we want MeshCentral to make use of the X-Forwarded-Host header that is set by HAProxy.</p>
|
||
<h2 id="meshcentral-running-in-a-production-environment">🏭 Running in a Production Environment</h2>
|
||
<p>When running MeshCentral is a production environment, administrators should set NodeJS to run in production mode. There is a good article here (http://www.hacksparrow.com/running-express-js-in-production-mode.html) on what this mode is and how to set it. This mode will also boost the speed of the web site on small devices like the Raspberry Pi. To run in production mode, the environment variable “NODE_ENV” must be set to “production”.</p>
|
||
<ul>
|
||
<li>On Linux, this is done like this:</li>
|
||
</ul>
|
||
<div class="highlight"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">NODE_ENV</span><span class="o">=</span>production
|
||
</code></pre></div>
|
||
<ul>
|
||
<li>On Windows, it’s done like this:</li>
|
||
</ul>
|
||
<div class="highlight"><pre><span></span><code>SET<span class="w"> </span><span class="nv">NODE_ENV</span><span class="o">=</span>production
|
||
</code></pre></div>
|
||
<p>Special care must be taken to set the environment variable in such a way that if the server is rebooted, this value is still set. Once set, if you run MeshCentral manually, you will see :</p>
|
||
<div class="highlight"><pre><span></span><code>MeshCentral<span class="w"> </span>HTTP<span class="w"> </span>redirection<span class="w"> </span>web<span class="w"> </span>server<span class="w"> </span>running<span class="w"> </span>on<span class="w"> </span>port<span class="w"> </span><span class="m">80</span>.
|
||
MeshCentral<span class="w"> </span>v0.2.2-u,<span class="w"> </span>Hybrid<span class="w"> </span><span class="o">(</span>LAN<span class="w"> </span>+<span class="w"> </span>WAN<span class="o">)</span><span class="w"> </span>mode,<span class="w"> </span>Production<span class="w"> </span>mode.
|
||
MeshCentral<span class="w"> </span>Intel<span class="o">(</span>R<span class="o">)</span><span class="w"> </span>AMT<span class="w"> </span>server<span class="w"> </span>running<span class="w"> </span>on<span class="w"> </span>devbox.mesh.meshcentral.com:4433.
|
||
MeshCentral<span class="w"> </span>HTTPS<span class="w"> </span>web<span class="w"> </span>server<span class="w"> </span>running<span class="w"> </span>on<span class="w"> </span>devbox.mesh.meshcentral.com:443.
|
||
</code></pre></div>
|
||
<p>In production mode, ExpressJS will cache some files in memory making the web server much faster and any exceptions thrown by the ExpressJS will not result in the stack trace being sent to the browser.</p>
|
||
<h2 id="meshcentral-two-step-authentication">📲 Two step authentication</h2>
|
||
<p>If the MeshCentral server is setup with a certificate name and not setup to use Windows domain authentication, then users will have the options to use 2-step authentication using the Google Authenticator application or any compatible application. Use of this option should be encouraged for users that manage a lot of critical computers. Once active the users will need to enter their username, password and a time limited token to login.</p>
|
||
<p>To get this features setup, users will need to go to the “My Account” tab or the “My Account” menu in the mobile application. They then select, “Add 2-stop login” and follow the instructions.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-38-11.jpg" /></p>
|
||
<p>Note that if a user performs a password recovery using email, the 2-step authentication is then turned off and will need to be turned on again. This is not idea as someone being able to intercept the user’s email could still log into the web site. Users should make sure to properly protect their email account.</p>
|
||
<p>Another form of MFA or Multi-factor Authentication is hardware based OTP (One Time Password) solution providing 2FA or Two-factor authentication. Yubikey is fully supported in MeshCentral.</p>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/FvDHlcdNepQ" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<p>And taking authentication to the next step is removing the login page entirely. Use LoginKey 3FA with MeshCentral.</p>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/-WKY8Wy0Huk" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<p>You can also setup <a href="https://github.com/Ylianst/MeshCentral/blob/master/docs/docs/meshcentral/security.md#duo-2fa-setup">Duo 2FA</a> which is a commertial offering.</p>
|
||
<h2 id="meshcentral-server-backup-restore">💾 Server Backup & Restore</h2>
|
||
<p>It’s very important that the server be backed up regularly and that a backup be kept offsite. Luckily, performing a full backup of the MeshCentral server is generally easy to do. For all installations make sure to back up the following two folders and all sub-folders.</p>
|
||
<ol>
|
||
<li><code>meshcentral-data</code></li>
|
||
<li><code>meshcentral-files</code></li>
|
||
</ol>
|
||
<p>If using NeDB that is built into MeshCentral, you are done. If you are running MongoDB, you will need to perform an extra step. In the command shell, run mongodump to archive all of the MongoDB databases.</p>
|
||
<div class="highlight"><pre><span></span><code>mongodump<span class="w"> </span>--archive<span class="o">=</span>backup.archive
|
||
</code></pre></div>
|
||
<p>Then, keep the backup.archive file in a safe place. It’s critical that the content of meshcentral-data be backed up in a secure location and preferably using encryption, this is because it contains certificates that give this server its unique personality. Once agents are installed, they will only connect to this server and no other. If you reinstall MeshCentral, even if it is with the same domain name, agents will not connect to the new server since the server certificates are different. Also, someone with access to a backup of “meshcentral-data” could impersonate the server.</p>
|
||
<p>To restore back backup, just install a MeshCentral server, make sure it works correctly. Stop it, wipe the old <code>meshcentral-data</code> and <code>meshcentral-files</code> and put the backup version instead. If using MongoDB, copy the backup.archive back, make sure to clean up any existing “meshcentral” database, run <code>mongo</code> and type:</p>
|
||
<div class="highlight"><pre><span></span><code>use<span class="w"> </span>meshcentral
|
||
</code></pre></div>
|
||
<div class="highlight"><pre><span></span><code>db.dropDatabase<span class="o">()</span>
|
||
</code></pre></div>
|
||
<p>Then exit with Ctrl-C and run:</p>
|
||
<div class="highlight"><pre><span></span><code>mongorestore<span class="w"> </span>--archive<span class="o">=</span>backup.archive
|
||
</code></pre></div>
|
||
<p>This will re-import the database from the backup. You can then start MeshCentral again.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The two values for <code>backup</code> and <code>restore</code> in the json are only valid for databases backed by NeDB</p>
|
||
</div>
|
||
<h3 id="meshcentral-backup-to-google-drive">Backup to Google Drive</h3>
|
||
<div class="highlight"><pre><span></span><code>sudo<span class="w"> </span>systemctl<span class="w"> </span>stop<span class="w"> </span>meshcentral.service
|
||
</code></pre></div>
|
||
<div class="highlight"><pre><span></span><code>nano<span class="w"> </span>/opt/meshcentral/meshcentral-data/config.json
|
||
</code></pre></div>
|
||
<p>Remove underscored items</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-06-17-15-56-14.jpg" /></p>
|
||
<div class="highlight"><pre><span></span><code>sudo<span class="w"> </span>systemctl<span class="w"> </span>start<span class="w"> </span>meshcentral.service
|
||
</code></pre></div>
|
||
<div class="highlight"><pre><span></span><code>sudo<span class="w"> </span>systemctl<span class="w"> </span>status<span class="w"> </span>meshcentral.service
|
||
</code></pre></div>
|
||
<p>Log into your MC:</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-06-17-15-56-55.jpg" /></p>
|
||
<p><img alt="" src="../meshcentral/images/2022-06-17-15-57-03.jpg" /></p>
|
||
<p>Create desktop app</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-06-17-15-57-15.jpg" /></p>
|
||
<p>Enter the Client ID and Client Secret into MC</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-06-17-15-57-30.jpg" /></p>
|
||
<p><img alt="" src="../meshcentral/images/2022-06-17-15-57-52.jpg" /></p>
|
||
<h2 id="meshcentral-hashicorp-vault-support">🗝️ HashiCorp Vault support</h2>
|
||
<p>MeshCentral has built-in support for HashiCorp Vault so that all configuration and certificates used by MeshCentral are retrieved from a Vault server. Vault is a secret store server and when used with MeshCentral, the MeshCentral server will not be storing any secrets locally. You can get started with Vault here: <a href="https://www.vaultproject.io/">HashiCorp Vault Official Site</a></p>
|
||
<p>Once you got a MeshCentral server working correctly, you can start a simple demonstration Vault server by typing:</p>
|
||
<div class="highlight"><pre><span></span><code>vault<span class="w"> </span>server<span class="w"> </span>-dev
|
||
</code></pre></div>
|
||
<p>When you run the server in developer mode, you will see a secret token and unseal key on the screen. These two values will be used in the commands to follow. You can load the configuration file and all certificates from “meshcentral-data” into Vault by typing this:</p>
|
||
<div class="highlight"><pre><span></span><code>node node_modules/meshcentral --vaultpushconfigfiles --vault http://127.0.0.1:8200 --token s.cO4… --unsealkey 7g4w… --name meshcentral
|
||
</code></pre></div>
|
||
<p>Once all of the files have been written into Vault, you can take a look at the Vault web user interface to see all of the secrets. It will be in “secret/meshcentral”:</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-42-49.jpg" /></p>
|
||
<p>The <code>config.json</code> and <code>terms.txt</code> files and files in <code>meshcentral-data</code> that end with <code>.key</code>, <code>.crt</code>, <code>.jpg</code> and <code>.png</code> will be stored in Vault. You can then run MeshCentral like this:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--vault<span class="w"> </span>http://127.0.0.1:8200<span class="w"> </span>--token<span class="w"> </span>s.cO4…<span class="w"> </span>--unsealkey<span class="w"> </span>7g4w…<span class="w"> </span>--name<span class="w"> </span>meshcentral
|
||
</code></pre></div>
|
||
<p>MeshCentral will first read all of the files from Vault and get started. An alternative to this is to create a very small <code>config.json</code> file in “meshcentral-data” that contains only the Vault configuration like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"vault"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"endpoint"</span><span class="p">:</span><span class="w"> </span><span class="s2">"http://127.0.0.1:8200"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"token"</span><span class="p">:</span><span class="w"> </span><span class="s2">"s.cO4Q…"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"unsealkey"</span><span class="p">:</span><span class="w"> </span><span class="s2">"7g4wFC…"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"meshcentral"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Once the config.json file is setup, you can just run MeshCentral without any arguments.</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>node_modules/meshcentral
|
||
</code></pre></div>
|
||
<p>Lastly you can all pull all of the files out of Vault using this command line:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--vaultpullconfigfiles<span class="w"> </span>--vault<span class="w"> </span>http://127.0.0.1:8200<span class="w"> </span>--token<span class="w"> </span>s.cO4…<span class="w"> </span>--unsealkey<span class="w"> </span>7g4w…<span class="w"> </span>--name<span class="w"> </span>meshcentral
|
||
</code></pre></div>
|
||
<p>And delete the Vault secrets using this:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--vaultdeleteconfigfiles<span class="w"> </span>--vault<span class="w"> </span>http://127.0.0.1:8200<span class="w"> </span>--token<span class="w"> </span>s.cO4…<span class="w"> </span>--unsealkey<span class="w"> </span>7g4w…<span class="w"> </span>--name<span class="w"> </span>meshcentral
|
||
</code></pre></div>
|
||
<h2 id="meshcentral-database-record-encryption">🔏 Database Record Encryption</h2>
|
||
<p>Regardless if using the default NeDB database or MongoDB, MeshCentral can optionally encrypt sensitive data that is stored in the database. When enabled, this encryption is applied to user credentials and Intel AMT credentials.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-44-03.jpg" /></p>
|
||
<p>The additional encryption does the affect database operations and can be used in addition to additional database security. In the following image, we see on the left a normal user record including user credential hashes and data required for two-factor authentication. On the right side, these values are encrypted using AES-256-GCM in the <code>_CRYPT</code> field.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-44-25.jpg" /></p>
|
||
<p>Only some data fields are encrypted and the “_CRYPT” entry will only be present when one or more fields are present that need to be secured. To enable this feature, add the “DbRecordsEncryptKey” with a password string to the “settings” section of the config.json like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">4430</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"RedirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">800</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"DbRecordsEncryptKey"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MyReallySecretPassword"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>The provided password will be hashed using SHA384 and the result with be used as an encryption key. When DbRecordsEncryptKey is set, any new or updated records that are written will be encrypted when needed. Existing encrypted records will be read and decrypted as needed. You can force the all entries to be re-written by running:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--recordencryptionrecode
|
||
</code></pre></div>
|
||
<p>This command will re-write entries in the database that could require added security and force the application of record encryption. You can also specify a key for decryption only like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">4430</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"RedirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">800</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"DbRecordsDecryptKey"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MyReallySecretPassword"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>When set, the key will only be used for decryption and any new or updated records in the database will not be written with record encryption. You can then run this command again to force all records to be rewritten without encryption:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--recordencryptionrecode
|
||
</code></pre></div>
|
||
<p>It’s really important to keep the encryption key in a safe place along with database backups. If the database is backed up but the record encryption key is lost, it will not be possible to recover the secured data in the database.</p>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>Also note that database record encryption can and should be used along with other data protection systems.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<h2 id="meshcentral-mongodb-free-server-monitoring">📊 MongoDB free server monitoring</h2>
|
||
<p>If running with MongoDB version 4.x, there is a free database monitoring service that is provided. Just run “mongo” and you may see the following:</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-45-31.jpg" /></p>
|
||
<p>Type <code>db.enableFreemonitoring()</code> if you want to enable this. You will be given a URL to access the data and can turn it back off at any time. The web page will look something like this:</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-45-45.jpg" /></p>
|
||
<p>In addition to database specific information, the graphs track CPU, memory and disk usage. This can be useful to track how well the server is responding under load.</p>
|
||
<h2 id="meshcentral-meshcentral-single-sign-on-sso">🔓 MeshCentral Single Sign-On (SSO)</h2>
|
||
<p>As with any web application deployed in organization, it’s convenient and more secure for users to have a single set of credentials that can be used across many services. In this section we take a look at how to configure MeshCentral so that you can sign-in using credentials from other services. This allows users to completely skip creating a user account on MeshCentral or having to remember usernames and password for one more web site. There are two single sign-on protocols that are supported in MeshCentral, OAuth2 and SAML. We will take a look at an example for each one.</p>
|
||
<p>Before you get started, your MeshCentral server must be publicly facing on the internet and have a valid TLS certificate. For example, by setting up Let’s Encrypt. After the web site is working correctly user the steps below.</p>
|
||
<h3 id="meshcentral-ldap">LDAP</h3>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/UQMbNQk85g8" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<p>You can integrate LDAP using <a href="https://github.com/Ylianst/MeshCentral/blob/f05eb9a198bed249c2b1a969ce17a41404ef70a6/meshcentral-config-schema.json#L505-L513">these</a> configuration options</p>
|
||
<p><img alt="" src="../meshcentral/images/ldap_integration.jpg" /></p>
|
||
<h3 id="meshcentral-twitter-authentication">Twitter Authentication</h3>
|
||
<p>Like many other services, Twitter allows its users to login to other web site using Twitter credentials using OAuth2. Start by creating an account on Twitter and logging in. Then navigate to <a href="https://developer.twitter.com/en/apps">Twitter Developer Apps</a>, this is where you can create new applications that are compatible with Twitter.</p>
|
||
<p>Start by creating a new application and fill in the application form. Give your application and name, description, server URL and more.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-48-17.jpg" /></p>
|
||
<p>Make sure to select “Enable Sign in with Twitter” and set the callback URL to <code>https://(server.domain.com)/auth-twitter-callback</code>. This is the URL that Twitter will redirect users to once they are logged in. For example this is what a sample application would look like:</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-48-41.jpg" /></p>
|
||
<p>Once the new application is created, go to the <code>Keys and tokens</code> tab. You will need the <code>API Key</code> and <code>API secret key</code> values. In the MeshCentral <code>config.json</code>, place these two values as <code>clientid</code> and <code>clientsecret</code> of the Twitter section of the <code>AuthStrategies</code>.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-48-54.jpg" /></p>
|
||
<p>Once done, your config.json should look a bit like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myserver.mydomain.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"RedirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">80</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MyServer"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Title2"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Servername"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"NewAccounts"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authStrategies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"twitter"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"clientid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"xxxxxxxxxxxxxxxxxxxxxxx"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientsecret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>Note that if you do not allow new accounts, any new users that use Twitter credentials will not be able to login to MeshCentral. One trick is to allow new account, login and change this setting again. Once the config.json is correct, restart the server and you should see the Twitter icon on the login screen. When restarting the MeshCentral server, new modules will need to be installed to support this new feature. Depending on how your server is setup, you may need to restart the server manually to allow the new modules to be installed.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-49-25.jpg" /></p>
|
||
<h3 id="meshcentral-google-github-reddit-authentication">Google, GitHub, Reddit Authentication</h3>
|
||
<p>The exact same process as shown in the previous section can be repeated for Google, GitHub and Reddit. In each case, you need to go to each respective credential provider and get a <code>ClientID</code> and <code>ClientSecret</code> for each service. You also need to register the correct callback URL for each service.</p>
|
||
<p>Take a look at the <code>config.json</code> below and note the callback URL that will need to be registered for each service provider.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myserver.mydomain.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"RedirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">80</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MyServer"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Title2"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Servername"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"NewAccounts"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authStrategies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"twitter"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__callbackurl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://server/auth-twitter-callback"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"xxxxxxxxxxxxxxxxxxxxxxx"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientsecret"</span><span class="p">:</span><span class="w"> </span><span class="s2">" xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx "</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"google"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__callbackurl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://server/auth-google-callback"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"xxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientsecret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"xxxxxxxxxxxxxxxxxxxxxxx"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"github"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__callbackurl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://server/auth-github-callback"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"xxxxxxxxxxxxxxxxxxxxxxx"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientsecret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"reddit"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__callbackurl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://server/auth-reddit-callback"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"xxxxxxxxxxxxxxxxxxxxxxx"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientsecret"</span><span class="p">:</span><span class="w"> </span><span class="s2">" xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx "</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>It’s possible to enable all four of these service providers at the same time to offer the most flexibility for users. Note that when using an OAuth service provider, MeshCentral does not offer two-factor authentication since it will be handled by the provider depending on user configuration.</p>
|
||
<h3 id="meshcentral-microsoft-azure-active-directory">Microsoft Azure Active Directory</h3>
|
||
<p>In this section we look at how to setup MeshCentral to Azure Active Directory using OAuth. Like all other sections about setting up single sign-on, make sure your MeshCentral server is already setup on the public Internet with a valid TLS certificate. You can then start by adding a new application registration to the Azure portal.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-50-18.jpg" /></p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-50-30.jpg" /></p>
|
||
<p>We give our application a name, generally the domain name of the MeshCentral server is a good choice. Then you can setup the redirect URL to <code>https://[servername]/auth-azure-callback</code>. Make sure to type this correctly, all lower case with the full domain name of your MeshCentral server. Once done, there are two values we will need later, the Application ID and Tenant ID.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-50-52.jpg" /></p>
|
||
<p>Next, we need to create a secret that will be shared between Azure and MeshCentral. Go to the <code>Certificates & secrets</code> section and click <code>New client secret</code>. You then enter a name and for our example, we will opt to never make it expire.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-51-14.jpg" /></p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-51-29.jpg" /></p>
|
||
<p>We then copy the resulting secret and this will be the 3rd and final value we need to get MeshCentral setup. Now, we take the application ID, tenant ID and secret and place these values in the MeshCentral config.json like so:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myserver.mydomain.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"RedirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">80</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MyServer"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Title2"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Servername"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"NewAccounts"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authStrategies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"azure"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"newAccounts"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"be4aadd3-77b8-4e55-af8a-4b8e2d994cb5"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientsecret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"NP0XXXXXXXXXXXXXXXXXXX"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"tenantid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"18910a48-e492-4c49-8043-3449f7964bd6"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>The <code>Application ID</code> value is placed as <code>Client ID</code> in the configuration file. You can also see that in the example above, we have <code>NewAccounts</code> set to false in the default MeshCentral domain, but set to true in the Azure section. This indicates that new accounts are not allowed in this domain except if it’s a new user that is authenticating thru Azure. Once done, restart the MeshCentral server. Depending on your setup, you many need to run MeshCentral once manually to allow new required modules to be installed. Once running again, you should see the Azure single sign-on button on the login page.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-52-05.jpg" /></p>
|
||
<h3 id="meshcentral-jumpcloud-authentication-using-saml">JumpCloud Authentication using SAML</h3>
|
||
<p>While using OAuth may be interesting, it’s more likely that MeshCentral servers used in an enterprise environment will want to use SAML (Security Assertion Markup Language). This is a widely deployed sign-on protocol used in enterprises so that, for example, employees can login to many different web sites using a single set of company credentials. MeshCentral can be one of many web sites that some users may want to log into.</p>
|
||
<p>In this section, we setup MeshCentral with JumpCloud, an easy to use sign-in provider. You can create an account on JumpCloud for free with up to 10 users allowing you to quickly get setup and test the following setup. In the next section, we look at a generic SAML configuration.</p>
|
||
<p>Before getting started with this section, make sure your server is on the Internet and publicly available and that it has a valid TLS certificate. You can use Let’s Encrypt to get a valid TLS certificate. Then, start by going to <a href="https://jumpcloud.com">JumpCloud</a> and creating an administrator account. Once setup, go to <code>Applications</code> and click on the big plug sign to create a new application.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-52-36.jpg" /></p>
|
||
<p>You will need to create a custom SAML application by clicking the <code>Custom SAML App</code>.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-52-53.jpg" /></p>
|
||
<p>Then, you can fill in the form with an application name and logo.</p>
|
||
<ul>
|
||
<li>For the IdP Entity ID, put <code>jumpcloud</code>.</li>
|
||
<li>For the SP Entity ID put <code>meshcentral</code>.</li>
|
||
<li>For the ACS URL, put the callback URL of your server. In this case it will be <code>https://(yourservername)/auth-jumpcloud-callback</code></li>
|
||
<li>Lastly in the attributes section, add 3 user attribute mapping.<ul>
|
||
<li><code>firstname</code> to <code>firstname</code></li>
|
||
<li><code>lastname</code> to <code>lastname</code></li>
|
||
<li><code>email</code> to <code>email</code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The attribute mappings will allow MeshCentral to receive from JumpCloud the first and last name of the user and the email address of the use. If any of these values are changed in the future, MeshCentral will update them the next time the user logs into MeshCentral. Here is an example configuration with red arrows next to important values.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-53-38.jpg" /></p>
|
||
<p>Once setup, you will need to allow one or more users to use the new application. One way to do this is to just add your new application to the <code>All Users</code> group.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-54-31.jpg" /></p>
|
||
<p>We are now almost done with JumpCloud. The last thing we need to do is download the certificate that JumpCloud will be using to sign the SAML assertions. You can get this certificate by going in the <code>Applications</code> tab, click on your new application and select <code>Download Certificate</code> as shown here.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-54-50.jpg" /></p>
|
||
<p>Save the certificate as <code>jumpcloud-saml.pem</code> and place it in the <code>meshcentral-data</code> folder. You are now ready to configure MeshCentral.</p>
|
||
<p>Edit the <code>config.json</code> and make it look like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myserver.mydomain.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"RedirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">80</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MyServer"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Title2"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Servername"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"NewAccounts"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authStrategies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"jumpcloud"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__callbackurl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://server/auth-jumpcloud-callback"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"NewAccounts"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"entityid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"meshcentral"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"idpurl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.jumpcloud.com/saml2/saml2"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"jumpcloud-saml.pem"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Take note that the <code>entityid</code>, <code>idpurl</code> and <code>cert</code> are values taken from JumpCloud. The callback URL should be configured in JumpCloud as we have done in previous steps. You can see that in the example above, we have <code>NewAccounts</code> set to false in the default MeshCentral domain, but set to true in the JumpCloud section. This indicates that new accounts are not allowed in this domain except if it’s a new user that is authenticating thru JumpCloud.</p>
|
||
<p>You are now ready to restart the MeshCentral server. Extra modules will be needed to support SAML and so, depending on your server configuration, you may need to run MeshCentral manually once to allow the new modules to be installed from NPM. Once restarted, you should see the JumpCloud sign-in button on the login screen.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-55-29.jpg" /></p>
|
||
<p>Users can sign-in using the regular username and password or using JumpCloud.</p>
|
||
<h3 id="meshcentral-generic-saml-setup">Generic SAML setup</h3>
|
||
<p>In this section, we look at configuring SAML with a generic authentication provider. The setup is exactly the same as with JumpCloud in the previous section, but we will be using a different section in the <code>config.json</code> to that a generic login icon is shown on the login page.</p>
|
||
<p>A generic SAML setup will look like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myserver.mydomain.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"RedirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">80</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MyServer"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Title2"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Servername"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"NewAccounts"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authStrategies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"saml"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__callbackurl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://server/auth-saml-callback"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"entityid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"meshcentral"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"idpurl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://server/saml2"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"saml.pem"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>The callback URL will be of the form <code>https://(servername)/auth-saml-callback</code>. You should set the entityid, idpurl as given by the identity provider. Lastly, place the identity provider certificate file in the <code>meshcentral-data</code> folder and indicate the name of the file in <code>cert</code>.</p>
|
||
<p>Once setup, restart the server and you should see a Single Sign-on button on the login screen.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-56-05.jpg" /></p>
|
||
<p>Enabling SAML will require MeshCentral to install extra modules from NPM, so depending on your server configuration, you may need to run MeshCentral once manually.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>MeshCentral only supports "POST". <a href="https://github.com/Ylianst/MeshCentral/issues/4725">For example Authentik's</a> default setting is to use <code>Redirect</code> as a <code>Service Provider Binding</code>.</p>
|
||
</div>
|
||
<h3 id="meshcentral-generic-openid-connect-setup">Generic OpenID Connect Setup</h3>
|
||
<p>Generally, if you are using an IdP that supports OpenID Connect (OIDC), you can use a very basic configuration to get started, and if needed, add more specific or advanced configurations later. Here is what your config file will look like with a basic, generic, configuration.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"mesh.your.domain"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"sqlite3"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Mesh"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"title2"</span><span class="p">:</span><span class="w"> </span><span class="s2">".Your.Domain"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authStrategies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"oidc"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"issuer"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientsecret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"newAccounts"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>As you can see, this is roughly the same as all the other OAuth2 based authentication strategies. These are the basics you need to get started using OpenID Connect because it's still authenticating with OAuth2. If you plan to take advantage of some of the more advanced features provided by this strategy you should consider reading the <a href="#meshcentral-openidconnectstrategy">additional strategy documentation</a>.</p>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>MeshCentral will use <code>https://mesh.your.domain/auth-oidc-callback</code> as the default redirect uri.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<h2 id="meshcentral-improvements-to-meshcentral">✨ Improvements to MeshCentral</h2>
|
||
<p>In 2007, the first version of MeshCentral was built. We will refer to it as “MeshCentral1”. When MeshCentral1 was designed, HTML5 did not exist and web sockets where not implemented in any of the major browsers. Many design decisions were made at the time that are no longer optimal today. With the advent of the latest MeshCentral, MeshCentral1 is no longer supported and MeshCentral v2 has been significantly redesigned and mostly re-written based of previous version. Here is a list of improvements made in MeshCentral when compared with MeshCentral1 :</p>
|
||
<ul>
|
||
<li><strong>Quick Installation –</strong><blockquote>
|
||
<p>By having MeshCentral published on NPM (www.npmjs.com) it’s now easy to download and install MeshCentral on both Linux and Windows<em>. On Linux</em> you can use NPM directly (<code>npm install meshcentral</code>) and on Windows you can use the <code>.MSI installer</code>.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>Cross-Platform Support –</strong><blockquote>
|
||
<p>Contrary to MeshCentral1 that only runs on Windows<em>, MeshCentral can run on any environment that supports NodeJS. This includes Windows</em>, Linux<em> and </em>OSX<em>. Because MeshCentral runs on Linux, it often lowers hosting costs and makes it possible to run MeshCentral in a Docker</em> container environment.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>Runs with Little Compute Resources –</strong><blockquote>
|
||
<p>Typical MeshCentral1 installation requires a large disk space foot print (approx* 30G of disk space) and is compute intensive even for small deployments. MeshCentral requires little resources to host (70MB) and able to deliver reasonable performance on a 900Mhz CPU with 1GB RAM. </p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>Multi-Tenancy and Load Balancing Support –</strong><blockquote>
|
||
<p>MeshCentral can handle hosting many server instances at once. Each instance or <code>domain</code> has it’s own administrators, users and computers to manage. The server can handle each instance using a url path <code>server.com/customer1</code> or a DNS name <code>customer1.server.com</code>. Many customers can be handled by having all the DNS names point to the same server IP address. MeshCentral will take care of serving the right TLS certificate for each connection.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>Single Executable –</strong><blockquote>
|
||
<p>MeshCentral is a single-module or single executable server. All of the components of MeshCentral1 including IIS, Swarm, AJAX, Social, Manageability Servers are all build into one single executable. This makes it super easy to setup and run, it also minimizes problems and overhead caused by having many components communicate to each other. When the server is updated, all of the components are updated at once and effective.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>Web Application Design –</strong><blockquote>
|
||
<p>MeshCentral1 has 100’s of web pages and often times a click on a web page causes the browser to load a different web page and this creates more load on the server. With MeshCentral there are only two main web pages: The login page and the main web application. This design is much more responsive since the server now delegates most of the UI workload to the client’s web browser.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>Real-Time User Interface –</strong><blockquote>
|
||
<p>In MeshCentral, the user never has to hit the <code>refresh</code> button to update the web page. The web interface is completely real-time and updates as things change. MeshCentral uses websockets to connect to the server and get real-time events.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>Single Programming Language –</strong><blockquote>
|
||
<p>MeshCentral1 used JavaScript on the browser, C# on the server and C for the agent. Use of 3 different programming languages means that developers wanting to implement a new use-case needs to have sufficient skills to change between these 3 languages during the coding session. Makes the code significantly more difficult to understand and maintain.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>Support for LAN only Mode –</strong><blockquote>
|
||
<p>MeshCentral is capable of being setup as “LAN only” mode. In fact, this is the default mode when no static name or IP address is provided. In this mode, MeshAgents perform a multicast search on the network for the server making a static DNS/IP unnecessary.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>Support for TLS Offloaders –</strong><blockquote>
|
||
<p>TLS offloaders are now fully supported. This means that MeshCentral can handle way more network connections and traffic significantly.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>Support for CIRA User/Pass Login –</strong><blockquote>
|
||
<p>MeshCentral now supports both Intel AMT CIRA user/pass login and certificate login. Compared to MeshCentral1 that only supported certificate login, user/pass login is easier to setup and it can also be used for TLS offloaders and CIRA authentication. </p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>No Live State Stored in the Database –</strong><blockquote>
|
||
<p>One if the big problems with MeshCentral1 is that a lot of the live states (Agent, User and AMT connections and disconnections) needed to be stored in the database. This caused a few problems, first the extra load on the database that was un-necessary, but also that servers did not have real-time state information about other servers (they had to query the database). This resulted in more load on the database and scaling issues. In MeshCentral, all live states are kept in the RAM which boosts performance significantly.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>Agentless Intel AMT Support –</strong><blockquote>
|
||
<p>With MeshCentral1, administrators have to install the MeshAgent software on all computers, even if it was only for used for Intel AMT. MeshCentral supports a new agent-less mesh type that allows administrators to just setup the server strictly for Intel AMT only.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>Latest Security & Crypto algorithms –</strong><blockquote>
|
||
<p>MeshCentral uses all the latest cryptographic algorithm, notably SHA384 and RSA3072 making it more resistant to future quantum computer attacks. This would be very difficult to retrofit into MeshCentralv1 since it would require change of database schema and 1000’s of line of code thus making the server incompatible with the current version version, making migration difficult.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>Support for Email Verification and Password Recovery –</strong><blockquote>
|
||
<p>MeshCentral can be configured with an SMTP server to send out e-mail confirmation messages and password recovery message. This is an important feature that was missing in MeshCentral1.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li><strong>MeshInterceptor Support –</strong><blockquote>
|
||
<p>MeshCentral can insert HTTP and Intel AMT redirection credential into a live data stream. This is useful to allow an administrator to securely pass Intel AMT password and control over an Intel AMT computer via web browser without the additional administrator login UI.</p>
|
||
</blockquote>
|
||
</li>
|
||
</ul>
|
||
<p>It’s possible to perform migration to MeshCentral from MeshCentral1 server using a migration package. The MeshCentral Migration Tool will convert your existing user database into a format that can be imported into MeshCentral.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-57-06.jpg" /></p>
|
||
<p>In addition to the migration tool, MeshCentral has a special module that will update all MeshAgents from v1 to v2 so the transition should be simple.</p>
|
||
<h2 id="meshcentral-additional-resources">💡 Additional Resources</h2>
|
||
<p>In addition to this document, there are a growing set of MeshCentral tutorial videos available on YouTube which covers all of the basic at <a href="https://www.meshcommander.com/meshcentral2/tutorials">www.meshcommander.com/meshcentral2/tutorials</a>
|
||
. The tutorial includes videos on how to perform server installation using both the Windows MSI installer and NPM methods.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-57-28.jpg" /></p>
|
||
<h2 id="meshcentral-conclusion">🏁 Conclusion</h2>
|
||
<p>MeshCentral is a free, open source and powerful remote management solution that is cross-platform. In this document, we have covered in detail on how to install and configure MeshCentral server to meet specific environment and use-case. MeshCentral works in many environments and situations. MeshCentral is not only simple to install but also takes minimal resources to host which makes it a very good remote management solution. As with any good software, MeshCentral will continue to be updated and evolve.</p>
|
||
<h2 id="meshcentral-license">License</h2>
|
||
<p>MeshCentral and this document are both opens source and licensed using Apache 2.0, the full license can be found at <a href="https://www.apache.org/licenses/LICENSE-2.0">https://www.apache.org/licenses/LICENSE-2.0</a>.</p>
|
||
<h2 id="meshcentral-annex-1-sample-configuration-file">Annex 1: Sample Configuration File</h2>
|
||
<p>In this annex, we present a complete sample config.json file. You would put this file in the “meshcentral-data” folder that is created when MeshCentral is first run. The config.json is completely optional and the server will run with default values with it. All key names in this file are case insensitive.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"MongoDb"</span><span class="p">:</span><span class="w"> </span><span class="s2">"mongodb://127.0.0.1:27017/meshcentral"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"MongoDbCol"</span><span class="p">:</span><span class="w"> </span><span class="s2">"meshcentral"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">4430</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"AliasPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"RedirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">800</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"TlsOffload"</span><span class="p">:</span><span class="w"> </span><span class="s2">"127.0.0.1"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"MpsPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">44330</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"MpsAliasPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">4433</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"MpsTlsOffload"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"SessionTime"</span><span class="p">:</span><span class="w"> </span><span class="mi">30</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"SessionKey"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MyReallySecretPassword"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"AllowLoginToken"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"AllowFraming"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"WebRTC"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"ClickOnce"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MyServer"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Title2"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Servername"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"TitlePicture"</span><span class="p">:</span><span class="w"> </span><span class="s2">"title-sample.png"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"UserQuota"</span><span class="p">:</span><span class="w"> </span><span class="mi">1048576</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"MeshQuota"</span><span class="p">:</span><span class="w"> </span><span class="mi">248576</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"NewAccounts"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Footer"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<a href='https://twitter.com/mytwitter'>Twitter</a>"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"PasswordRequirements"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"min"</span><span class="p">:</span><span class="w"> </span><span class="mi">8</span><span class="p">,</span><span class="w"> </span><span class="nt">"max"</span><span class="p">:</span><span class="w"> </span><span class="mi">128</span><span class="p">,</span><span class="w"> </span><span class="nt">"upper"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="nt">"lower"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="nt">"numeric"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="nt">"nonalpha"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"customer1"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Dns"</span><span class="p">:</span><span class="w"> </span><span class="s2">"customer1.myserver.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Customer1"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Title2"</span><span class="p">:</span><span class="w"> </span><span class="s2">"TestServer"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"NewAccounts"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Auth"</span><span class="p">:</span><span class="w"> </span><span class="s2">"sspi"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Footer"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Test"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"info"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"share"</span><span class="p">:</span><span class="w"> </span><span class="s2">"C:\\ExtraWebSite"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"letsencrypt"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"email"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myemail@myserver.com "</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"names"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myserver.com,customer1.myserver.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"rsaKeySize"</span><span class="p">:</span><span class="w"> </span><span class="mi">3072</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"production"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"peers"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"serverId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"server1"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"servers"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"server1"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"wss://192.168.2.133:443/"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"server2"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"wss://192.168.1.106:443/"</span><span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"smtp"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"host"</span><span class="p">:</span><span class="w"> </span><span class="s2">"smtp.myserver.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="mi">25</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"from"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myemail@myserver.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"tls"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>All these values are examples only, this config.json should just be used as an example and none of the values here are real.</p>
|
||
<h2 id="meshcentral-annex-2-tips-tricks">Annex 2: Tips & Tricks</h2>
|
||
<p>In this annex, we present various suggestions. These are often found by users on the GitHub community and readers are encouraged to participate. The GitHub community is at: <a href="https://github.com/Ylianst/MeshCentral/issues">https://github.com/Ylianst/MeshCentral/issues</a></p>
|
||
<h3 id="meshcentral-remote-terminal">Remote Terminal</h3>
|
||
<p>When doing a remote terminal session to a Linux computer, it may be interesting to run the bash shell under a different user. One would typically use the command:</p>
|
||
<div class="highlight"><pre><span></span><code>su<span class="w"> </span>-s<span class="w"> </span>/bin/bash<span class="w"> </span>myOtherUser
|
||
</code></pre></div>
|
||
<p>However, because bash is not run in interactive mode, the command line prompt may be empty and history keys (up and down), tab and backspace will not work right. The correct command is:</p>
|
||
<div class="highlight"><pre><span></span><code>su<span class="w"> </span>-c<span class="w"> </span><span class="s1">'/bin/bash -i'</span><span class="w"> </span>myOtherUser
|
||
</code></pre></div>
|
||
<p>This will run bash in interactive mode and work correctly.</p>
|
||
<h4 id="meshcentral-ssh-and-sftp-integration-to-the-terminal">SSH and SFTP integration to the Terminal</h4>
|
||
<p>MeshCentral has built-in web-based integration of SSH in the "Terminal" tab and SFTP in the "Files" tab.</p>
|
||
<div class="video-wrapper">
|
||
<iframe src="https://www.youtube.com/embed/7qAbl2OuZEU" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<h2 id="meshcentral-pdf-and-odt-handouts">PDF and ODT handout(s).</h2>
|
||
<p><a href="https://meshcentral.com/docs/MeshCentral2UserGuide.pdf">MeshCentral Guide</a></p>
|
||
<p>MeshCmd Guide <a href="https://meshcentral.com/docs/MeshCmdUserGuide.pdf">as .pdf</a> <a href="../documents/MeshCentral%20User%27s%20Guide%20v0.2.9.odt">as .odt</a></p></section><section class="print-page" id="meshcentral-config" heading-number="3.2"><h1 id="meshcentral-config-configuration-options">Configuration Options</h1>
|
||
<p>There are MANY configuration options available with meshcentral, search this file for options: <a href="https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json">https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json</a></p>
|
||
<p>Some options you can find relate to:</p>
|
||
<ul>
|
||
<li>DNS</li>
|
||
<li>HTTPS</li>
|
||
<li>MPS (Management Presence Server)</li>
|
||
<li>MongoDB</li>
|
||
<li>MariaDB</li>
|
||
<li>SQLite3</li>
|
||
<li>MySQL</li>
|
||
<li>PostgreSQL</li>
|
||
<li>AceBase</li>
|
||
<li>WAN (Wide Area Network)</li>
|
||
<li>LAN (Local Area Network)</li>
|
||
<li>Maintenance Mode</li>
|
||
<li>Session Cookie</li>
|
||
<li>Database Encryption</li>
|
||
<li>Web Relay</li>
|
||
<li>Agent Connection</li>
|
||
<li>TLS (Transport Layer Security)</li>
|
||
<li>WebRTC</li>
|
||
<li>Web Push Notifications</li>
|
||
<li>Auto Backup</li>
|
||
<li>Crowdsec</li>
|
||
<li>IP KVM (Keyboard, Video, Mouse over IP)</li>
|
||
<li>Mesh Router</li>
|
||
<li>Syslog</li>
|
||
<li>WebDAV</li>
|
||
<li>Certificates and Authentication</li>
|
||
<li>MeshCentral Server Settings</li>
|
||
<li>Device Management</li>
|
||
<li>User Permissions</li>
|
||
<li>Remote Desktop Configuration</li>
|
||
</ul>
|
||
<p>and more!</p>
|
||
<p><img alt="Server Options" src="../meshcentral/images/2023-11-29_140845%20-%20mesh%20json1.jpg" /></p>
|
||
<p><img alt="Domain Options" src="../meshcentral/images/2023-11-29_140845%20-%20mesh%20json2.jpg" /></p></section><section class="print-page" id="meshcentral-sslnletsencrypt" heading-number="3.3"><h1 id="meshcentral-sslnletsencrypt-sslletsencrypt">SSL/Letsencrypt</h1>
|
||
<h2 id="meshcentral-sslnletsencrypt-meshcentral-supports-ssl-using-self-generated-certs-your-own-certs-or-letsencrypt">MeshCentral supports SSL using self generated certs, your own certs or Letsencrypt</h2>
|
||
<h3 id="meshcentral-sslnletsencrypt-enabling-letsencrypt">Enabling letsencrypt</h3>
|
||
<p>Make sure you match and/or adjust all the following settings appropriately in your config.json file:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"redirPort"</span>
|
||
<span class="w"> </span><span class="nt">"cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"yourdomain.com"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"letsencrypt"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"__comment__"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Requires NodeJS 8.x or better, Go to https://letsdebug.net/ first before trying Let's Encrypt."</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"email"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myemail@myserver.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"names"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myserver.com,customer1.myserver.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"skipChallengeVerification"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"production"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>If you need further clarification to know what each of these settings are, check out <a href="https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json">the config schema</a>.</p>
|
||
<p>Then restart meshcentral and it will get a cert for you, the process will need to restart to apply the cert.</p>
|
||
<h3 id="meshcentral-sslnletsencrypt-useful-resourcestroubleshooting">Useful resources/troubleshooting</h3>
|
||
<p>To check letsencrypt is working properly please use https://letsdebug.net/. We are using the <a href="https://letsencrypt.org/docs/challenge-types/#http-01-challenge">HTTP-O1 challenge</a> method with these instructions.</p>
|
||
<p>Also make sure you have port 80 open and pointing to your meshcentral server, <strong>IT WILL NOT WORK</strong> if port 80 isn't open and it <strong>HAS</strong> to be port 80.</p>
|
||
<p>You can read more about Letsencrypt and meshcentral <a href="https://ylianst.github.io/MeshCentral/meshcentral/#lets-encrypt-support">here</a>. </p></section><section class="print-page" id="meshcentral-agents" heading-number="3.4"><h1 id="meshcentral-agents-mesh-agents">Mesh Agents</h1>
|
||
<h2 id="meshcentral-agents-windows">Windows</h2>
|
||
<p>Default Install Path: <code>c:\Program Files\Mesh Agent</code></p>
|
||
<p>Application Path: <code>c:\Program Files\Mesh Agent\meshagent.exe</code></p>
|
||
<p>Application database Path: <code>c:\Program Files\Mesh Agent\meshagent.db</code></p>
|
||
<p>Application Log Path: <code>c:\Program Files\Mesh Agent\meshagent.log</code></p>
|
||
<p>xxx Path: <code>c:\Program Files\Mesh Agent\meshagent.msh</code></p>
|
||
<div class="tabbed-set tabbed-alternate" data-tabs="1:2"><input checked="checked" id="meshcentral-agents-__tabbed_1_1" name="meshcentral-agents-__tabbed_1" type="radio" /><input id="meshcentral-agents-__tabbed_1_2" name="meshcentral-agents-__tabbed_1" type="radio" /><div class="tabbed-labels"><label for="meshcentral-agents-__tabbed_1_1"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 19v-3h8v3zm-4.5-6L2.47 7h4.24l4.96 4.95c.58.59.58 1.55 0 2.12L6.74 19H2.5z"/></svg></span> Status</label><label for="meshcentral-agents-__tabbed_1_2"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 19v-3h8v3zm-4.5-6L2.47 7h4.24l4.96 4.95c.58.59.58 1.55 0 2.12L6.74 19H2.5z"/></svg></span> Troubleshooting</label></div>
|
||
<div class="tabbed-content">
|
||
<div class="tabbed-block">
|
||
<ul>
|
||
<li>Start: <code>net start "mesh agent"</code></li>
|
||
<li>Stop: <code>net stop "mesh agent"</code></li>
|
||
<li>Restart: <code>net restart "mesh agent"</code></li>
|
||
<li>Status: Needs info</li>
|
||
</ul>
|
||
</div>
|
||
<div class="tabbed-block">
|
||
<p>Troubleshooting steps: Needs info</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<h2 id="meshcentral-agents-linux-bsd">Linux / BSD</h2>
|
||
<p>Uninstall: <code>sudo /usr/local/mesh_services/meshagent/[agent-name]/meshagent -fulluninstall</code></p>
|
||
<h2 id="meshcentral-agents-apple-macos-binary-installer">Apple macOS Binary Installer</h2>
|
||
<p>Default Install Path: <code>/usr/local/mesh_services/meshagent/meshagent</code></p>
|
||
<p>Launches from <code>/Library/LaunchAgents/meshagent.plist</code></p>
|
||
<p>Controlling agent</p>
|
||
<div class="highlight"><pre><span></span><code>launchctl<span class="w"> </span>stop<span class="w"> </span>meshagent
|
||
launchctl<span class="w"> </span>start<span class="w"> </span>meshagent
|
||
</code></pre></div>
|
||
<p>Install: </p>
|
||
<p>Uninstall: <code>sudo /usr/local/mesh_services/meshagent/[agent-name]/meshagent -fulluninstall</code></p>
|
||
<h2 id="meshcentral-agents-apple-macos-universal">Apple macOS Universal</h2>
|
||
<p>For OSx 11+ including Big Sur, Monterey and later</p>
|
||
<h2 id="meshcentral-agents-apple-macos">Apple macOS</h2>
|
||
<p>For macOS 10.x including Catalina, Mojave, High Sierra, Sierra, El Capitan, Yosemite, Mavericks, Mountain Lion and earlier.</p>
|
||
<h2 id="meshcentral-agents-mobile-device-android">Mobile Device (Android)</h2>
|
||
<h2 id="meshcentral-agents-meshcentral-assistant">MeshCentral Assistant</h2>
|
||
<p>See <a href="#meshcentral-assistant">Assistant</a></p>
|
||
<h2 id="meshcentral-agents-apple-macos-binary-installer_1">Apple MacOS Binary Installer</h2>
|
||
<h2 id="meshcentral-agents-agent-commands">Agent Commands</h2>
|
||
<p><strong>agentmsg</strong>
|
||
: Add/Remove badged messages to the device's web ui
|
||
<div class="highlight"><pre><span></span><code> agentmsg add "[message]" [iconIndex]
|
||
agentmsg remove [index]
|
||
agentmsg list
|
||
</code></pre></div>
|
||
<strong>agentsize</strong>
|
||
: Returns the binary size of the agent</p>
|
||
<p><strong>agentupdate</strong>
|
||
: Manually trigger an agent self-update</p>
|
||
<p><strong>alert</strong>
|
||
: Display an alert dialog on the logged in session
|
||
<div class="highlight"><pre><span></span><code>alert TITLE, CAPTION [, TIMEOUT]
|
||
</code></pre></div></p>
|
||
<p><strong>amt</strong></p>
|
||
<p><strong>amtconfig</strong></p>
|
||
<p><strong>amtevents</strong></p>
|
||
<p><strong>apf</strong></p>
|
||
<p><strong>args</strong></p>
|
||
<p><strong>av</strong>
|
||
: Displays Antivirus State</p>
|
||
<p><strong>coredump</strong></p>
|
||
<p><strong>coreinfo</strong></p>
|
||
<p><strong>cpuinfo</strong></p>
|
||
<p><strong>cs</strong>
|
||
: Display Windows Connected Standby State</p>
|
||
<p><strong>dbcompact</strong>
|
||
: Compacts the agent database</p>
|
||
<p><strong>dbget</strong></p>
|
||
<p><strong>dbkeys</strong></p>
|
||
<p><strong>dbset</strong></p>
|
||
<p><strong>dnsinfo</strong>
|
||
: Display DNS server info</p>
|
||
<p><strong>domain</strong>
|
||
: Display domain metadata</p>
|
||
<p><strong>errorlog</strong></p>
|
||
<p><strong>eval</strong>
|
||
: executes javascript on the agent
|
||
<div class="highlight"><pre><span></span><code>eval [code]
|
||
</code></pre></div></p>
|
||
<p><strong>fdcount</strong>
|
||
: Returns the number of active descriptors in the event loop</p>
|
||
<p><strong>fdsnapshot</strong>
|
||
: Returns detailed descriptor/handle/timer metadata</p>
|
||
<p><strong>getclip</strong>
|
||
: Fetches clipboard data from agent</p>
|
||
<p><strong>getscript</strong></p>
|
||
<p><strong>help</strong>
|
||
: Returns the list of supported console commands</p>
|
||
<p><strong>httpget</strong></p>
|
||
<p><strong>info</strong>
|
||
: Returns general information about the agent, such as connected state, loaded modules, LMS state, etc</p>
|
||
<p><strong>kill</strong>
|
||
: Sends a SIGKILL signal to the specified PID
|
||
<div class="highlight"><pre><span></span><code>kill [pid]
|
||
</code></pre></div></p>
|
||
<p><strong>kvmmode</strong>
|
||
: Displays the KVM Message Format</p>
|
||
<p><strong>location</strong>
|
||
: Displays saves location information about the connected agent</p>
|
||
<p><strong>lock</strong></p>
|
||
<p><strong>log</strong>
|
||
: Writes a message to the logfile
|
||
<div class="highlight"><pre><span></span><code>log [message]
|
||
</code></pre></div></p>
|
||
<p><strong>ls</strong>
|
||
: Enumerates the files in the agent's install folder</p>
|
||
<p><strong>mousetrails</strong>
|
||
: Enables/Disables Mouse Trails Accessibility on Windows. To change setting, specify a positive integer representing the number of latent cursors, where 0 is disable
|
||
<div class="highlight"><pre><span></span><code>mousetrails [n]
|
||
</code></pre></div></p>
|
||
<p><strong>msh</strong>
|
||
: Displays the loaded msh settings file</p>
|
||
<p><strong>netinfo</strong>
|
||
: Displays network interface information</p>
|
||
<p><strong>notify</strong>
|
||
: Display a notification on the web interface</p>
|
||
<p><strong>openurl</strong></p>
|
||
<p><strong>osinfo</strong>
|
||
: Displays OS information</p>
|
||
<p><strong>parseuri</strong>
|
||
: Parses the specified URI, and displays the parsed output
|
||
<div class="highlight"><pre><span></span><code>parseuri [uri]
|
||
</code></pre></div></p>
|
||
<p><strong>plugin</strong>
|
||
: Invokes a plugin
|
||
<div class="highlight"><pre><span></span><code>plugin [pluginName] [args]
|
||
</code></pre></div></p>
|
||
<p><strong>power</strong>
|
||
: Performs the specified power action
|
||
<div class="highlight"><pre><span></span><code>power [action]
|
||
LOGOFF = 1
|
||
SHUTDOWN = 2
|
||
REBOOT = 3
|
||
SLEEP = 4
|
||
HIBERNATE = 5
|
||
DISPLAYON = 6
|
||
KEEPAWAKE = 7
|
||
BEEP = 8
|
||
CTRLALTDEL = 9
|
||
VIBRATE = 13
|
||
FLASH = 14
|
||
</code></pre></div></p>
|
||
<p><strong>print</strong></p>
|
||
<p><strong>privacybar</strong>
|
||
: Sets/Gets the default pinned state of the Privacy Bar on windows
|
||
<div class="highlight"><pre><span></span><code>privacybar [PINNED|UNPINNED]
|
||
</code></pre></div></p>
|
||
<p><strong>ps</strong>
|
||
: Enumerates processes on the agent</p>
|
||
<p><strong>rawsmbios</strong>
|
||
: Fetches the raw smbios table</p>
|
||
<p><strong>safemode</strong>
|
||
: Sets/Gets the SAFEMODE configuration of the agent, as well as the next boot state.
|
||
<div class="highlight"><pre><span></span><code>safemode (ON|OFF|STATUS)
|
||
</code></pre></div></p>
|
||
<p><strong>scanwifi</strong>
|
||
: Scans the available Wifi access points, and displays the SSID and Signal Strength</p>
|
||
<p><strong>service</strong>
|
||
: Shortcut to be able to restart the agent service
|
||
<div class="highlight"><pre><span></span><code>service status|restart
|
||
</code></pre></div></p>
|
||
<p><strong>setclip</strong>
|
||
: Sets clipboard data to the agent
|
||
<div class="highlight"><pre><span></span><code>setclip [text]
|
||
</code></pre></div></p>
|
||
<p><strong>setdebug</strong>
|
||
: Sets the location target for debug messages
|
||
<div class="highlight"><pre><span></span><code>setdebug [target]
|
||
0 = Disabled
|
||
1 = StdOut
|
||
2 = This Console
|
||
* = All Consoles
|
||
4 = WebLog
|
||
8 = Logfile
|
||
</code></pre></div></p>
|
||
<p><strong>smbios</strong>
|
||
: Displays the parsed SMBIOS metadata</p>
|
||
<p><strong>startupoptions</strong>
|
||
: Displays the command-line options that the agent was started with</p>
|
||
<p><strong>sysinfo</strong>
|
||
: Collects and displays telemetry on the platform</p>
|
||
<p><strong>task</strong></p>
|
||
<p><strong>taskbar</strong>
|
||
: Hides or shows the Windows System task bar, optionally on the specified Terminal Server Session ID
|
||
<div class="highlight"><pre><span></span><code>taskbar HIDE|SHOW [TSID]
|
||
</code></pre></div></p>
|
||
<p><strong>timerinfo</strong>
|
||
: Displays metadata about any configured timers on the event loop</p>
|
||
<p><strong>toast</strong>
|
||
: Displays a toast message on the logged in user's session
|
||
<div class="highlight"><pre><span></span><code>toast [message]
|
||
</code></pre></div></p>
|
||
<p><strong>translations</strong>
|
||
: Shows the currently configured translations</p>
|
||
<p><strong>type</strong>
|
||
<div class="highlight"><pre><span></span><code>type (filepath) [maxlength]
|
||
</code></pre></div></p>
|
||
<p><strong>uac</strong>
|
||
: Get/Sets the Windows UAC mode
|
||
<div class="highlight"><pre><span></span><code>uac [get|interactive|secure]
|
||
</code></pre></div></p>
|
||
<p><strong>unzip</strong>
|
||
<div class="highlight"><pre><span></span><code>unzip input, destination
|
||
</code></pre></div>
|
||
: Unzips the specified file</p>
|
||
<p><strong>users</strong>
|
||
: Enumerates the logged in users on the system</p>
|
||
<p><strong>versions</strong>
|
||
: Displays version information about the agent</p>
|
||
<p><strong>vm</strong>
|
||
: Detects if the system is a Virtual Machine</p>
|
||
<p><strong>volumes</strong>
|
||
: Displays volume information reported by the OS</p>
|
||
<p><strong>wakeonlan</strong>
|
||
: Sends wake-on-lan packets to the specified MAC address
|
||
<div class="highlight"><pre><span></span><code>wakeonlan [mac]
|
||
</code></pre></div></p>
|
||
<p><strong>wallpaper</strong>
|
||
: Gets/Toggles the logged in user's desktop background image
|
||
<div class="highlight"><pre><span></span><code>wallpaper (GET|TOGGLE)
|
||
</code></pre></div></p>
|
||
<p><strong>wpfhwacceleration</strong>
|
||
: Enable/Disable WPF HW Acceleration on Windows
|
||
<div class="highlight"><pre><span></span><code>wpfhwacceleration (ON|OFF|STATUS)
|
||
</code></pre></div></p>
|
||
<p><strong>wsclose</strong></p>
|
||
<p><strong>wsconnect</strong></p>
|
||
<p><strong>wslist</strong></p>
|
||
<p><strong>wssend</strong></p>
|
||
<p><strong>zip</strong>
|
||
<div class="highlight"><pre><span></span><code>zip (output file name), input1 [, input n]
|
||
</code></pre></div></p>
|
||
<h2 id="meshcentral-agents-agent-msh-options">Agent msh options</h2>
|
||
<p>You can find a full list of options for the agent <a href="https://github.com/Ylianst/MeshAgent?tab=readme-ov-file#msh-format">here</a></p>
|
||
<p><code>skipmaccheck=1</code>: Will not regenerate the agents nodeid and cause duplication of the agent when the MAC address changes.</p>
|
||
<p>You can add options to your .msh on agent install with <a href="https://github.com/Ylianst/MeshCentral/blob/15ff7d12a1e4e5d78936b473ea207b7e02b8ff26/meshcentral-config-schema.json#L2504">this</a></p></section><section class="print-page" id="meshcentral-assistant" heading-number="3.5"><h1 id="meshcentral-assistant-meshcentral-assistant">MeshCentral Assistant</h1>
|
||
<h2 id="meshcentral-assistant-initial-setup">Initial Setup</h2>
|
||
<h2 id="meshcentral-assistant-agent-invite-code">Agent Invite Code</h2>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"agentInviteCodes"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p><img alt="agent invite code" src="../meshcentral/images/assistant_agent_code.jpg" /></p>
|
||
<h2 id="meshcentral-assistant-agent-invitation">Agent Invitation</h2>
|
||
<p>Click on the 'Invite' button next to the device group name to access it. </p>
|
||
<h3 id="meshcentral-assistant-link-invitation">Link Invitation</h3>
|
||
<p>For link invitation web page customization:</p>
|
||
<ol>
|
||
<li>Alongside <code>meshcentral-data</code> create a folder called <code>meshcentral-web</code></li>
|
||
<li>Create a <code>views</code> folder in it and copy the file <code>node_modules/meshcentral/views/invite.handlebars</code> into it.</li>
|
||
<li>That copy will be served instead of the default one, so you can customize it as you want.</li>
|
||
</ol>
|
||
<p><img alt="agent invite code" src="../meshcentral/images/assistant_invitation_link.jpg" /></p>
|
||
<h3 id="meshcentral-assistant-email-invitation">Email Invitation</h3>
|
||
<p>This option will show up if you have an SMTP email server set up with MeshCentral. </p>
|
||
<p>For invitation email customization: </p>
|
||
<ol>
|
||
<li>Alongside <code>meshcentral-data</code> create a folder called <code>meshcentral-web</code></li>
|
||
<li>Create an <code>emails</code> folder in it and copy the files <code>node_modules/meshcentral/emails/mesh-invite.txt</code> and <code>node_modules/meshcentral/emails/mesh-invite.html</code> into it.</li>
|
||
<li>These copies will be used instead of the default ones, so you can customize them as you want.</li>
|
||
</ol>
|
||
<p><img alt="email-invitation" src="../meshcentral/images/email-invitation.jpg" /></p>
|
||
<h2 id="meshcentral-assistant-email-notification">Email notification</h2>
|
||
<p>You can also get an email notification when someone clicks the "Request Help" button in the Assistant agent.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-09-06-16-38-57.jpg" /></p></section><section class="print-page" id="meshcentral-codesigning" heading-number="3.6"><h1 id="meshcentral-codesigning-code-signing">Code Signing</h1>
|
||
<h2 id="meshcentral-codesigning-authenticode-js-video">Authenticode-JS Video</h2>
|
||
<p>Nodejs Code Signing module</p>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/xteKscs_Jgo" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<p>MeshCentral comes with authenticode.js, you can run it like this:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>node_modules/meshcentral/authenticode-js
|
||
</code></pre></div>
|
||
<p>and you will get</p>
|
||
<div class="highlight"><pre><span></span><code>MeshCentral Authenticode Tool.
|
||
Usage:
|
||
node authenticode.js [command] [options]
|
||
Commands:
|
||
info: Show information about an executable.
|
||
--exe [file] Required executable to view information.
|
||
--json Show information in JSON format.
|
||
sign: Sign an executable.
|
||
--exe [file] Required executable to sign.
|
||
--out [file] Resulting signed executable.
|
||
--pem [pemfile] Certificate & private key to sign the executable with.
|
||
--desc [description] Description string to embbed into signature.
|
||
--url [url] URL to embbed into signature.
|
||
--hash [method] Default is SHA384, possible value: MD5, SHA224, SHA256, SHA384 or SHA512.
|
||
--time [url] The time signing server URL.
|
||
--proxy [url] The HTTP proxy to use to contact the time signing server, must start with http://
|
||
unsign: Remove the signature from the executable.
|
||
--exe [file] Required executable to un-sign.
|
||
--out [file] Resulting executable with signature removed.
|
||
createcert: Create a code signging self-signed certificate and key.
|
||
--out [pemfile] Required certificate file to create.
|
||
--cn [value] Required certificate common name.
|
||
--country [value] Certificate country name.
|
||
--state [value] Certificate state name.
|
||
--locality [value] Certificate locality name.
|
||
--org [value] Certificate organization name.
|
||
--ou [value] Certificate organization unit name.
|
||
--serial [value] Certificate serial number.
|
||
timestamp: Add a signed timestamp to an already signed executable.
|
||
--exe [file] Required executable to sign.
|
||
--out [file] Resulting signed executable.
|
||
--time [url] The time signing server URL.
|
||
--proxy [url] The HTTP proxy to use to contact the time signing server, must start with http://
|
||
icons: Show the icon resources in the executable.
|
||
--exe [file] Input executable.
|
||
saveicons: Save an icon group to a .ico file.
|
||
--exe [file] Input executable.
|
||
--out [file] Resulting .ico file.
|
||
--icongroup [groupNumber] Icon groupnumber to save to file.
|
||
--removeicongroup [number]
|
||
--icon [groupNumber],[filename.ico]
|
||
|
||
Note that certificate PEM files must first have the signing certificate,
|
||
followed by all certificates that form the trust chain.
|
||
|
||
When doing sign/unsign, you can also change resource properties of the generated file.
|
||
|
||
--filedescription [value]
|
||
--fileversion [value]
|
||
--internalname [value]
|
||
--legalcopyright [value]
|
||
--originalfilename [value]
|
||
--productname [value]
|
||
--productversion [value]
|
||
</code></pre></div>
|
||
<h2 id="meshcentral-codesigning-automatic-agent-code-signing">Automatic Agent Code Signing</h2>
|
||
<p>If you want to self-sign the mesh agent so you can whitelist the software in your AV, as well as lock it to your server and organization:</p>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/qMAestNgCwc" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>If you generate your private key on windows with use <code>BEGIN PRIVATE KEY</code> and openssl needs <code>BEGIN RSA PRIVATE KEY</code> you can convert your private key to rsa private key using <code>openssl rsa -in server.key -out server_new.key</code></p>
|
||
</div>
|
||
<h2 id="meshcentral-codesigning-setting-agent-file-info">Setting Agent File info</h2>
|
||
<p>Now that MeshCentral customizes and signs the agent, you can set that value to anything you like.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"agentFileInfo"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"filedescription"</span><span class="p">:</span><span class="w"> </span><span class="s2">"sample_filedescription"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"fileversion"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0.1.2.3"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"internalname"</span><span class="p">:</span><span class="w"> </span><span class="s2">"sample_internalname"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"legalcopyright"</span><span class="p">:</span><span class="w"> </span><span class="s2">"sample_legalcopyright"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"originalfilename"</span><span class="p">:</span><span class="w"> </span><span class="s2">"sample_originalfilename"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"productname"</span><span class="p">:</span><span class="w"> </span><span class="s2">"sample_productname"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"productversion"</span><span class="p">:</span><span class="w"> </span><span class="s2">"v0.1.2.3"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<h2 id="meshcentral-codesigning-external-signing-job">External Signing Job</h2>
|
||
<p>The externalsignjob feature allows you to perform additional operations on the agent after MeshCentral completes its code signing process. This is particularly useful for:</p>
|
||
<ol>
|
||
<li>Using hardware security tokens for signing</li>
|
||
<li>Performing signing on a separate server or cloud host</li>
|
||
<li>Archiving signed agents</li>
|
||
<li>Adding additional security measures</li>
|
||
</ol>
|
||
<p>The externalsignjob is called after MeshCentral completes its entire code signing process, including:
|
||
- Resource modification
|
||
- Digital signature application
|
||
- Timestamp application (if configured)</p>
|
||
<p>To use this feature, add the following to your config.json:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"externalsignjob"</span><span class="p">:</span><span class="w"> </span><span class="s2">"path/to/your/script.bat"</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>The script will receive the path to the agent as its first argument. Here are example scripts:</p>
|
||
<h3 id="meshcentral-codesigning-batch-file-example">Batch File Example</h3>
|
||
<div class="highlight"><pre><span></span><code><span class="p">@</span><span class="k">echo</span> off
|
||
<span class="k">Echo</span> External Signing Job
|
||
signtool sign /tr http://timestamp.sectigo.com /td SHA256 /fd SHA256 /a /v /f path/to/your/signing.cer /csp <span class="s2">"eToken Base Cryptographic Provider"</span> /k <span class="s2">"[{{MyPassword}}]=PrivateKeyContainerName"</span> <span class="s2">"</span><span class="nv">%~1</span><span class="s2">"</span>
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-codesigning-powershell-example">PowerShell Example</h3>
|
||
<div class="highlight"><pre><span></span><code><span class="nv">$file</span> <span class="p">=</span> <span class="nv">$args</span><span class="p">[</span><span class="n">0</span><span class="p">]</span>
|
||
<span class="n">signtool</span> <span class="n">sign</span> <span class="p">/</span><span class="n">tr</span> <span class="n">http</span><span class="p">://</span><span class="n">timestamp</span><span class="p">.</span><span class="n">sectigo</span><span class="p">.</span><span class="n">com</span> <span class="p">/</span><span class="n">td</span> <span class="n">SHA256</span> <span class="p">/</span><span class="n">fd</span> <span class="n">SHA256</span> <span class="p">/</span><span class="n">a</span> <span class="p">/</span><span class="n">v</span> <span class="p">/</span><span class="n">f</span> <span class="n">path</span><span class="p">/</span><span class="n">to</span><span class="p">/</span><span class="n">your</span><span class="p">/</span><span class="n">signing</span><span class="p">.</span><span class="n">cer</span> <span class="p">/</span><span class="n">csp</span> <span class="s2">"eToken Base Cryptographic Provider"</span> <span class="p">/</span><span class="n">k</span> <span class="s2">"[{{MyPassword}}]=PrivateKeyContainerName"</span> <span class="nv">$file</span>
|
||
</code></pre></div>
|
||
<p>The externalsignjob can be used for more than just signing. For example, you could:</p>
|
||
<ol>
|
||
<li>Archive signed agents to a secure location</li>
|
||
<li>Upload signed agents to a distribution server</li>
|
||
<li>Perform additional security checks</li>
|
||
<li>Add custom metadata or watermarks</li>
|
||
<li>Integrate with your organization's build pipeline</li>
|
||
</ol>
|
||
<p>Note: The script must return a success exit code (0) for the process to be considered successful. Any non-zero exit code will be treated as a failure and will be logged.</p></section><section class="print-page" id="meshcentral-debugging" heading-number="3.7"><h1 id="meshcentral-debugging-debugging">Debugging</h1>
|
||
<h2 id="meshcentral-debugging-websockets-video">Websockets Video</h2>
|
||
<p>Make sure you understand how MeshCentral works with your browser using chrome developer tools.</p>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/3vI4URd3VzU" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<h2 id="meshcentral-debugging-meshcentral-server">MeshCentral Server</h2>
|
||
<h3 id="meshcentral-debugging-useful-configjs-settings">Useful config.js settings</h3>
|
||
<p><a href="https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json">https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json</a></p>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"AgentsInRAM"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||
<span class="nt">"AgentUpdateBlockSize"</span><span class="p">:</span><span class="w"> </span><span class="mi">2048</span><span class="p">,</span>
|
||
<span class="nt">"agentUpdateSystem"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
|
||
<span class="nt">"noAgentUpdate"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
|
||
<span class="nt">"WsCompression"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||
<span class="nt">"AgentWsCompression"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-debugging-understanding-node-and-paths">Understanding node and paths</h3>
|
||
<p>Note that when running MeshCentral, you should always run from the path that is parent to node_modules, so you do this:</p>
|
||
<div class="highlight"><pre><span></span><code>cd C:\Program Files\Open Source\MeshCentral
|
||
node node_modules\meshcentral
|
||
</code></pre></div>
|
||
<p>You do NOT do this:</p>
|
||
<div class="highlight"><pre><span></span><code>cd C:\Program Files\Open Source\MeshCentral\node_modules\meshcentral
|
||
node meshcentral
|
||
</code></pre></div>
|
||
<p>The problem with the second command is that NPM may install missing modules in the incorrect location.</p>
|
||
<p>Also, in general I recommend not using the MeshCentral MSI Installer and just install manually unless you are very scared of the command prompt. Anyone that knows a bit about the shell should install MeshCentral like this:</p>
|
||
<div class="highlight"><pre><span></span><code>mkdir c:\meshcentral
|
||
cd c:\meshcentral
|
||
npm install meshcentral
|
||
node node_modules\meshcentral
|
||
(ctrl-c when done installing optional modules)
|
||
node node_modules\meshcentral --install
|
||
</code></pre></div>
|
||
<p>This way, you have a lot more control over what is going on. In my opinion, the MSI installer basically does the same thing and installs NodeJS for you.</p>
|
||
<h3 id="meshcentral-debugging-unable-to-update-server">Unable to update server</h3>
|
||
<p>Generally the problem is that MeshCentral can't find the npm tool and therefore, can't run it to see if there is a new version. You can fix this by setting the path to npm in the config.json like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"npmPath"</span><span class="p">:</span><span class="w"> </span><span class="s2">"c:\\npm.exe"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"npmProxy"</span><span class="p">:</span><span class="w"> </span><span class="s2">"http://1.2.3.4:80"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>The problem could also be that you need a proxy, the configuration line to that is above.</p>
|
||
<p>You can also manually update. Just stop your server and so this:</p>
|
||
<div class="highlight"><pre><span></span><code>mv<span class="w"> </span>node_modules<span class="w"> </span>node_modules_bak
|
||
npm<span class="w"> </span>install<span class="w"> </span>meshcentral
|
||
node<span class="w"> </span>node_modules/meshcentral
|
||
</code></pre></div>
|
||
<p>Then wait for all optional modules to install, then once the server starts hit ctrl-c and start up the server again. You can also use the following to help you start/stop the server:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--install
|
||
node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--uninstall
|
||
node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--start
|
||
node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--stop
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-debugging-port-troubleshooting-on-server">Port Troubleshooting on server</h3>
|
||
<p>If you're getting a <code>port 4433 is not available</code> error, this is because another process is using this port, very likely another instance of MeshCentral. If your MeshCentral server is bound to ports 81/444 MeshCentral could not get port 80/443 and got the next available ones.</p>
|
||
<p>In general the problem is that you are running two MeshCentral instances at the same time. Probably one as a background Windows Service and one in the command line. Which ever instance can grab port 4433 will have a running MPS and CIRA should work, but the second instance will not have port 4433 and CIRA will not work.</p>
|
||
<h3 id="meshcentral-debugging-running-meshcentral-server-in-debug-mode">Running Meshcentral server in debug mode</h3>
|
||
<p>Debug more will cause MeshCentral to output a lot of debug messages to the console. To display all debug messages, run MeshCentral like this:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--debug
|
||
</code></pre></div>
|
||
<p>A more practical way to run the debug command it to specify what messages you want printed out using a comma seperated list, for example:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--debug<span class="w"> </span>web,amt,mps
|
||
</code></pre></div>
|
||
<p>Here is the list of all debug options:</p>
|
||
<div class="highlight"><pre><span></span><code>cookie - Cookie encoder
|
||
dispatch - Message Dispatcher
|
||
main - Main Server Messages
|
||
peer - MeshCentral Server Peering
|
||
agent - MeshAgent traffic
|
||
agentupdate - MeshAgent update
|
||
cert - Server Certificate
|
||
db - Server Database
|
||
email - Email/SMS/Push Traffic
|
||
web - Web Server
|
||
webrequest - Web Server Requests
|
||
relay - Web Socket Relay
|
||
httpheaders - Web Server HTTP Headers
|
||
authlog - User Authentication Log
|
||
amt - Intel AMT
|
||
webrelay - Connection Relay
|
||
mps - CIRA Server
|
||
mpscmd - CIRA Server Commands
|
||
</code></pre></div>
|
||
<p>You can also specify the <code>debug</code> option in the config.json file in the <code>settings</code> section. For example:</p>
|
||
<div class="highlight"><pre><span></span><code>"settings": {
|
||
"debug": "web,amt,mps"
|
||
}
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-debugging-enabling-trace-in-your-browser-dev-tools">Enabling trace in your browser Dev Tools</h3>
|
||
<p>You can enable browser console tracing by adding <code>trace=1</code> as a parameter to the URL of the MeshCentral main web page. For example <code>https://myserver.com/?trace=1</code>. Once present, open the browser's console window to see all web client tracing messages.</p>
|
||
<p>To log all database queries, change log_statement in /etc/postgresql/13/main/postgresql.conf</p>
|
||
<div class="highlight"><pre><span></span><code># CUSTOM
|
||
log_statement = 'all' # none, ddl, mod, all
|
||
</code></pre></div>
|
||
<p>The stacktrace was logged to <code>stdout/journalctl</code>. Supposedly, you can enable debug logging for node modules by adding <code>DEBUG=<modulename></code> to the environment. </p>
|
||
<p>Adding this to <code>/etc/systemd/system/meshcentral.service</code> should do it but it didn't seem to do anything. </p>
|
||
<p>I think that's because Mesh uses the trace logging in the browser instead of logging things in the server logs. </p>
|
||
<div class="highlight"><pre><span></span><code>Environment=DEBUG=mesh*
|
||
</code></pre></div>
|
||
<p>If you want to change node to meshcentral in journalctl, add this to /etc/systemd/system/meshcentral.service.</p>
|
||
<div class="highlight"><pre><span></span><code>SyslogIdentifier=meshcentral
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-debugging-finding-agent-problems">Finding agent problems</h3>
|
||
<p>Using the servers <code>My Server > console</code></p>
|
||
<ul>
|
||
<li><code>agentstatus</code> - Gives you summary counts of problems</li>
|
||
<li><code>agentissues</code> - Gives IP:port and what error</li>
|
||
<li><code>dupagents</code> - Gives duplicateAgent IP's, counts and names</li>
|
||
</ul>
|
||
<h3 id="meshcentral-debugging-logging-it-all">Logging it all</h3>
|
||
<p>To log everything that's possible, prepare the log directory.</p>
|
||
<div class="highlight"><pre><span></span><code>mkdir /meshcentral/meshcentral-logs/
|
||
chown tactical:tactical logs
|
||
ln -s ../meshcentral-logs/log.txt /meshcentral/meshcentral-data/log.txt
|
||
</code></pre></div>
|
||
<p>And then add this to your config.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="w"> </span><span class="nt">"meshErrorLogPath"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/meshcentral/meshcentral-logs/"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authLog"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/meshcentral/meshcentral-logs/auth.log"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"log"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||
<span class="w"> </span><span class="s2">"cookie"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"dispatch"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"main"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"peer"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"web"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"webrequest"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"relay"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"webrelaydata"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"webrelay"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"mps"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"mpscmd"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"swarm"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"swarmcmd"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"agentupdate"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"agent"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"cert"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"db"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"email"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"amt"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"httpheaders"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"websocket"</span>
|
||
<span class="w"> </span><span class="p">],</span>
|
||
</code></pre></div>
|
||
<p>You'll then have 3 files:</p>
|
||
<div class="highlight"><pre><span></span><code>-rw-rw-r--<span class="w"> </span><span class="m">1</span><span class="w"> </span>tactical<span class="w"> </span>tactical<span class="w"> </span><span class="m">2593</span><span class="w"> </span>Feb<span class="w"> </span><span class="m">2</span><span class="w"> </span><span class="m">12</span>:22<span class="w"> </span>auth.log
|
||
-rw-r--r--<span class="w"> </span><span class="m">1</span><span class="w"> </span>tactical<span class="w"> </span>tactical<span class="w"> </span><span class="m">147593</span><span class="w"> </span>Feb<span class="w"> </span><span class="m">2</span><span class="w"> </span><span class="m">12</span>:31<span class="w"> </span>log.txt
|
||
-rw-rw-r--<span class="w"> </span><span class="m">1</span><span class="w"> </span>tactical<span class="w"> </span>tactical<span class="w"> </span><span class="m">381</span><span class="w"> </span>Feb<span class="w"> </span><span class="m">2</span><span class="w"> </span><span class="m">12</span>:02<span class="w"> </span>mesherrors.txt
|
||
</code></pre></div>
|
||
<p><code>log.txt</code> will now log everything in the Trace tab</p>
|
||
<h3 id="meshcentral-debugging-restricting-server-to-specific-ips">Restricting server to specific IP(s)</h3>
|
||
<p>When doing debugging on my development server, I use this line in the settings section to block all agent connections except the agent I want:</p>
|
||
<div class="highlight"><pre><span></span><code>"agentAllowedIp": [ "192.168.2.147" ],
|
||
</code></pre></div>
|
||
<p>Of course, this is just for debugging.</p>
|
||
<h3 id="meshcentral-debugging-finding-system-id-types">Finding system ID types</h3>
|
||
<p><a href="https://serverurl/meshagents">https://serverurl/meshagents</a> aka trying figure out what this is</p>
|
||
<p><img alt="ID" src="../meshcentral/images/determine-id.jpg" /></p>
|
||
<h3 id="meshcentral-debugging-pull-down-cert-crt-file-from-internet">Pull down cert .crt file from internet</h3>
|
||
<p><a href="https://github.com/Ylianst/MeshCentral/issues/1662#issuecomment-666559391">See #1662</a> We have run into this challenge before, where our .crt file expired and then all our agents were unable to connect. In our case, the TLS cert was available on the internet, and thus, we were able to use these commands to update it:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="nb">echo</span><span class="w"> </span>-n<span class="w"> </span><span class="se">\|</span><span class="w"> </span>openssl<span class="w"> </span>s_client<span class="w"> </span>-connect<span class="w"> </span>yourdomain.com:443<span class="w"> </span><span class="m">2</span>><span class="w"> </span>/dev/null<span class="se">\|</span><span class="w"> </span>sed<span class="w"> </span>-ne<span class="w"> </span><span class="s1">'/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'</span><span class="w"> </span>><span class="w"> </span>/opt/meshcentral/meshcentral-data/webserver-cert-public.crt
|
||
service<span class="w"> </span>meshcentral<span class="w"> </span>restart
|
||
</code></pre></div>
|
||
<h2 id="meshcentral-debugging-meshagent">MeshAgent</h2>
|
||
<p>Troubleshooting agent</p>
|
||
<div class="highlight"><pre><span></span><code>./meshagent<span class="w"> </span>-state
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-debugging-agent-debug-logs-to-server">Agent Debug Logs to server</h3>
|
||
<p>This automatically downloads all agent error logs into <code>meshcentral-data/agenterrorlogs.txt</code></p>
|
||
<p><a href="https://github.com/Ylianst/MeshCentral/blob/aa58afcc3a5d738177ab7a7b6d0228d72af82b85/meshcentral-config-schema.json#L100">Set</a> in <code>config.json</code></p>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"agentLogDump"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-debugging-determine-agent-capabilities">Determine Agent capabilities</h3>
|
||
<p>On the server goto the agents console tab. Type:</p>
|
||
<div class="highlight"><pre><span></span><code>info
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-debugging-useful-meshagentmsh-flags">Useful MeshAgent.msh flags</h3>
|
||
<p><a href="https://github.com/Ylianst/MeshAgent/blob/master/meshcore/agentcore.h#L190">https://github.com/Ylianst/MeshAgent/blob/master/meshcore/agentcore.h#L190</a></p>
|
||
<div class="highlight"><pre><span></span><code><span class="err">co</span><span class="kc">ntr</span><span class="err">olCha</span><span class="kc">nnel</span><span class="err">Debug=</span><span class="mi">1</span>
|
||
<span class="err">logUpda</span><span class="kc">te</span><span class="err">=</span><span class="mi">1</span>
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-debugging-obtain-generated-msh-file">Obtain generated .msh File</h3>
|
||
<p>If you need a trick to get the .msh file, you can add ?debug=1 to the URL and click "Add Agent", there will be an extra link to download it.</p>
|
||
<h3 id="meshcentral-debugging-meshagent-commands">MeshAgent Commands</h3>
|
||
<div class="highlight"><pre><span></span><code>MeshAgent run
|
||
MeshAgent dbTool.js list
|
||
</code></pre></div>
|
||
<p>Forcing Core version from Cmdline</p>
|
||
<ul>
|
||
<li>Download meschore.js and rename to CoreModule.js and put it alongside MeshAgent.exe</li>
|
||
<li>Stop MeshAgent service</li>
|
||
<li>Run <code>MeshAgent.exe dbTool.js import CoreModule</code></li>
|
||
</ul>
|
||
<h3 id="meshcentral-debugging-on-the-fly-patching-meshagent">On the fly Patching MeshAgent</h3>
|
||
<p><a href="https://github.com/Ylianst/MeshAgent/issues/89#issuecomment-949901720">MeshAgent#89 (comment)</a></p>
|
||
<p>There are two ways to do this... When debugging, and making changes, you can modify the .js file directly, and just save it in the same folder as the agent binary... The agent will use the .js file from disc if it's there, if it's newer than the one compiled in the binary. You don't even need to restart the agent. You can just clear the core, and reload the core.....</p>
|
||
<p>When you are satisfied with your changes to the .js file, you can use the clipboard, in the following fashion:</p>
|
||
<div class="highlight"><pre><span></span><code>meshagent<span class="w"> </span>-exec<span class="w"> </span><span class="s2">"require('clipboard').nativeAddCompressedModule('foo');process.exit();"</span>
|
||
</code></pre></div>
|
||
<p>if the file you modified isn't in the same folder as the agent binary, you can use the following command if you don't want to move the file, and edit it directly in the modules folder:</p>
|
||
<div class="highlight"><pre><span></span><code>meshagent<span class="w"> </span>-exec<span class="w"> </span><span class="s2">"setModulePath('pathToFolder');require('clipboard').nativeAddCompressedModule('foo');process.exit();"</span>
|
||
</code></pre></div>
|
||
<p>This command is just like the previous, except it searches for modules in the path specified.</p>
|
||
<p>Just substitute foo, with the name of the module that you modified. It will load the module from disc, compress it, and save it into the clipboard.. So you can just load up your editor for ILibDuktape_Polyfills.c, and find where that particular module is defined... and paste directly from the clipboard... The clipboard will contain all the necessary C code to uncompress and load the module.</p>
|
||
<p>If the compressed result is relatively long, it will auto break it up into multiple lines to work around an issue with visual studio's maximum string literal limitations.</p>
|
||
<h3 id="meshcentral-debugging-agent-debugging-using-meshcore-js-debugger">Agent Debugging using MeshCore JS Debugger</h3>
|
||
<p><a href="https://github.com/Ylianst/MeshAgent/issues/119">(#119)</a> How to test changes to the meshagent and recompile them.</p>
|
||
<ul>
|
||
<li>Copy duktape-debugger.js to the mesh directory on the target machine.</li>
|
||
<li>From the console tab of the agent, enter this command, substituting the port number you want to use instead of 9999
|
||
<code>eval "attachDebugger({ webport: 9999 })"</code></li>
|
||
</ul>
|
||
<p>Then open your browser to http://localhost:9999 or whatever port you used.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>If you pause the debugger, and happen to forget about it, the agent will automatically kill itself and restart because it will think that a thread is stuck. Default debugger timeout is 10 minutes, you may find a log entry saved to disk saying "Microstack Thread STUCK", or something similar.</p>
|
||
</div>
|
||
<h3 id="meshcentral-debugging-troubleshooting-agent-connectivity">Troubleshooting Agent connectivity</h3>
|
||
<p>If an agent keeps disconnecting and reconnecting, add this line to the "settings" section of the config.json:</p>
|
||
<div class="highlight"><pre><span></span><code>"agentping": 30
|
||
</code></pre></div>
|
||
<p>This will cause MeshCentral to "ping" the agent every 30 seconds and the agent to respond with a "pong" each time. That usually solves the issue however, it does generate more traffic. If that works, you can remove the line and try this line instead:</p>
|
||
<div class="highlight"><pre><span></span><code>"agentpong": 30
|
||
</code></pre></div>
|
||
<p>This will cause MeshCentral to "pong" the agent every 30 seconds, the agent will not respond. This usually fixes the issue, but you have half the traffic. I would also increase the time like:</p>
|
||
<div class="highlight"><pre><span></span><code>"agentpong": 90
|
||
</code></pre></div>
|
||
<p>This is the best, you have one way traffic to all agents every 90 seconds. The larger the number you can get away with the better.</p>
|
||
<p>If you ever get the same problem but on the browser side, you can also use one of these:</p>
|
||
<div class="highlight"><pre><span></span><code>"browserping": 30
|
||
"browserpong": 30
|
||
</code></pre></div>
|
||
<p>Same idea, browser side instead of agent side.</p>
|
||
<h2 id="meshcentral-debugging-intel-amt">Intel AMT</h2>
|
||
<p>To debug issues, confirm that Intel AMT is active and there MeshCentral is not showing any red errors on the "Intel AMT" line:</p>
|
||
<p><img alt="" src="../meshcentral/images/amt_troubleshoot1.jpg" /></p>
|
||
<p>Next, you can go in the "My Server / Trace" tab and enable tracing on the "Intel AMT Manager" like this:</p>
|
||
<p><img alt="" src="../meshcentral/images/amt_troubleshoot2.jpg" /></p>
|
||
<p>You can then open another tab and select to power off or power on Intel AMT, you should see "performPowerAction" with 2 or 8 depending on power on/off.</p>
|
||
<p><img alt="" src="../meshcentral/images/amt_troubleshoot3.jpg" /></p></section><section class="print-page" id="meshcentral-devicetabs" heading-number="3.8"><h1 id="meshcentral-devicetabs-device-tabs">Device Tabs</h1>
|
||
<h2 id="meshcentral-devicetabs-search-or-filter">Search or Filter</h2>
|
||
<p>You can search your list of agents using any of these criteria using the filter box (also viewable in the tooltip of the Filter box):</p>
|
||
<div class="highlight"><pre><span></span><code>user:xxx or u:xxx
|
||
ip:xxx
|
||
group:xxx or g:xxx
|
||
tag:xxx or t:xxx
|
||
atag:xxx or a:xxx
|
||
os:xxx
|
||
amt:xxx
|
||
desc:xxx
|
||
wsc:ok
|
||
wsc:noav
|
||
wsc:noupdate
|
||
wsc:nofirewall
|
||
wsc:any
|
||
</code></pre></div>
|
||
<h2 id="meshcentral-devicetabs-general">General</h2>
|
||
<p>For viewing general information about the agent</p>
|
||
<ul>
|
||
<li>Group</li>
|
||
<li>Description</li>
|
||
<li>IP-KVM Port Number</li>
|
||
<li>IP-KVM Port Type</li>
|
||
<li>Intel AMT</li>
|
||
<li>Intel AMT Tag</li>
|
||
<li>Mesh Agent</li>
|
||
<li>Operating System</li>
|
||
<li>Windows Security</li>
|
||
<li>Antivirus</li>
|
||
<li>Active User</li>
|
||
<li>User Consent</li>
|
||
<li>Notifications</li>
|
||
<li>Tags</li>
|
||
</ul>
|
||
<h3 id="meshcentral-devicetabs-fields">Fields</h3>
|
||
<h3 id="meshcentral-devicetabs-buttons">Buttons</h3>
|
||
<p>Actions
|
||
Notes
|
||
Log Event
|
||
Message
|
||
PDU On/Off/Control
|
||
Chat</p>
|
||
<h3 id="meshcentral-devicetabs-7-day-power-state">7 Day Power State</h3>
|
||
<p><img alt="" src="../meshcentral/images/7daypowerstate.jpg" /></p>
|
||
<p>Legend</p>
|
||
<ul>
|
||
<li><strong><em>Black color</em></strong>: Device is Powered On on (Intel AMT & agents)</li>
|
||
<li><strong><em>Purple color</em></strong>: Device is in sleep state such as Hibernating (Intel AMT agents only)</li>
|
||
<li><strong><em>Teal color</em></strong>: Device is connected through AMT/CIRA, but the Power State is UNKNOWN (Intel AMT agents only)</li>
|
||
<li><strong><em>DarkGreen color</em></strong>: Device is connected through AMT/CIRA and is in Soft-Off Power State (Intel AMT agents only)</li>
|
||
<li><strong><em>Grey color</em></strong>: Device is Powered Off/Not Connected To MeshCentral (Intel AMT & agents)</li>
|
||
</ul>
|
||
<h3 id="meshcentral-devicetabs-text-links">Text Links</h3>
|
||
<p>You can set alternate port in the link if it's not default by right-clicking.</p>
|
||
<p><img alt="" src="../meshcentral/images/general_alternateports.jpg" /></p>
|
||
<ul>
|
||
<li>Interfaces</li>
|
||
<li>Location</li>
|
||
<li>MeshCmd</li>
|
||
<li>RDP</li>
|
||
<li>Web-VNC</li>
|
||
<li>Web-RDP</li>
|
||
<li>Web-SSH</li>
|
||
<li>XTerm</li>
|
||
<li>HTTP</li>
|
||
<li>HTTPS</li>
|
||
<li>SSH</li>
|
||
<li>SCP</li>
|
||
<li>MQTT Login</li>
|
||
</ul>
|
||
<h2 id="meshcentral-devicetabs-desktop">Desktop</h2>
|
||
<p>For connecting to the machines KVM interface.</p>
|
||
<h3 id="meshcentral-devicetabs-connect-button">Connect Button</h3>
|
||
<p>Right-clicking on Connect button will give you additional options:</p>
|
||
<ul>
|
||
<li>Ask Consent + Bar</li>
|
||
<li>Ask Consent</li>
|
||
<li>Privacy Bar</li>
|
||
</ul>
|
||
<p><img alt="" src="../meshcentral/images/desktop_connectbutton.jpg" /></p>
|
||
<h3 id="meshcentral-devicetabs-rdp-connect-button">RDP Connect Button</h3>
|
||
<p>Right-clicking on RDP Connect button allows you to specify Alternate Port.</p>
|
||
<p><img alt="" src="../meshcentral/images/desktop_rdpconnectbutton.jpg" /></p>
|
||
<h3 id="meshcentral-devicetabs-intel-amt-connect-button">Intel AMT Connect Button</h3>
|
||
<p>Uses Intel AMT to control video output of the hardware video card.</p>
|
||
<h3 id="meshcentral-devicetabs-during-a-desktop-session">During a desktop session</h3>
|
||
<p><strong>Bottom left include:</strong></p>
|
||
<p><img alt="desktop bottom left" src="../meshcentral/images/desktop_buttonsbottomleft.jpg" /></p>
|
||
<ul>
|
||
<li>Sending special Keys</li>
|
||
</ul>
|
||
<p><strong>Top Right include:</strong></p>
|
||
<p>Actions</p>
|
||
<p><img alt="" src="../meshcentral/images/desktop_buttonstopright_actions.jpg" /></p>
|
||
<ul>
|
||
<li>Wake Up</li>
|
||
<li>Run Commands</li>
|
||
<li>Sleep</li>
|
||
<li>Reset</li>
|
||
<li>Power Off</li>
|
||
<li>Uninstall Agent</li>
|
||
</ul>
|
||
<p>Settings</p>
|
||
<p><img alt="" src="../meshcentral/images/desktop_settings.jpg" /></p>
|
||
<ul>
|
||
<li>Quality</li>
|
||
<li>Scaling</li>
|
||
<li>Frame rate</li>
|
||
<li>Swap Mouse Buttons</li>
|
||
<li>Reverse Mouse Wheel</li>
|
||
<li>Use Remote Keyboard Map</li>
|
||
<li>Automatic Clipboard</li>
|
||
<li>Lock on Disconnect</li>
|
||
</ul>
|
||
<p><img alt="" src="../meshcentral/images/desktop_buttonstopright_other.jpg" /></p>
|
||
<ul>
|
||
<li>Session recording indicator</li>
|
||
<li>Screen rotating</li>
|
||
<li>switching view mode</li>
|
||
<li>full screen</li>
|
||
</ul>
|
||
<p>Bottom right include:</p>
|
||
<p><img alt="" src="../meshcentral/images/desktop_buttonsbottomright.jpg" /></p>
|
||
<ul>
|
||
<li>Session Sharing with Guest</li>
|
||
<li>Toggling keyboard lockout on guest</li>
|
||
<li>Refresh Desktop view</li>
|
||
<li>Upload Clipboard</li>
|
||
<li>Download Clipboard</li>
|
||
<li>Record Session to file</li>
|
||
<li>Take screenshot</li>
|
||
<li>Toggle Remote Desktop Background</li>
|
||
<li>Open URL on remote desktop</li>
|
||
<li>Lock the Remote computer</li>
|
||
<li>Display a notification on the remote computer</li>
|
||
<li>Open Chat Window</li>
|
||
</ul>
|
||
<h2 id="meshcentral-devicetabs-terminal">Terminal</h2>
|
||
<p>For connecting to a command line based interface on the agent</p>
|
||
<p>Right-clicking on Connect button allows you to:</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Linux and Windows have different options:</p>
|
||
</div>
|
||
<ul>
|
||
<li>Admin Shell (Windows)</li>
|
||
<li>Admin Powershell (Windows)</li>
|
||
<li>User Shell (Windows)</li>
|
||
<li>User Powershell (Windows)</li>
|
||
<li>SSH (Linux)</li>
|
||
</ul>
|
||
<p><img alt="" src="../meshcentral/images/terminal_connectbutton.jpg" /></p>
|
||
<h2 id="meshcentral-devicetabs-files">Files</h2>
|
||
<p>For transferring files to and from the agent.</p>
|
||
<h2 id="meshcentral-devicetabs-events">Events</h2>
|
||
<p>Mesh Events related to the agent. This is your audit log to see what actions have been taken on the agent from the MeshCentral server.</p>
|
||
<h2 id="meshcentral-devicetabs-details">Details</h2>
|
||
<p>Agent information that includes:</p>
|
||
<ul>
|
||
<li>OS</li>
|
||
<li>Agent Info</li>
|
||
<li>Network Info</li>
|
||
<li>BIOS</li>
|
||
<li>Motherboard</li>
|
||
<li>Memory</li>
|
||
<li>Storage</li>
|
||
<li>Intel AMT</li>
|
||
</ul>
|
||
<p>Note you can show CPU and Memory usage info by clicking the icon in the top right corner</p>
|
||
<p><img alt="" src="../meshcentral/images/details_cpuram.jpg" /></p>
|
||
<h2 id="meshcentral-devicetabs-intel-amt">Intel AMT</h2>
|
||
<h2 id="meshcentral-devicetabs-console">Console</h2>
|
||
<p>For debugging and communicating with the mesh agent.</p>
|
||
<p>It allows JS commands to be issued to the device but also run extra commands from the meshcore. Type <code>help</code> for all available options</p>
|
||
<ul>
|
||
<li>2falock</li>
|
||
<li>acceleratorsstats</li>
|
||
<li>agentissues</li>
|
||
<li>agentstats</li>
|
||
<li>amtacm</li>
|
||
<li>amtmanager</li>
|
||
<li>amtpasswords</li>
|
||
<li>amtstats</li>
|
||
<li>args</li>
|
||
<li>autobackup</li>
|
||
<li>backupconfig</li>
|
||
<li>bad2fa</li>
|
||
<li>badlogins</li>
|
||
<li>certexpire</li>
|
||
<li>certhashes</li>
|
||
<li>closeusersessions</li>
|
||
<li>cores</li>
|
||
<li>dbcounters</li>
|
||
<li>dbstats</li>
|
||
<li>dispatchtable</li>
|
||
<li>dropallcira</li>
|
||
<li>dupagents</li>
|
||
<li>email</li>
|
||
<li>emailnotifications</li>
|
||
<li>firebase</li>
|
||
<li>heapdump</li>
|
||
<li>heapdump2</li>
|
||
<li>help</li>
|
||
<li>info</li>
|
||
<li>le</li>
|
||
<li>lecheck</li>
|
||
<li>leevents</li>
|
||
<li>maintenance</li>
|
||
<li>migrationagents</li>
|
||
<li>mps</li>
|
||
<li>mpsstats</li>
|
||
<li>msg</li>
|
||
<li>nodeconfig</li>
|
||
<li>print</li>
|
||
<li>relays</li>
|
||
<li>removeinactivedevices</li>
|
||
<li>resetserver</li>
|
||
<li>serverupdate</li>
|
||
<li>setmaxtasks</li>
|
||
<li>showpaths</li>
|
||
<li>sms</li>
|
||
<li>swarmstats</li>
|
||
<li>tasklimiter</li>
|
||
<li>trafficdelta</li>
|
||
<li>trafficstats</li>
|
||
<li>updatecheck</li>
|
||
<li>usersessions</li>
|
||
<li>versions</li>
|
||
<li>watchdog</li>
|
||
<li>webpush</li>
|
||
<li>webstats</li>
|
||
</ul></section><section class="print-page" id="meshcentral-plugins" heading-number="3.9"><h1 id="meshcentral-plugins-plugins-installation-usage">Plugins - Installation & Usage</h1>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Plugins as such receive <strong>no support</strong> by the main developers of MeshCentral. If you experience problems with MeshCentral please make sure to <strong>disable all plugins before further troubleshooting</strong>!</p>
|
||
</div>
|
||
<h2 id="meshcentral-plugins-use-cases">Use Cases</h2>
|
||
<p>Certain feature requests may not be suitable for all MeshCentral users and thus are available as a plugin. Furthermore users can develop their own plugins - as described further below - to extend functionality or benefit from integrating MeshCentral into their existing application environment.</p>
|
||
<h2 id="meshcentral-plugins-list-of-publically-available-plugins">List of publically available plugins</h2>
|
||
<p><a href="https://github.com/topics/meshcentral-plugin">https://github.com/topics/meshcentral-plugin</a></p>
|
||
<h2 id="meshcentral-plugins-installation-of-a-plugin">Installation of a plugin</h2>
|
||
<ol>
|
||
<li>First please make sure that you enable plugins in the configuration<blockquote>
|
||
<p>"plugins": {
|
||
"enabled": true
|
||
},</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>Restart MeshCentral if you needed to change the configuration.</li>
|
||
<li>Log into MeshCentral as full administrator.</li>
|
||
<li>Go my <code>My Server</code> -> <code>Plugins</code>, then hit the Download plugin button.</li>
|
||
<li>A dialog opens requesting a URL, e.g. put in: <a href="https://github.com/ryanblenis/MeshCentral-ScriptTask">https://github.com/ryanblenis/MeshCentral-ScriptTask</a></li>
|
||
<li>The plugin pops up in the plugin list below the download button, you can now configure and enable/disable it.</li>
|
||
</ol>
|
||
<h1 id="meshcentral-plugins-plugins-development-hooks">Plugins - Development & Hooks</h1>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Plugins as such receive <strong>no support</strong> by the main developers of MeshCentral. If you experience problems with MeshCentral please make sure to <strong>disable all plugins before further troubleshooting</strong>!</p>
|
||
</div>
|
||
<h2 id="meshcentral-plugins-overview">Overview</h2>
|
||
<p>Not all feature requests may be suitable for all MeshCentral users and thus can't be integrated into MeshCentral directly. Hwoever, Instead of maintaining a complete fork of MeshCentral it is much easier to extend MeshCentral's functionality using hooks and writing plugins for it.</p>
|
||
<h2 id="meshcentral-plugins-anatomy-of-a-plugin">Anatomy of a plugin:</h2>
|
||
<pre><code>- plugin_name/
|
||
-- config.json
|
||
-- plugin_name.js
|
||
-- modules_meshcore/ // optional
|
||
--- plugin_name.js // optional
|
||
</code></pre>
|
||
<h2 id="meshcentral-plugins-plugin-configuration-file">Plugin Configuration File</h2>
|
||
<p>A valid JSON object within a file named <code>config.json</code> in the root folder of your project. An example:</p>
|
||
<pre><code>{
|
||
"name": "Plugin Name",
|
||
"shortName": "plugin_name",
|
||
"version": "0.0.0",
|
||
"author": "Author Name",
|
||
"description": "Short Description of the plugin",
|
||
"hasAdminPanel": false,
|
||
"homepage": "https://www.example.com",
|
||
"changelogUrl": "https://raw.githubusercontent.com/User/Project/master/changelog.md",
|
||
"configUrl": "https://raw.githubusercontent.com/User/Project/master/config.json",
|
||
"downloadUrl": "https://github.com/User/Project/archive/master.zip",
|
||
"repository": {
|
||
"type": "git",
|
||
"url": "https://github.com/User/Project.git"
|
||
},
|
||
"versionHistoryUrl": "https://api.github.com/repos/User/Project/tags",
|
||
"meshCentralCompat": ">0.4.3"
|
||
}
|
||
</code></pre>
|
||
<h2 id="meshcentral-plugins-configuration-file-properties">Configuration File Properties</h2>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>Required</th>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>name</td>
|
||
<td>Yes</td>
|
||
<td>string</td>
|
||
<td>a human-readable name for the plugin</td>
|
||
</tr>
|
||
<tr>
|
||
<td>shortName</td>
|
||
<td>Yes</td>
|
||
<td>string</td>
|
||
<td>an alphanumeric, unique short identifier for the plugin (will be used to access your functions throughout the project</td>
|
||
</tr>
|
||
<tr>
|
||
<td>version</td>
|
||
<td>Yes</td>
|
||
<td>string</td>
|
||
<td>the current version of the plugin</td>
|
||
</tr>
|
||
<tr>
|
||
<td>author</td>
|
||
<td>No</td>
|
||
<td>string</td>
|
||
<td>the author's name</td>
|
||
</tr>
|
||
<tr>
|
||
<td>description</td>
|
||
<td>Yes</td>
|
||
<td>string</td>
|
||
<td>a short, human-readable description of what the plugin does</td>
|
||
</tr>
|
||
<tr>
|
||
<td>hasAdminPanel</td>
|
||
<td>Yes</td>
|
||
<td>boolean</td>
|
||
<td><code>true</code> or <code>false</code>, indicates whether or not the plugin will offer its own administrative interface</td>
|
||
</tr>
|
||
<tr>
|
||
<td>homepage</td>
|
||
<td>Yes</td>
|
||
<td>string</td>
|
||
<td>the URL of the projects homepage</td>
|
||
</tr>
|
||
<tr>
|
||
<td>changelogUrl</td>
|
||
<td>Yes</td>
|
||
<td>string</td>
|
||
<td>the URL to the changelog of the project</td>
|
||
</tr>
|
||
<tr>
|
||
<td>configUrl</td>
|
||
<td>Yes</td>
|
||
<td>string</td>
|
||
<td>the URL to the config.json of the project</td>
|
||
</tr>
|
||
<tr>
|
||
<td>downloadUrl</td>
|
||
<td>Yes</td>
|
||
<td>string</td>
|
||
<td>the URL to a ZIP of the project (used for installation/upgrades)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>repository</td>
|
||
<td>Yes</td>
|
||
<td>JSON object</td>
|
||
<td>contains the following attributes</td>
|
||
</tr>
|
||
<tr>
|
||
<td>repository.type</td>
|
||
<td>Yes</td>
|
||
<td>string</td>
|
||
<td>valid values are <code>git</code> and in the future, <code>npm</code> will also be supported.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>repository.url</td>
|
||
<td>Yes</td>
|
||
<td>string</td>
|
||
<td>the URL to the project's repository</td>
|
||
</tr>
|
||
<tr>
|
||
<td>versionHistoryUrl</td>
|
||
<td>No</td>
|
||
<td>string</td>
|
||
<td>the URL to the project's versions/tags</td>
|
||
</tr>
|
||
<tr>
|
||
<td>meshCentralCompat</td>
|
||
<td>Yes</td>
|
||
<td>string</td>
|
||
<td>the minimum version string of required compatibility with the MeshCentral server, can be formatted as "0.1.2-c" or ">=0.1.2-c". Currently only supports minimum version, not full semantic checking.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h2 id="meshcentral-plugins-plugin-hooks">Plugin Hooks</h2>
|
||
<p>In essence, hooks are locations in the code which enable developers to tap into a module to either provide alternative behavior or to respond to an event.</p>
|
||
<p>These are separated into the following categories depending on the type of functionality the plugin should offer.</p>
|
||
<ul>
|
||
<li>Web UI, to modify the MeshCentral admin interface</li>
|
||
<li>Back End, to modify core functionality of the server and communicate with the Web UI layer as well as the Mesh Agent (Node) layer to send commands and data</li>
|
||
<li>Mesh Agent (Node), to introduce functionality to each agent</li>
|
||
</ul>
|
||
<h3 id="meshcentral-plugins-web-ui-hooks">Web UI Hooks</h3>
|
||
<ul>
|
||
<li><code>onDeviceRefreshEnd</code>: called when a device is selected in the MeshCentral web interface</li>
|
||
<li><code>registerPluginTab</code>: callable when a device is selected in the MeshCentral web interface to register a new tab for plugin data, if required. Accepts an object, or function that returns an object, with the following properties: { tabId: "yourShortNameHere", tabTitle: "Your Display Name"}. A tab and div with the associated ID and title will be created for your use</li>
|
||
<li><code>onDesktopDisconnect</code>: called when a remote desktop session is disconnected</li>
|
||
<li><code>onWebUIStartupEnd</code>: called when the page has loaded for the first time after a login / refresh</li>
|
||
<li><code>goPageStart</code>: called before page changes take effect. Passes 2 arguments (<page number> : int, <event> : Event)</li>
|
||
<li><code>goPageEnd</code>: called after page changes take effect. Passes 2 arguments (<page number> : int, <event> : Event)</li>
|
||
</ul>
|
||
<h4 id="meshcentral-plugins-exports">Exports</h4>
|
||
<p>Any function can be exported to the Web UI layer by adding the name of the function to an <code>exports</code> array in the plugin object.</p>
|
||
<h3 id="meshcentral-plugins-back-end-hooks">Back End Hooks</h3>
|
||
<ul>
|
||
<li><code>server_startup</code>: called once when the server starts (or when the plugin is first installed)</li>
|
||
<li><code>hook_agentCoreIsStable</code>: called once when an agent initially checks in</li>
|
||
<li><code>hook_processAgentData</code>: called each time an agent transmits data back to the server</li>
|
||
<li><code>hook_userLoggedIn</code>: called when a user has logged into the web interface</li>
|
||
<li><code>hook_setupHttpHandlers</code>: called before all http handlers are setup</li>
|
||
</ul>
|
||
<h3 id="meshcentral-plugins-mesh-agent">Mesh Agent</h3>
|
||
<p>Use of the optional file <code>plugin_name.js</code> in the optional folder <code>modules_meshcore</code> will include the file in the default meshcore file sent to each endpoint. This is useful to add functionality on each of the endpoints.</p>
|
||
<h2 id="meshcentral-plugins-structure">Structure</h2>
|
||
<p>Much of MeshCentral revolves around returning objects for your structures, and plugins are no different. Within your plugin you can traverse all the way up to the web server and MeshCentral Server classes to access all the functionality those layers provide. This is done by passing the current object to newly created objects, and assigning that reference to a <code>parent</code> variable within that object.</p>
|
||
<h2 id="meshcentral-plugins-ping-pong">Ping-Pong</h2>
|
||
<p>If you build a plugin which makes use of <code>meshrelay.ashx</code>, keep in mind to either handle ping-pong messages (<code>serverPing</code>, <code>serverPong</code>) on the control channel or to request MeshCentral to not send such messages through sending the <code>noping=1</code> parameter in the connection URL. For a deeper sight search for "PING/PONG" in <code>meshrelay.js</code>.</p>
|
||
<h2 id="meshcentral-plugins-versioning">Versioning</h2>
|
||
<p>Versioning your plugin correctly and consistently is essential to ensure users of your plugin are prompted to upgrade when it is available. Semantic versioning is recommended.</p>
|
||
<h2 id="meshcentral-plugins-changelog">Changelog</h2>
|
||
<p>A changelog is highly recommended so that your users know what's changed since their last version.</p>
|
||
<h2 id="meshcentral-plugins-sample-plugin">Sample Plugin</h2>
|
||
<p><a href="https://github.com/ryanblenis/MeshCentral-Sample">MeshCentral-Sample</a> is a simple plugin that, upon disconnecting from remote desktop, prompts the user to enter a manual event (note), pre-filled in with the date and timestamp.</p></section><section class="print-page" id="meshcentral-security" heading-number="3.10"><h1 id="meshcentral-security-security">Security</h1>
|
||
<h2 id="meshcentral-security-rate-limiting-login-attempts">Rate Limiting login attempts</h2>
|
||
<p>You can use the MeshCentral Server Console with the command <code>badlogins</code> to see the current settings.</p>
|
||
<p>Adjust these items in your <code>config.json</code></p>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"_maxInvalidLogin"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"time"</span><span class="p">:</span><span class="w"> </span><span class="mi">10</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"count"</span><span class="p">:</span><span class="w"> </span><span class="mi">10</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"coolofftime"</span><span class="p">:</span><span class="w"> </span><span class="mi">10</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p><img alt="" src="../meshcentral/images/rate_limiting_logins.jpg" /></p>
|
||
<h2 id="meshcentral-security-disabling-tls-1011-for-amt">Disabling TLS 1.0/1.1 for AMT</h2>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"mpshighsecurity"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<h2 id="meshcentral-security-duo-2fa-setup">Duo 2FA setup</h2>
|
||
<p>MeshCentral supports Duo as a way for users to add two-factor authentication and Duo offers free accounts for user 10 users. To get started, go to <a href="https://duo.com/">Duo.com</a> and create a free account. Once logged into Duo, select "Applications" and "Protect an Application" on the left side. Search for "Web SDK" and hit the "Protect" button. You will see a screen with the following information:</p>
|
||
<ul>
|
||
<li>Client ID</li>
|
||
<li>Client secret</li>
|
||
<li>API hostname</li>
|
||
</ul>
|
||
<p>Copy these three values in a safe place and do not share these values with anyone. Then, in your MeshCentral config.json file, add the following in the domains section:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"duo2factor"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"integrationkey"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ClientId"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"secretkey"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ClientSecret"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"apihostname"</span><span class="p">:</span><span class="w"> </span><span class="s2">"api-xxxxxxxxxxx.duosecurity.com"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Restart MeshCentral and your server should now be Duo capable. Users will see an option to enable it in the "My Account" tab. When enabling it, users will be walked thru the process of downloading the mobile application and going thru a trial run on 2FA. Users that get setup will be added to your Duo account under the "Users" / "Users" screen in Duo. Note that the "admin" user is not valid in Duo, so, if you have a user with the name "Admin" in MeshCentral, they will get an error trying to setup Duo.</p></section><section class="print-page" id="meshcentral-tokens" heading-number="3.11"><h1 id="meshcentral-tokens-141-tokens">14.1 Tokens</h1>
|
||
<h2 id="meshcentral-tokens-user-tokens">User Tokens</h2>
|
||
<p><img alt="User Tokens 1" src="../meshcentral/images/user_tokens1.jpg" /></p>
|
||
<p><img alt="User Tokens 2" src="../meshcentral/images/user_tokens2.jpg" /></p>
|
||
<h2 id="meshcentral-tokens-software-integration-tokens">Software Integration Tokens</h2>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>You can only have a SINGLE loginTokenKey for your meshcentral server!<br>
|
||
So if you regenerate a loginTokenKey, the old one will be revoked/deleted!</p>
|
||
</div>
|
||
<p>You can create/view the Login Token Key with the following:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--loginTokenKey
|
||
</code></pre></div>
|
||
<p>You can then reset/revoke/renew the Login Token Key with the following to create a new one:</p>
|
||
<div class="highlight"><pre><span></span><code>node<span class="w"> </span>node_modules/meshcentral<span class="w"> </span>--loginTokenKey<span class="w"> </span>--loginTokenGen
|
||
</code></pre></div></section><section class="print-page" id="meshcentral-faq" heading-number="3.12"><h1 id="meshcentral-faq-faq">FAQ</h1>
|
||
<h2 id="meshcentral-faq-json-config-files">json config files</h2>
|
||
<p>Any item in the config.json file starting with an underscore character are ignored.</p>
|
||
<p>Ignored</p>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"_title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MyServer"</span>
|
||
</code></pre></div>
|
||
<p>Valid setting</p>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MyServer"</span>
|
||
</code></pre></div>
|
||
<p>json requires correct formatting, if in doubt copy/paste your json config into a web based format checker to make sure you have it right: <a href="https://duckduckgo.com/?va=j&t=hc&q=json+lint&ia=answer">https://duckduckgo.com/?va=j&t=hc&q=json+lint&ia=answer</a></p>
|
||
<h2 id="meshcentral-faq-help-ive-been-hacked-there-are-weird-agents-appearing-in-my-meshcentral-console">Help! I've been hacked there are weird agents appearing in my MeshCentral Console</h2>
|
||
<p>No, you haven't.</p>
|
||
<ol>
|
||
<li>
|
||
<p>Your agent installer was scanned by an antivirus.</p>
|
||
</li>
|
||
<li>
|
||
<p>It didn't recognize the exe.</p>
|
||
</li>
|
||
<li>
|
||
<p>You have the option enabled to submit unknown applications for analysis.</p>
|
||
<p><img alt="AV Option1" src="../meshcentral/images/faq_av_option1.jpg" /></p>
|
||
</li>
|
||
<li>
|
||
<p>They ran it against their virtualization testing cluster.</p>
|
||
</li>
|
||
<li>
|
||
<p>You allow anyone to connect to your server (you should look into techniques to hide your server from the internet).</p>
|
||
</li>
|
||
<li>
|
||
<p>Here are some examples of what that looks like.</p>
|
||
</li>
|
||
</ol>
|
||
<h2 id="meshcentral-faq-cant-login-on-server-after-first-setup">Can't login on server after first setup</h2>
|
||
<p>You're sure you're typing in everything right, giving it 2FA code and can't login</p>
|
||
<p><a href="https://en.wikipedia.org/wiki/Time-based_one-time_password">TOTP</a> is time sensitive, check your time/NTP and make sure it's right (on server and TOTP app device)! :)</p>
|
||
<p><img alt="" src="../images/2022-08-04-18-19-19.png" /></p>
|
||
<h2 id="meshcentral-faq-branding-and-customization">Branding and Customization</h2>
|
||
<p>You can brand and customize MeshCentral almost as much as you like without delving into the code, a few changes in the config.json file and uploading images can change the way your system looks. Read more <a href="https://ylianst.github.io/MeshCentral/meshcentral/#branding-terms-of-use">here</a></p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>You will need to reinstall the agent for agent customizations to take effect.</p>
|
||
</div>
|
||
<h2 id="meshcentral-faq-mac-clients">Mac Clients</h2>
|
||
<p>You have to manually grant Mac permissions outside of the agent install process due to the MacOS security system under Security & Privacy > Privacy</p>
|
||
<p>To see the screen (otherwise you just see the menu bar, and otherwise blank)</p>
|
||
<p><img alt="" src="../meshcentral/images/2023-11-29-12-57-15.jpg" /></p>
|
||
<p>To be able to transfer files</p>
|
||
<p><img alt="" src="../meshcentral/images/2023-11-29-12-58-05.jpg" /></p>
|
||
<p>To be able to control keyboard and mouse</p>
|
||
<p><img alt="" src="../meshcentral/images/2023-11-29-12-58-36.jpg" /></p>
|
||
<h2 id="meshcentral-faq-im-using-cloudflare-and-im-getting-a-black-screen-but-the-mouse-moves">I'm using CloudFlare and I'm getting a black screen but the mouse moves?</h2>
|
||
<p>If you are using CloudFlare for your DNS hosting and your remote screen is black, DONT PANIC!</p>
|
||
<p>Unfortunately, MeshCentral doesn't always work with CloudFlare's Proxy DNS Mode. </p>
|
||
<p>The fix is to simply set the 'Proxy Status' to OFF inside your DNS A Record, within the CloudFlare control panel.</p>
|
||
<p>Simply follow the steps <a href="https://developers.cloudflare.com/fundamentals/setup/manage-domains/pause-cloudflare/#disable-proxy-on-dns-records">here</a></p>
|
||
<p>Once done, open your firewall for the <code>port</code> and <code>agentPort</code> ports of where your meshcentral is hosted, then restart your MeshCentral Server</p>
|
||
<p>There is currently a PINNED GitHub issue about this <a href="https://github.com/Ylianst/MeshCentral/issues/5302">here</a></p></section><section class="print-page" id="meshcentral-tipsntricks" heading-number="3.13"><h1 id="meshcentral-tipsntricks-tips-n-tricks">Tips n' Tricks</h1>
|
||
<h2 id="meshcentral-tipsntricks-colors-in-ssh">Colors in SSH</h2>
|
||
<p>The SSH terminal does support color. The issue is going to be the terminal configuration of the shell. Try typing this:</p>
|
||
<div class="highlight"><pre><span></span><code>ls<span class="w"> </span>-al<span class="w"> </span>--color<span class="w"> </span>/tmp
|
||
</code></pre></div>
|
||
<h2 id="meshcentral-tipsntricks-fancy-config-editing-with-vs-code">Fancy config editing with VS Code</h2>
|
||
<p>A common problem in the issues is an incorrect config.json. What makes a config incorrect? How can you verify your config is correct?</p>
|
||
<p>Easy! Use Visual Studio Code to edit your config.json and add the schema at the top.</p>
|
||
<p>If you haven't already, download VS code.
|
||
Download or copy the config.json to your computer.
|
||
Open config.json in code and add the schema as the top line. This schema is the raw JSON file in the MeshCentral repo.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"your settings go here"</span><span class="p">:</span><span class="w"> </span><span class="s2">"..."</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Now you have autocomplete, auto-format and validation for your config.json! If you start typing, Code will show the values that are valid for the location you are editing. Words with a red squiggle line are errors. Words with a orange squiggle line are warnings. Hover over both to see the error message and possible fixes. Code can even format your config.</p>
|
||
<p>While this is a huge step up, it's not perfect. If you notice, there are some invalid keys in the screenshot. This is perfectly valid JSON and MeshCentral will ignore them (maybe?). If you paste some configs into the wrong section, code will not tell you it's in the wrong section. Autocomplete will tell you what keys are valid and the type of the value (i.e. string, number, boolean).</p>
|
||
<p>Hopefully this will help verify your config is syntactically correct and prevent needless formatting errors, misspellings, etc.</p>
|
||
<p><img alt="" src="../meshcentral/images/2023-02-24vscodejsonediting.jpg" /></p>
|
||
<h2 id="meshcentral-tipsntricks-downloading-folders">Downloading Folders</h2>
|
||
<p>If you would like to download folders via Files simply select folder/files then use the zip and download the zip file by clicking on it.</p>
|
||
<h2 id="meshcentral-tipsntricks-share-device-groups-with-ad-logins">Share device groups with AD logins</h2>
|
||
<p>If you would like to share device groups with different AD users.</p>
|
||
<p>In the config.json set "ldapuserkey" to "sAMAccountName".</p></section><section class="print-page" id="messaging" heading-number="3.14"><h1 id="messaging-messaging">Messaging</h1>
|
||
<h2 id="messaging-table-of-contents">Table of Contents</h2>
|
||
<p><a href="#messaging-introduction">Introduction</a><br />
|
||
<a href="#messaging-telegram-setup">Telegram Setup</a><br />
|
||
<a href="#messaging-discord-setup">Discord Setup</a><br />
|
||
<a href="#messaging-xmpp-setup">XMPP Setup</a><br />
|
||
<a href="#messaging-callmebot-setup">CallMeBot Setup</a><br />
|
||
<a href="#messaging-pushover-setup">Pushover Setup</a><br />
|
||
<a href="#messaging-ntfy-setup">ntfy Setup</a><br />
|
||
<a href="#messaging-zulip-setup">Zulip Setup</a><br />
|
||
<a href="#messaging-user-setup">User Setup</a><br />
|
||
<a href="#messaging-administrator-management">Administrator Management</a><br />
|
||
<a href="#messaging-two-factor-authentication">Two-Factor Authentication</a> </p>
|
||
<h2 id="messaging-introduction">Introduction</h2>
|
||
<p>MeshCentral supports messaging platforms so that users can register a messaging account with MeshCentral and receive notifications. This is useful since messages are sent to an application the user is confirtable with and many messaging platforms have clients on mobile phones, desktop and more so that the notification can show up where the user is.</p>
|
||
<h2 id="messaging-telegram-setup">Telegram Setup</h2>
|
||
<p>For Telegram integration, you will need to provide MeshCentral with the necessary login information so that MeshCentral can authenticate and connect to the Telegram servers and start sending notifications. For Telegram, both user and bot login is supported with bot login being the more typical way to go. The configuration in the config.json for a bot login looks like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"devbox.mesh.meshcentral.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"My Server"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"messaging"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"telegram"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"apiid"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"apihash"</span><span class="p">:</span><span class="w"> </span><span class="s2">"00000000000000000000000"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"bottoken"</span><span class="p">:</span><span class="w"> </span><span class="s2">"00000000:aaaaaaaaaaaaaaaaaaaaaaaa"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Note the "messaging" section in the config.json. For Telegram user login, it looks like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"messaging"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"telegram"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"apiid"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"apihash"</span><span class="p">:</span><span class="w"> </span><span class="s2">"00000000000000000000000"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"session"</span><span class="p">:</span><span class="w"> </span><span class="s2">"aaaaaaaaaaaaaaaaaaaaaaa"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>User login makes use of "session", while bot login uses "bottoken". One way to get started with the setup is to run <code>node node_modules/meshcentral --setuptelegram</code> and follow the instructions.</p>
|
||
<p><img alt="" src="../messaging/images/MC2-Telegram5.png" /></p>
|
||
<p>In the first step, you will get the apiid and apihash values. In the second step you get the bottoken or enter your phone number and code to get the session value. Once done, when running the server manually from the command line, the server should indicate that it can connect to Telegram like this:</p>
|
||
<div class="highlight"><pre><span></span><code>MeshCentral HTTP redirection server running on port 80.
|
||
MeshCentral v1.0.87, Hybrid (LAN + WAN) mode.
|
||
MeshCentral Intel(R) AMT server running on central.mesh.meshcentral.com:4433.
|
||
MeshCentral HTTPS server running on central.mesh.meshcentral.com:443.
|
||
MeshCentral HTTPS relay server running on relay1.mesh.meshcentral.com:443.
|
||
MeshCentral Telegram client is bot connected.
|
||
</code></pre></div>
|
||
<p>Note the last line, indicating it's connected as a bot. If you wish to use Telegram with a proxy, here are the possible Telegram settings. You can use the proxy settings for both user or bot login modes.</p>
|
||
<div class="highlight"><pre><span></span><code>{
|
||
"messaging": {
|
||
"telegram": {
|
||
"apiid": 0,
|
||
"apihash": "00000000000000000000000",
|
||
"session": "aaaaaaaaaaaaaaaaaaaaaaa",
|
||
"useWSS": false, // Important. Most proxies cannot use SSL.
|
||
"proxy": {
|
||
"ip": "123.123.123.123", // Proxy host (IP or hostname)
|
||
"port": 123, // Proxy port
|
||
"MTProxy": false, // Whether it's an MTProxy or a normal Socks one
|
||
"secret": "00000000000000000000000000000000", // If used MTProxy then you need to provide a secret (or zeros).
|
||
"socksType": 5, // If used Socks you can choose 4 or 5.
|
||
"timeout": 2 // Timeout (in seconds) for connection,
|
||
}
|
||
}
|
||
}
|
||
}
|
||
</code></pre></div>
|
||
<h2 id="messaging-discord-setup">Discord Setup</h2>
|
||
<p>For Discord integration, you need to provide MeshCentral with a bot application token so that MeshCentral can login and send notifications to users. The Discord bot will need to be joined to one or more Discord servers and users will need to join at at least one Discord server that is in common with the bot to receive notifications.</p>
|
||
<p>There are many tutorials online on how to create a Discord bot and get the login token. For example follow the <a href="https://www.freecodecamp.org/news/create-a-discord-bot-with-javascript-nodejs/">two first sections of this tutorial</a>. The "How to Create a Discord Bot Account" section will show how to create a bot and get the token, the "How to Invite Your Bot to Join a Server" section shows how to join the bot to a Discord server.</p>
|
||
<p>Note that Privleged Gateway Intents permissions is needed for the bot on Discord. If not set, MeshCentral will show an error when trying to connect to Discord.</p>
|
||
<p><img alt="" src="../messaging/images/MC2-Discord1.png" /></p>
|
||
<p>Discord integration requires that MeshCentral be run on NodeJS v17 or higher. Once you have the Discord bot login token, the config.json Discord configuration looks like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"messaging"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"discord"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"serverurl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://discord.gg/xxxxxxxxx"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"token"</span><span class="p">:</span><span class="w"> </span><span class="s2">"xxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Once users will need to join the same Discord server as the bot, the optional "serverurl" can be used to give the users a URL link to join the server, this can be a server invitation link or some other URL with instructions.</p>
|
||
<h2 id="messaging-xmpp-setup">XMPP Setup</h2>
|
||
<p>For XMPP integration, you need to provide MeshCentral with a XMPP server, username and password so that MeshCentral can login and send notifications to users. You can get a XMPP account to any number of servers or start up your own XMPP server.</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"messaging"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"xmpp"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"service"</span><span class="p">:</span><span class="w"> </span><span class="s2">"xmppserver.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"credentials"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"username"</span><span class="p">:</span><span class="w"> </span><span class="s2">"username"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"password"</span><span class="p">:</span><span class="w"> </span><span class="s2">"password"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>An easy way to get setup with XMPP is to create a free account with <a href="https://chatterboxtown.us/">chatterboxtown.us</a> and then, setup MeshCentral with the service value set to "chatterboxtown.us" along with the username and password of you account. This can be done in minutes. Once setup, users will be able to setup and verify XMLL accounts and use this for notifications and 2FA verification.</p>
|
||
<h2 id="messaging-callmebot-setup">CallMeBot Setup</h2>
|
||
<p><img alt="" src="../messaging/images/MC2-CallMeBot3.png" /></p>
|
||
<p><a href="https://www.callmebot.com/">CallMeBot</a> is a free system that allows users to receive notifications on Signal Messenger, Whatsapp and Facebook Messenger. Enabling this feature is very simple, just enable it like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"messaging"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"callmebot"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Once enabled, users see the new "CallMeBot" option when trying to enable messaging in MeshCentral. They will need to follow specific instructions to enable CallMeBot to send notifications to their messaging application.</p>
|
||
<ul>
|
||
<li><a href="https://www.callmebot.com/blog/free-api-signal-send-messages/">Signal Messenger</a></li>
|
||
<li><a href="https://www.callmebot.com/blog/free-api-whatsapp-messages/">Whatsapp</a></li>
|
||
<li><a href="https://www.callmebot.com/blog/free-api-facebook-messenger/">Facebook Messenger</a></li>
|
||
<li><a href="https://www.callmebot.com/blog/telegram-text-messages/">Telegram</a></li>
|
||
</ul>
|
||
<p>Once the user has enabled their account, they can cut & paste the CallMeBot URI into MeshCentral to validate their account.</p>
|
||
<h2 id="messaging-pushover-setup">Pushover Setup</h2>
|
||
<p><a href="https://pushover.net/">Pushover</a> is another notification service that makes it's own mobile application. To get started, download the Pushover application and create an account then go to the https://pushover.net/ web site and setup a new application like this:</p>
|
||
<p><img alt="" src="../messaging/images/MC2-Pushover2.png" /></p>
|
||
<p>You can setup an application with a name and icon, then, once you get a application token you can add it to the config.json like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"messaging"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"pushover"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"token"</span><span class="p">:</span><span class="w"> </span><span class="s2">"xxxxxxxxxxxxxxxxxxxxx"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Once setup, the server will offer users the "Pushover" option when setting up messaging. Users will need to copy the Pushover user key into the dialog box to verify notifications are correct.</p>
|
||
<p><img alt="" src="../messaging/images/MC2-Pushover1.png" /></p>
|
||
<h2 id="messaging-ntfy-setup">ntfy setup</h2>
|
||
<p><a href="https://ntfy.sh/">ntfy</a> is a completely free notification service. You can enable the ntfy integration with the following config.json section:</p>
|
||
<p><div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"messaging"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"ntfy"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
No setup is reqired to enable this. When using ntfy, make sure you use a suffisently random topic name so that others can't guess the name and subscribe to it to receive your messages.</p>
|
||
<p>For <a href="https://ntfy.sh/docs/install/">self-hosting your own ntfy server</a> with <a href="https://ntfy.sh/docs/config/#access-control">ACL support</a></p>
|
||
<p>You can set <code>host</code> to the DNS name of your server, <code>userurl</code> to the url to provide to users to setup access to your server and <code>authorization</code> to the Basic base64 User+Pass authenttication for your server</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"messaging"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"ntfy"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"host"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myntfyserver.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"userurl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://myntfyserver.com/userhelp"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authorization"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Basic cGhpbDpteXBhc3M="</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p><img alt="" src="../messaging/images/MC2-Ntfy1.png" /></p>
|
||
<h2 id="messaging-zulip-setup">Zulip setup</h2>
|
||
<p>You can enable the MeshCentral <a href="https://zulip.com/">Zulip</a> integration with the following config.json section:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"messaging"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"zulip"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"site"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://api.zulip.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"email"</span><span class="p">:</span><span class="w"> </span><span class="s2">"your-bot@zulip.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"api_key"</span><span class="p">:</span><span class="w"> </span><span class="s2">"your_32_character_api_key"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<h2 id="messaging-slack-setup">Slack setup</h2>
|
||
<p><a href="https://slack.com/">Slack</a> integration is achieved by the use of Incoming Webhooks.
|
||
You can get started by following the Slack guide <a href="https://api.slack.com/messaging/webhooks">here</a> and getting your URL</p>
|
||
<p>Once you have your incoming webhooks url, You can enable the <a href="https://slack.com/">Slack</a> integration with the following config.json section</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"messaging"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"slack"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<h2 id="messaging-user-setup">User Setup</h2>
|
||
<p>Once one or more messaging systems are setup with MeshCentral, users will be able to register their handle and verify that they own that account by typing in a 6 digit code.</p>
|
||
<p><img alt="" src="../messaging/images/MC2-Telegram1.png" /></p>
|
||
<p>This verification is necessary so that MeshCentral does not send notifications to incorrect messaging accounts.</p>
|
||
<h2 id="messaging-administrator-management">Administrator Management</h2>
|
||
<p>When users setup a messaging account, a messaging bubble will show up next to their name in the "My Users" tab. You can also click on a user to see and edit it's messaging handle and message them. Currently MeshCentral can only send messages, no receive.</p>
|
||
<p><img alt="" src="../messaging/images/MC2-Telegram2.png" /></p>
|
||
<h2 id="messaging-two-factor-authentication">Two-Factor Authentication</h2>
|
||
<p>By default, messaging is used as a second factor for login when a user enabled a messaging account. Users will need to messaging icon on the login screen and can opt to receive a 6 digit code to login.</p>
|
||
<p><img alt="" src="../messaging/images/MC2-Telegram3.png" /></p>
|
||
<p>As an administrator you can turn off use of messaging for 2FA using the following settings in the config.json:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"devbox.mesh.meshcentral.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"My Server"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"passwordRequirements"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"msg2factor"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Notice the <code>msg2factor</code> is set to false. In this case, messaging can still be used for user notifications, but will not be offered as a 2FA option.</p>
|
||
<p>For administrators, login reports will show if "Messaging" was used as a second factor for a user login. You can see this in this report:</p>
|
||
<p><img alt="" src="../messaging/images/MC2-Telegram4.png" /></p></section><section class="print-page" id="meshcentral-customization" heading-number="3.15"><h1 id="meshcentral-customization-customization">Customization</h1>
|
||
<p>Whitelabeling your MeshCentral installation to personalize it to your company's brand, as well as having your own terms of use is one of the first things many people do after installation.</p>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/xUZ1w9RSKpQ" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<h2 id="meshcentral-customization-web-branding">Web Branding</h2>
|
||
<p>You can put your own logo on the top of the web page. To get started, get the file “logoback.png” from the folder “node_modules/meshcentral/public/images” and copy it to your “meshcentral-data” folder. In this example, we will change the name of the file “logoback.png” to “title-mycompany.png”. Then use any image editor to change the image and place your logo.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-38-51.jpg" /></p>
|
||
<p>Once done, edit the config.json file and set one or all of the following values:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Title"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Title2"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"TitlePicture"</span><span class="p">:</span><span class="w"> </span><span class="s2">"title-sample.png"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"loginPicture"</span><span class="p">:</span><span class="w"> </span><span class="s2">"logintitle-sample.png"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"welcomeText"</span><span class="p">:</span><span class="w"> </span><span class="s2">"This is sample text"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"welcomePicture"</span><span class="p">:</span><span class="w"> </span><span class="s2">"mainwelcome-04.jpg"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"welcomePictureFullScreen"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"siteStyle"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"nightMode"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"meshMessengerTitle"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Mesh Chat"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"meshMessengerPicture"</span><span class="p">:</span><span class="w"> </span><span class="s2">"chatimage.png"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"footer"</span><span class="p">:</span><span class="w"> </span><span class="s2">"This is a HTML string displayed at the bottom of the web page when a user is logged in."</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"loginfooter"</span><span class="p">:</span><span class="w"> </span><span class="s2">"This is a HTML string displayed at the bottom of the web page when a user is not logged in."</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
</code></pre></div>
|
||
<p>This will set the title and sub-title text to empty and set the background image to the new title picture file. You can now restart the server and take a look at the web page. Both the desktop and mobile sites will change.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-39-35.jpg" /></p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-39-42.jpg" /></p>
|
||
<p>The title image must a PNG image of size 450 x 66.</p>
|
||
<p>You can also customize the server icon in the “My Server” tab. By default, it’s a picture of a desktop with a padlock.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-40-00.jpg" /></p>
|
||
<p>If, for example, MeshCentral is running on a Raspberry Pi. You may want to put a different picture at this location. Just put a “server.jpg” file that is 200 x 200 pixels in the “meshcentral-data” folder. The time MeshCentral page is loaded, you will see the new image.</p>
|
||
<p><img alt="" src="../meshcentral/images/2022-05-19-00-40-13.jpg" /></p>
|
||
<p>This is great to personalize the look of the server within the web site.</p>
|
||
<h3 id="meshcentral-customization-customizing-web-icons">Customizing Web Icons</h3>
|
||
<p>MeshCentral lets you change the icons for different devices shown in the Web User Interface. To do this the proper way, you should make a new folder called <code>meshcentral-web</code> in the main directory, where you find other folders like <code>meshcentral-data</code>, <code>meshcentral-backup</code>, <code>meshcentral-files</code>, and <code>node-modules</code>. Inside <code>meshcentral-web</code>, make another folder named <code>public</code> and copy the entire <code>node_modules/meshcentral/public/images</code> folder into this new <code>meshcentral-web/public</code> folder and then edit the files in <code>meshcentral-web/public/images/</code>. This step is suggested because if MeshCentral updates, it might delete any changes in <code>node_modules</code>. But, changes in <code>meshcentral-web</code> will stay safe, and MeshCentral will use these files instead of the originals in <code>node_modules</code>.</p>
|
||
<p>To update device icons, you need to edit these files: <code>meshcentral-web/public/images/webp/iconsXX.webp</code> (<code>icons16.webp</code>, <code>icons32.webp</code>, <code>icons50.webp</code>, <code>icons100.webp</code>), and <code>meshcentral-web/public/images/iconsXX.png</code> (<code>icons16.png</code>, <code>icons32.png</code>, <code>icons50.png</code>, <code>icons64.png</code>, <code>icons100.png</code>) and the corresponding <code>meshcentral-web/public/images/icons256-X-1.png</code>. Make sure to keep the resolution of these files as it is. </p>
|
||
<p>By following these steps, you can customize any icon in MeshCentral. Just find and change the corresponding image files in the <code>meshcentral-web/public/images</code> folder. Similarly, you can also move other folders from <code>node_modules/meshcentral</code> to <code>meshcentral-web</code> while keeping the original folder structure. This allows you to modify other parts of MeshCentral too, like the <code>.handlebars</code> templates for the web interface. Simply copy files from <code>node_modules/meshcentral/views</code> to <code>meshcentral-web/views</code> and make your changes in <code>meshcentral-web</code>. This lets you match MeshCentral's look to your company's brand or your own style. <br />
|
||
<img alt="" src="../meshcentral/images/custom-web-icons.jpg" /> </p>
|
||
<h3 id="meshcentral-customization-customizing-web-style">Customizing Web Style</h3>
|
||
<p>MeshCentral gives you the flexibility to override some or all of the web interface. An easy way to modify the style is to do the following:</p>
|
||
<ol>
|
||
<li>Create the file <code>custom.css</code> under <code>meshcentral-web/public/styles</code>. See <a href="#meshcentral-customization-customizing-web-style">above</a> for more information on <code>meshcentral-web</code>.</li>
|
||
<li>Anything added to this file will override the default stylesheets. </li>
|
||
</ol>
|
||
<p>An example file:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">#</span><span class="nn">masthead</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="k">background-color</span><span class="p">:</span><span class="w"> </span><span class="kc">red</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
|
||
<span class="p">#</span><span class="nn">page_leftbar</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="k">background</span><span class="p">:</span><span class="w"> </span><span class="nb">linear-gradient</span><span class="p">(</span><span class="kc">to</span><span class="w"> </span><span class="kc">bottom</span><span class="p">,</span><span class="w"> </span><span class="mh">#104893</span><span class="w"> </span><span class="mi">0</span><span class="kt">%</span><span class="p">,</span><span class="kc">green</span><span class="w"> </span><span class="mi">100</span><span class="kt">%</span><span class="p">)</span>
|
||
<span class="p">}</span>
|
||
|
||
<span class="p">#</span><span class="nn">footer</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="k">background-color</span><span class="p">:</span><span class="w"> </span><span class="kc">green</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Gives:</p>
|
||
<p><img alt="Custom Style" src="../meshcentral/images/custom-style-example.png" /></p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
</div>
|
||
<p>You can of course override the stylesheets by directly copying them into <code>meshcentral-web/public/styles</code> but run the risk that future updates to those files in MeshCentral will be masked. <code>custom.css</code> is guaranteed to be loaded last on every page and will contain no content by default which means upgrades will work as normal. </p>
|
||
<h3 id="meshcentral-customization-customizing-agent-invitation">Customizing Agent Invitation</h3>
|
||
<p>Agents can be invited by public link or via email. <a href="#meshcentral-assistant-agent-invitation">Click Here</a> to see details. </p>
|
||
<h2 id="meshcentral-customization-agent-branding">Agent Branding</h2>
|
||
<p>You can customize the Agent to add your own logo, change the title bar, install text, the service name, or even colors!</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The Customization must be done FIRST and BEFORE you deploy your agents! Once the agents have been deployed, any customization made afterwards, will not sync! This is because the setup files are customized on the fly, then when you install the agents, the exe and .msh file with the customizations in are copied over to the required folder, so you will need to reinstall the agent for agent customizations to take effect.</p>
|
||
</div>
|
||
<p><img alt="" src="../meshcentral/images/2022-08-24-06-42-40.jpg" /></p>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"agentCustomization"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"displayName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MeshCentral Agent"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Mesh Agent background service"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"companyName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Mesh Agent Company"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"serviceName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Mesh Agent Service"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"installText"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Text string to show in the agent installation dialog box"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"image"</span><span class="p">:</span><span class="w"> </span><span class="s2">"mylogo.png"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"fileName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"meshagent"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"foregroundColor"</span><span class="p">:</span><span class="w"> </span><span class="s2">"#FFA500"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"backgroundColor"</span><span class="p">:</span><span class="w"> </span><span class="s2">"#EE82EE"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p><img alt="agent icon" src="../meshcentral/images/agentico.jpg" /></p>
|
||
<h2 id="meshcentral-customization-terms-of-use">Terms of use</h2>
|
||
<p>You can change the terms of use of the web site by adding a “terms.txt” file in the “meshcentral-data” folder. The file can include HTML markup. Once set, the server does not need to be restarted, the updated terms.txt file will get used the next time it’s requested.</p>
|
||
<p>For example, placing this in “terms.txt”</p>
|
||
<div class="highlight"><pre><span></span><code><br />
|
||
This is a <b>test file</b>.
|
||
</code></pre></div>
|
||
<p>Will show this on the terms of use web page.</p></section><section class="print-page" id="meshcentral-openidconnectstrategy" heading-number="3.16"><h1 id="meshcentral-openidconnectstrategy-using-the-openid-connect-strategy-on-meshcentral">Using the OpenID Connect Strategy on MeshCentral</h1>
|
||
<h2 id="meshcentral-openidconnectstrategy-overview">Overview</h2>
|
||
<h3 id="meshcentral-openidconnectstrategy-introduction">Introduction</h3>
|
||
<p>There is a lot of information to go over, but first, why OpenID Connect?</p>
|
||
<p>Esentially its because its both based on a industry standard authorization protocol, and is becoming an industry standard authentication protocol. Put simply it's reliable and reusable, and we use OpenID Connect for exactly those reasons, almost every everyone does, and we want to be able to integrate with almost anyone. This strategy allows us to expand the potential of MeshCentral through the potential of OpenID Connect.</p>
|
||
<p>In this document, we will learn about the OpenID Connect specification at a high level, and then use that information to configure the OpenID Connect strategy for MeshCentral using a generic OpenID Connect compatible IdP. After that we will go over some advanced configurations and then continue by explaining how to use the new presets for popular IdPs, specifically Google or Azure. Then we will explore the configuration and usage of the groups feature.</p>
|
||
<blockquote>
|
||
<p>ATTENTION: As of MeshCentral <code>v1.1.22</code> there are multiple config options being depreciated. Using any of the old configs will only generate a warning in the authlog and will not stop you from using this strategy at this time. If there is information found in both the new and old config locations the new config location will be used. We will go over the specifics later, now lets jump in.</p>
|
||
</blockquote>
|
||
<h3 id="meshcentral-openidconnectstrategy-chart-of-frequently-used-terms-and-acronyms">Chart of Frequently Used Terms and Acronyms</h3>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Term</th>
|
||
<th>AKA</th>
|
||
<th>Descriptions</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>OAuth 2.0</td>
|
||
<td>OAuth2</td>
|
||
<td>OAuth 2.0 is the industry-standard protocol for user <em>authorization</em>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>OpenID Connect</td>
|
||
<td>OIDC</td>
|
||
<td>Identity layer built on top of OAuth2 for user <em>authentication</em>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Identity Provider</td>
|
||
<td>IdP</td>
|
||
<td>The <em>service used</em> to provide authentication and authorization.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Preset Configs</td>
|
||
<td>Presets</td>
|
||
<td>Set of <em>pre-configured values</em> to allow some specific IdPs to connect correctly.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>OAuth2 Scope</td>
|
||
<td>Scope</td>
|
||
<td>A flag <em>requesting access</em> to a specific resource or endpoint</td>
|
||
</tr>
|
||
<tr>
|
||
<td>OIDC Claim</td>
|
||
<td>Claim</td>
|
||
<td>A <em>returned property</em> in the user info provided by your IdP</td>
|
||
</tr>
|
||
<tr>
|
||
<td>User Authentication</td>
|
||
<td>AuthN</td>
|
||
<td>Checks if you <em>are who you say you are</em>. Example: Username and password authentication</td>
|
||
</tr>
|
||
<tr>
|
||
<td>User Authorization</td>
|
||
<td>AuthZ</td>
|
||
<td>Check if you have the <em>permissions</em> required to access a specific resource or endpoint</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h3 id="meshcentral-openidconnectstrategy-openid-connect-technology-overview">OpenID Connect Technology Overview</h3>
|
||
<p>OpenID Connect is a simple identity layer built on top of the OAuth2 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an “Authorization Server”, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.</p>
|
||
<p>OpenID Connect allows clients of all types, including Web-based, mobile, and JavaScript clients, to request and receive information about authenticated sessions and end-users. The specification suite is extensible, allowing participants to use optional features such as encryption of identity data, discovery of OpenID Providers, and logout, when it makes sense for them.</p>
|
||
<p>That description was straight from <a href="https://openid.net/connect/">OpenID Connect Documentation</a>, but basically, OAuth2 is the foundation upon which OpenID Connect was built, allowing for wide ranging compatability and interconnection. OpenID Connect appends the secure user <em>authentication</em> OAuth2 is known for, with user <em>authorization</em> by allowing the request of additional <em>scopes</em> that provide additional <em>claims</em> or access to API's in an easily expandable way.</p>
|
||
<h3 id="meshcentral-openidconnectstrategy-annotations">Annotations</h3>
|
||
<h4 id="meshcentral-openidconnectstrategy-own-idp-ca-and-docker">Own IDP, CA and Docker</h4>
|
||
<p>If you operate your own identity provider, your own certification authority and MeshCentral via Docker, it is necessary to provide the complete certificate chain, otherwise NodeJS (in particular the openid-client module) will refuse the connection to the IDP server. </p>
|
||
<p>The following errors can be found in the log file:</p>
|
||
<blockquote>
|
||
<p>OIDC: Discovery failed.</p>
|
||
<p>UNABLE_TO_GET_ISSUER_CERT_LOCALLY</p>
|
||
</blockquote>
|
||
<p>To solve this problem, the certificate chain in PEM format must be placed in the data directory and the following entry must be added to the docker-compose.yml file in the “environment” section:
|
||
<div class="highlight"><pre><span></span><code> environment:
|
||
- NODE_EXTRA_CA_CERTS=/opt/meshcentral/meshcentral-data/chain.pem
|
||
</code></pre></div></p>
|
||
<h2 id="meshcentral-openidconnectstrategy-basic-config">Basic Config</h2>
|
||
<h3 id="meshcentral-openidconnectstrategy-introduction_1"><em>Introduction</em></h3>
|
||
<p>Generally, if you are using an IdP that supports OIDC, you can use a very basic configuration to get started, and if needed, add more specific or advanced configurations later. Here is what your config file will look like with a basic, generic, configuration.</p>
|
||
<h3 id="meshcentral-openidconnectstrategy-basic-config-file-example"><em>Basic Config File Example</em></h3>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"mesh.your.domain"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"sqlite3"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"MeshCentral"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"title2"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Your sub-title"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authStrategies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"oidc"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"issuer"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2d5685c5-0f32-4c1f-9f09-c60e0dbc948a"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientsecret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"7PiGSLSLL4e7NGi67KM229tfK7Z7TqzQ"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"newAccounts"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>As you can see, this is roughly the same as all the other OAuth2 based authentication strategies. These are the basics you need to get started, however, if you plan to take advantage of some of the more advanced features provided by this strategy, you'll need to keep reading.</p>
|
||
<p>In this most basic of setups, you only need the URL of the issuer, as well as a client ID and a client secret. Notice in this example that the callback URL (or client redirect uri) is not configured, thats because MeshCentral will use <code>https://mesh.your.domain/auth-oidc-callback</code> as the default. Once you've got your configuration saved, restart MeshCentral and you should see an OpenID Connect Single Sign-on button on the login screen.</p>
|
||
<blockquote>
|
||
<p>WARNING: The redirect endpoint must EXACTLY match the value provided to your IdP or your will deny the connection.</p>
|
||
<p>ATTENTION: You are required to configure the cert property in the settings section for the default domain, and configure the dns property under each additional domain.</p>
|
||
</blockquote>
|
||
<h2 id="meshcentral-openidconnectstrategy-advanced-options">Advanced Options</h2>
|
||
<h3 id="meshcentral-openidconnectstrategy-overview_1">Overview</h3>
|
||
<p>There are plenty of options at your disposal if you need them. In fact, you can configure any property that node-openid-client supports. The openid-client module supports far more customization than I know what to do with, if you want to know more check out <a href="https://github.com/panva/node-openid-client">node-openid-client on GitHub</a> for expert level configuration details. There are plenty of things you can configure with this strategy and there is a lot of decumentation behind the tools used to make this all happen. I strongly recommend you explore the <a href="https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json">config schema</a>, and if you have a complicated config maybe check out the <a href="https://github.com/panva/node-openid-client/blob/main/docs/README.md">openid-client readme</a>. Theres a list of resources at the end if you want more information on any specific topics. In the meantime, let’s take a look at an example of what your config file could look with a slightly more complicated configuration, including multiple manually defined endpoints.</p>
|
||
<h4 id="meshcentral-openidconnectstrategy-advanced-config-file-example"><em>Advanced Config File Example</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"mesh.your.domain"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"redirPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">80</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"AgentPong"</span><span class="p">:</span><span class="w"> </span><span class="mi">300</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"TLSOffload"</span><span class="p">:</span><span class="w"> </span><span class="s2">"192.168.1.50"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"SelfUpdate"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"AllowFraming"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"sqlite3"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"WebRTC"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Mesh"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"title2"</span><span class="p">:</span><span class="w"> </span><span class="s2">".Your.Domain"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"orphanAgentUser"</span><span class="p">:</span><span class="w"> </span><span class="s2">"~oidc:e48f8ef3-a9cb-4c84-b6d1-fb7d294e963c"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authStrategies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"oidc"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"issuer"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"issuer"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authorization_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://auth.your.domain/auth-endpoint"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"token_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://tokens.sso.your.domain/token-endpoint"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"end_session_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain/logout"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"jwks_uri"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain/jwks-uri"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"client"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"client_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"110d5612-0822-4449-a057-8a0dbe26eca5"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"client_secret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"4TqST46K53o3Z2Q88p39YwR6YwJb7Cka"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"redirect_uri"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://mesh.your.domain/auth-oidc-callback"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"post_logout_redirect_uri"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://mesh.your.domain/login"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"token_endpoint_auth_method"</span><span class="p">:</span><span class="w"> </span><span class="s2">"client_secret_post"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"response_types"</span><span class="p">:</span><span class="w"> </span><span class="s2">"code"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"custom"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"scope"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"openid"</span><span class="p">,</span><span class="w"> </span><span class="s2">"profile"</span><span class="p">,</span><span class="w"> </span><span class="s2">"read.EmailAlias"</span><span class="p">,</span><span class="w"> </span><span class="s2">"read.UserProfile"</span><span class="w"> </span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"preset"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"groups"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"recursive"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"required"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"Group1"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Group2"</span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"siteadmin"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"GroupA"</span><span class="p">,</span><span class="w"> </span><span class="s2">"GroupB"</span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"revokeAdmin"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"sync"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span>
|
||
<span class="w"> </span><span class="nt">"filter"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"Group1"</span><span class="p">,</span><span class="w"> </span><span class="s2">"GroupB"</span><span class="p">,</span><span class="w"> </span><span class="s2">"OtherGroup"</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"claim"</span><span class="p">:</span><span class="w"> </span><span class="s2">"GroupClaim"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"scope"</span><span class="p">:</span><span class="w"> </span><span class="s2">"read.GroupMemberships"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"logouturl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain/logout?r=https://mesh.your.domain/login"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"newAccounts"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="p">{</span><span class="err">...</span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-openidconnectstrategy-issuer-options">"Issuer" Options</h3>
|
||
<h4 id="meshcentral-openidconnectstrategy-introduction_2"><em>Introduction</em></h4>
|
||
<p>In the advanced example config above, did you notice that the issuer property has changed from a <em>string</em> to an <em>object</em> compared to the basic example? This not only allows for much a much smaller config footprint when advanced issuer options are not required, it successfully fools you in to a false sense of confidence early on in this document. If you are manually configuring the issuer endpoints, keep in mind that MeshCentral will still attempt to discover <strong>ALL</strong> issuer information. Obviously if you manually configure an endpoint, it will be used even if the discovered information is different from your config. </p>
|
||
<blockquote>
|
||
<p>NOTE: If you are using a preset, you dont need to define an issuer. If you do, the predefined information will be ignored.</p>
|
||
</blockquote>
|
||
<h4 id="meshcentral-openidconnectstrategy-common-config-chart"><em>Common Config Chart</em></h4>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th>
|
||
<th>Description</th>
|
||
<th>Default</th>
|
||
<th>Example</th>
|
||
<th>Required</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>issuer</code></td>
|
||
<td>The primary URI that represents your Identity Providers authentication endpoints.</td>
|
||
<td>N/A</td>
|
||
<td><code>"issuer": "https://sso.your.domain"</code><br/><code>"issuer": { "issuer": "https://sso.your.domain" }</code></td>
|
||
<td>Unless using preset.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h4 id="meshcentral-openidconnectstrategy-advanced-config-example"><em>Advanced Config Example</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"issuer"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"issuer"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authorization_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://auth.your.domain/auth-endpoint"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"token_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://tokens.sso.your.domain/token-endpoint"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"end_session_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain/logout"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"jwks_uri"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain/jwks-uri"</span>
|
||
<span class="p">},</span>
|
||
</code></pre></div>
|
||
<h4 id="meshcentral-openidconnectstrategy-required-and-commonly-used-configs"><em>Required and Commonly Used Configs</em></h4>
|
||
<p>The <code>issuer</code> property in the <code>issuer</code> object is the only one required, and its only required if you aren't using a preset. Besides the issuer, these are mostly options related to the endpoints and their configuration. The schema below looks intimidating but it comes down to being able to support any IdP. Setting the issuer, and end_session_endpoint are the two main ones you want to setup.</p>
|
||
<h4 id="meshcentral-openidconnectstrategy-schema"><em>Schema</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"issuer"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"string"</span><span class="p">,</span><span class="s2">"object"</span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Issuer options. Requires issuer URI (issuer.issuer) to discover missing information unless using preset"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"properties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"issuer"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="p">,</span><span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"URI of the issuer."</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"authorization_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"token_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"jwks_uri"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"userinfo_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"revocation_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"introspection_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"end_session_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"URI to direct users to when logging out of MeshCentral."</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="s2">"this.issuer/logout"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"registration_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"token_endpoint_auth_methods_supported"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"token_endpoint_auth_signing_alg_values_supported"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"introspection_endpoint_auth_methods_supported"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"introspection_endpoint_auth_signing_alg_values_supported"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"revocation_endpoint_auth_methods_supported"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"revocation_endpoint_auth_signing_alg_values_supported"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"request_object_signing_alg_values_supported"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"mtls_endpoint_aliases"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="s2">"object"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"properties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"token_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"userinfo_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"revocation_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"introspection_endpoint"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"additionalProperties"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="p">},</span>
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-openidconnectstrategy-client-options">"Client" Options</h3>
|
||
<h4 id="meshcentral-openidconnectstrategy-introduction_3"><em>Introduction</em></h4>
|
||
<p>There are just about as many option as possible here since openid-client also provides a Client class, because of this you are able to manually configure the client how ever you need. This includes setting your redirect URI to any available path, for example, if I was using the "google" preset and wanted to have Google redirect me back to "https://mesh.your.domain/oauth2/oidc/redirect/givemebackgooglemusicyoujerks", MeshCentral will now fully support you in that. One of the other options is the post logout redirect URI, and it is exactly what it sounds like. After MeshCentral logs out a user using the IdPs end session endpoint, it send the post logout redirect URI to your IdP to forward the user back to MeshCentral or to an valid URI such as a homepage.</p>
|
||
<blockquote>
|
||
<p>NOTE: The client object is required, however an exception would be with using old configs, which will be discussed later.</p>
|
||
</blockquote>
|
||
<h4 id="meshcentral-openidconnectstrategy-common-configs"><em>Common Configs</em></h4>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th>
|
||
<th>Description</th>
|
||
<th>Default</th>
|
||
<th>Example</th>
|
||
<th>Required</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>client_id</code></td>
|
||
<td>The client ID provided by your Identity Provider (IdP)</td>
|
||
<td>N/A</td>
|
||
<td><code>bdd6aa4b-d2a2-4ceb-96d3-b3e23cd17678</code></td>
|
||
<td><code>true</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>client_secret</code></td>
|
||
<td>The client secret provided by your Identity Provider (IdP)</td>
|
||
<td>N/A</td>
|
||
<td><code>vUg82LJ322rp2bvdzuVRh3dPn3oVo29m</code></td>
|
||
<td><code>true</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>redirect_uri</code></td>
|
||
<td>"URI your IdP sends you after successful authorization.</td>
|
||
<td><code>https://mesh.your.domain/auth-oidc-callback</code></td>
|
||
<td><code>https://mesh.your.domain/oauth2/oidc/redirect</code></td>
|
||
<td><code>false</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>post_logout_redirect_uri</code></td>
|
||
<td>URI for your IdP to send you after logging out of IdP via MeshCentral.</td>
|
||
<td><code>https://mesh.your.domain/login</code></td>
|
||
<td><code>https://site.your.other.domain/login</code></td>
|
||
<td><code>false</code></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h4 id="meshcentral-openidconnectstrategy-advanced-config-example_1"><em>Advanced Config Example</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"client"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"client_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"00b3875c-8d82-4238-a8ef-25303fa7f9f2"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"client_secret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"7PP453H577xbFDCqG8nYEJg8M3u8GT8F"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"redirect_uri"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://mesh.your.domain/auth-oidc-callback"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"post_logout_redirect_uri"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://mesh.your.domain/login"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"token_endpoint_auth_method"</span><span class="p">:</span><span class="w"> </span><span class="s2">"client_secret_post"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"response_types"</span><span class="p">:</span><span class="w"> </span><span class="s2">"code"</span>
|
||
<span class="p">},</span>
|
||
</code></pre></div>
|
||
<h4 id="meshcentral-openidconnectstrategy-required-and-commonly-used-configs_1"><em>Required and Commonly Used Configs</em></h4>
|
||
<p>There are many available options you can configure but most of them go unused. Although there are a few <em>commonly used</em> properties. The first two properties, <code>client_id</code> and <code>client_secret</code> are required. The next one <code>redirect_uri</code> is used to setup a custom URI for the redirect back to MeshCentral after being authenicated by your IdP. The <code>post_logout_redirect_uri</code> property is used to tell your IdP where to send you after being logged out. These work in conjunction with the issuers <code>end_session_url</code> to automatically fill in any blanks in the config.</p>
|
||
<h4 id="meshcentral-openidconnectstrategy-schema_1"><em>Schema</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"client"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"object"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"OIDC Client Options"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"properties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"client_id"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"REQUIRED: The client ID provided by your Identity Provider (IdP)"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"client_secret"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"REQUIRED: The client secret provided by your Identity Provider (IdP)"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"redirect_uri"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"URI your IdP sends you after successful authorization. This must match what is listed with your IdP. (Default is https://[currentHost][currentPath]/auth-oidc-callback)"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"post_logout_redirect_uri"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"URI for your IdP to send you after logging out of IdP via MeshCentral."</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https:[currentHost][currentPath]/login"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"id_token_signed_response_alg"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="s2">"RS256"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"id_token_encrypted_response_alg"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"id_token_encrypted_response_enc"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"userinfo_signed_response_alg"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"userinfo_encrypted_response_alg"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"userinfo_encrypted_response_enc"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"response_types"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="s2">"array"</span><span class="p">],</span><span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"code"</span><span class="p">]</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"default_max_age"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"number"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"require_auth_time"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"boolean"</span><span class="p">,</span><span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w"> </span><span class="p">},</span><span class="w"> </span>
|
||
<span class="w"> </span><span class="nt">"request_object_signing_alg"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"request_object_encryption_alg"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"request_object_encryption_enc"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"token_endpoint_auth_method"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="s2">"client_secret_basic"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"enum"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"none"</span><span class="p">,</span><span class="w"> </span><span class="s2">"client_secret_basic"</span><span class="p">,</span><span class="w"> </span><span class="s2">"client_secret_post"</span><span class="p">,</span><span class="w"> </span><span class="s2">"client_secret_jwt"</span><span class="p">,</span><span class="w"> </span><span class="s2">"private_key_jwt"</span><span class="w"> </span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">},</span><span class="w"> </span>
|
||
<span class="w"> </span><span class="nt">"introspection_endpoint_auth_method"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="s2">"client_secret_basic"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"enum"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"none"</span><span class="p">,</span><span class="w"> </span><span class="s2">"client_secret_basic"</span><span class="p">,</span><span class="w"> </span><span class="s2">"client_secret_post"</span><span class="p">,</span><span class="w"> </span><span class="s2">"client_secret_jwt"</span><span class="p">,</span><span class="w"> </span><span class="s2">"private_key_jwt"</span><span class="w"> </span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">},</span><span class="w"> </span>
|
||
<span class="w"> </span><span class="nt">"revocation_endpoint_auth_method"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="s2">"client_secret_basic"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"enum"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"none"</span><span class="p">,</span><span class="w"> </span><span class="s2">"client_secret_basic"</span><span class="p">,</span><span class="w"> </span><span class="s2">"client_secret_post"</span><span class="p">,</span><span class="w"> </span><span class="s2">"client_secret_jwt"</span><span class="p">,</span><span class="w"> </span><span class="s2">"private_key_jwt"</span><span class="w"> </span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">},</span><span class="w"> </span>
|
||
<span class="w"> </span><span class="nt">"token_endpoint_auth_signing_alg"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"introspection_endpoint_auth_signing_alg"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"revocation_endpoint_auth_signing_alg"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"tls_client_certificate_bound_access_tokens"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"boolean"</span><span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"required"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"client_id"</span><span class="p">,</span><span class="w"> </span><span class="s2">"client_secret"</span><span class="w"> </span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"additionalProperties"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="p">},</span>
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-openidconnectstrategy-custom-options">"Custom" Options</h3>
|
||
<h4 id="meshcentral-openidconnectstrategy-introduction_4"><em>Introduction</em></h4>
|
||
<p>These are all the options that dont fit with the issuer or client, including the presets. The presets define more than just the issuer URL used in discovery, they also define API endpoints, and specific ways to assemble your data. You are able to manually override most of the effects of the preset, but not all. You are able to manually configure the <em>scope</em> of the authorization request though, as well as choose which claims to use if your IdP uses something other than the defaults.</p>
|
||
<blockquote>
|
||
<p>NOTE: The scope must be a string, an array of strings, or a space separated list of scopes as a single string.</p>
|
||
</blockquote>
|
||
<h4 id="meshcentral-openidconnectstrategy-common-config-chart_1"><em>Common Config Chart</em></h4>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th>
|
||
<th>Description</th>
|
||
<th>Default</th>
|
||
<th>Example</th>
|
||
<th>Required</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>scope</code></td>
|
||
<td>A list of scopes to request from the issuer.</td>
|
||
<td><code>"openid profile email"</code></td>
|
||
<td><code>["openid", "profile"]</code></td>
|
||
<td><code>false</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>claims</code></td>
|
||
<td>A group of claims to use instead of the defaults</td>
|
||
<td>Defauts to name of property except that <code>uuid</code> used <code>sub</code></td>
|
||
<td><code>"claims": {"uuid": "unique_name"}</code></td>
|
||
<td><code>false</code></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h4 id="meshcentral-openidconnectstrategy-advanced-config-example_2"><em>Advanced Config Example</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"custom"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"scope"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"openid"</span><span class="p">,</span><span class="w"> </span><span class="s2">"profile"</span><span class="p">,</span><span class="w"> </span><span class="s2">"read.EmailAlias"</span><span class="p">,</span><span class="w"> </span><span class="s2">"read.UserProfile"</span><span class="w"> </span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"preset"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"claims"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"nameOfUser"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"email"</span><span class="p">:</span><span class="w"> </span><span class="s2">"publicEmail"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">},</span>
|
||
</code></pre></div>
|
||
<blockquote>
|
||
<p>NOTE: You can <code>preset</code> to null if you want to explicitly disable presets.</p>
|
||
</blockquote>
|
||
<h4 id="meshcentral-openidconnectstrategy-required-and-commonly-used-configs_2"><em>Required and Commonly Used Configs</em></h4>
|
||
<p>As should be apparent by the name alone, the custom property does not need to be configured and is used for optional or advanced configurations. With that said, lets look at few common options strategy will default to using the <code>openid</code>, <code>profile</code>, and <code>email</code> scopes to gather the required information about the user, if your IdP doesn't support or require all these, you can set up the scope manually. Combine that with the ability to set the group scope and you can end up with an entirely custom scope being sent to your IdP. Not to mention the claims property, which allows you to pick and choose what claims to use to gather your data in case you have issues with any of the default behaviors of OpenID Connect and your IdP. This is also where you would set the preset and any values required by the presets.</p>
|
||
<h4 id="meshcentral-openidconnectstrategy-schema_2"><em>Schema</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"custom"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"object"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"properties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"scope"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="s2">"array"</span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"A list of scopes to request from the issuer."</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="s2">"openid profile email"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"examples"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"openid"</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="s2">"openid"</span><span class="p">,</span><span class="w"> </span><span class="s2">"profile"</span><span class="p">],</span><span class="w"> </span><span class="s2">"openid profile email"</span><span class="p">,</span><span class="w"> </span><span class="s2">"openid profile email groups"</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"claims"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"object"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"properties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"email"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"uuid"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"preset"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"enum"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"azure"</span><span class="p">,</span><span class="w"> </span><span class="s2">"google"</span><span class="p">]},</span>
|
||
<span class="w"> </span><span class="nt">"tenant_id"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"REQUIRED FOR AZURE PRESET: Tenantid for Azure"</span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"customer_id"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"REQUIRED FOR GOOGLE PRESET IF USING GROUPS: Customer ID from Google, should start with 'C'."</span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"additionalProperties"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="p">},</span>
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-openidconnectstrategy-groups-options">"Groups" Options</h3>
|
||
<h4 id="meshcentral-openidconnectstrategy-introduction_5"><em>Introduction</em></h4>
|
||
<p>The groups option allows you to use the groups you already have with your IdP in MeshCentral in a few ways. First you can set a group that the authorized user must be in to sign in to MeshCentral. You can also allow users with the right memberships automatic admin privlidges, and there is even an option to revoke privlidges if the user is NOT in the admin group. Besides these filters, you can filter the sync property to mirror only certain groups as MeshCentral User Groups, dynamically created as the user logs in. You can of course simply enable sync and mirror all groups from your IdP as User Groups. Additionally you can define the scope and claim of the groups for a custom setup, again allowing for a wide range of IdPs to be used, even without a preset.</p>
|
||
<h4 id="meshcentral-openidconnectstrategy-common-config-chart_2"><em>Common Config Chart</em></h4>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th>
|
||
<th>Description</th>
|
||
<th>Default</th>
|
||
<th>Example</th>
|
||
<th>Required</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>sync</code></td>
|
||
<td>Allows you to mirror user groups from your IdP.</td>
|
||
<td><code>false</code></td>
|
||
<td><code>"sync": { "filter": ["Group1", "Group2"] }</code><br/><code>"sync": true</code></td>
|
||
<td><code>false</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>required</code></td>
|
||
<td>Access is only granted to users who are a member<br/>of at least one of the listed required groups.</td>
|
||
<td><code>undefined</code></td>
|
||
<td><code>"required": ["Group1", "Group2"]</code></td>
|
||
<td><code>false</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>siteadmin</code></td>
|
||
<td>Full site admin priviledges will be granted to users<br/>who are a member of at least one of the listed admin groups</td>
|
||
<td><code>undefined</code></td>
|
||
<td><code>"siteadmin": ["Group1", "Group2"]</code></td>
|
||
<td><code>false</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>revokeAdmin</code></td>
|
||
<td>If true, admin privileges will be revoked from users<br/>who arent a member of at least one of the listed admin groups.</td>
|
||
<td><code>true</code></td>
|
||
<td><code>"revokeAdmin": false</code></td>
|
||
<td><code>false</code></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h4 id="meshcentral-openidconnectstrategy-advanced-config-example_3"><em>Advanced Config Example</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"groups"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"recursive"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"required"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"Group1"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Group2"</span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"siteadmin"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"GroupA"</span><span class="p">,</span><span class="w"> </span><span class="s2">"GroupB"</span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"revokeAdmin"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"sync"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span>
|
||
<span class="w"> </span><span class="nt">"filter"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"Group1"</span><span class="p">,</span><span class="w"> </span><span class="s2">"GroupB"</span><span class="p">,</span><span class="w"> </span><span class="s2">"OtherGroup"</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"claim"</span><span class="p">:</span><span class="w"> </span><span class="s2">"GroupClaim"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"scope"</span><span class="p">:</span><span class="w"> </span><span class="s2">"read.GroupMemberships"</span>
|
||
<span class="p">},</span>
|
||
</code></pre></div>
|
||
<h4 id="meshcentral-openidconnectstrategy-required-and-commonly-used-configs_3"><em>Required and Commonly Used Configs</em></h4>
|
||
<p>As you can see in the schema below, there aren't any required properties in the groups object, however there are some commonly used ones. The first, and maybe most commonly used one, is the sync property. The sync property mirrors IdP provided groups into MeshCentral as user groups. You can then configure access as required to those groups, and as users log in, they will be added to the now existing groups if they are a member. You also have other options like using a custom <em>scope</em> or <em>claim</em> to get your IdP communicating with MeshCentral properly, without the use of preset configs. You also can set the required property if you need to limit authorization to users that are a member of at least one of the groups you set. or the siteadmin property to grant admin privilege, with the revokeAdmin property available to allow revoking admin rights also.</p>
|
||
<h4 id="meshcentral-openidconnectstrategy-schema_3"><em>Schema</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"groups"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"object"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"properties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"recursive"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"boolean"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"When true, the group memberships will be scanned recursively."</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"required"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="s2">"array"</span><span class="w"> </span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Access is only granted to users who are a member of at least one of the listed required groups."</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"siteadmin"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="s2">"array"</span><span class="w"> </span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Full site admin priviledges will be granted to users who are a member of at least one of the listed admin groups."</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"revokeAdmin"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"boolean"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"If true, admin privileges will be revoked from users who are NOT a member of at least one of the listed admin groups."</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"sync"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"boolean"</span><span class="p">,</span><span class="w"> </span><span class="s2">"object"</span><span class="w"> </span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"If true, all groups found during user login are mirrored into MeshCentral user groups."</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"properties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"filter"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="s2">"array"</span><span class="w"> </span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Only groups listed here are mirrored into MeshCentral user groups."</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"scope"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="s2">"groups"</span><span class="p">,</span><span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Custom scope to use."</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"claim"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="s2">"groups"</span><span class="p">,</span><span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Custom claim to use."</span><span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"additionalProperties"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<h2 id="meshcentral-openidconnectstrategy-preset-openid-connect-configurations">Preset OpenID Connect Configurations</h2>
|
||
<h3 id="meshcentral-openidconnectstrategy-overview_2">Overview</h3>
|
||
<h4 id="meshcentral-openidconnectstrategy-common-config-chart_3"><em>Common Config Chart</em></h4>
|
||
<blockquote>
|
||
<p>NOTE: All settings directly related to presets are in the custom section of the config.</p>
|
||
</blockquote>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th>
|
||
<th>Description</th>
|
||
<th>Example</th>
|
||
<th>Required</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>preset</code></td>
|
||
<td>Manually enable the use of a preset.</td>
|
||
<td><code>"preset": "google"</code><br/><code>"preset": "azure"</code></td>
|
||
<td><code>false</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>customer_id</code></td>
|
||
<td>Customer ID of the Google Workspaces instace you<br/>plan to use with the groups feature.</td>
|
||
<td><code>"customer_id": ["Group1", "Group2"]</code></td>
|
||
<td>If <code>google</code> preset is used with <code>groups</code> feature.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>tenant_id</code></td>
|
||
<td>Tenant ID from Azure AD, this is required to use<br/>the <code>azure</code> preset as it is part of the issuer url.</td>
|
||
<td><code>"tenant_id": "46a6022g-4h33-1451-h1rc-08102ga3b5e4"</code></td>
|
||
<td>If <code>Azure</code> preset is being used.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h3 id="meshcentral-openidconnectstrategy-google-preset">Google Preset</h3>
|
||
<h4 id="meshcentral-openidconnectstrategy-prerequisites"><em>Prerequisites</em></h4>
|
||
<blockquote>
|
||
<p>Check out this <a href="https://developers.google.com/identity/protocols/oauth2/openid-connect">documentation</a> to get ready before we start.</p>
|
||
</blockquote>
|
||
<h4 id="meshcentral-openidconnectstrategy-basic-config-example"><em>Basic Config Example</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"oidc"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"client"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"client_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"268438852161-r8xa7qxwf3rr0shp1xnpgmm70bnag21p.apps.googleusercontent.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"client_secret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ETFWBX-gFEaxfPXs1tWmAOkuWDFTgoL3nwh"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<h4 id="meshcentral-openidconnectstrategy-specifics"><em>Specifics</em></h4>
|
||
<p>If you notice above I forgot to add any preset related configs, however because google tags the client ID we can detect that and automatically use the google preset. The above config is tested, the sentive data has been scrambled of course. That said, you would normally use this preset in more advaced setups, let take a look at an example.</p>
|
||
<h4 id="meshcentral-openidconnectstrategy-advanced-example-with-groups"><em>Advanced Example with Groups</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"oidc"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"client"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"client_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"424555768625-k7ub3ovqs0yp7mfo0usvyyx51nfii61c.apps.googleusercontent.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"client_secret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"QLBCQY-nRYmjnFWv3nKyHGmwQEGLokP6ldk"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"custom"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"preset"</span><span class="p">:</span><span class="w"> </span><span class="s2">"google"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"customer_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"C46kyhmps"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"groups"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"siteadmin"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"GroupA"</span><span class="p">,</span><span class="w"> </span><span class="s2">"GroupB"</span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"revokeAdmin"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"sync"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"callbackURL"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://mesh.your.domain/auth-oidc-google-callback"</span>
|
||
<span class="p">},</span>
|
||
</code></pre></div>
|
||
<h4 id="meshcentral-openidconnectstrategy-customer-id-and-groups"><em>Customer ID and Groups</em></h4>
|
||
<p>As always, the client ID and secret are required, the customer ID on the other hand is only required if you plan to take advantage of the groups function <em>and</em> the google preset. This also requires you have a customer ID, if you have do, it is available in the Google Workspace Admin Console under Profile->View. Groups work the same as they would with any other IdP but they are pulled from the Workspace groups. </p>
|
||
<h4 id="meshcentral-openidconnectstrategy-schema_4"><em>Schema</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"custom"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"object"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"properties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"preset"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"enum"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"azure"</span><span class="p">,</span><span class="w"> </span><span class="s2">"google"</span><span class="p">]},</span>
|
||
<span class="w"> </span><span class="nt">"customer_id"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Customer ID from Google, should start with 'C'."</span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"additionalProperties"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="p">},</span>
|
||
</code></pre></div>
|
||
<h3 id="meshcentral-openidconnectstrategy-azure-preset">Azure Preset</h3>
|
||
<h4 id="meshcentral-openidconnectstrategy-prerequisites_1"><em>Prerequisites</em></h4>
|
||
<p>To configure OIDC-based SSO, you need an Azure account with an active subscription. <a href="https://azure.microsoft.com/free/?WT.mc_id=A261C142F">Create an account</a> for free. The account used for setup must be of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner the service principal.</p>
|
||
<blockquote>
|
||
<p>Check this <a href="https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-oidc-sso">documentation</a> for more information. </p>
|
||
</blockquote>
|
||
<h4 id="meshcentral-openidconnectstrategy-basic-config-example_1"><em>Basic Config Example</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"oidc"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"client"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"client_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"a1gkl04i-40g8-2h74-6v41-2jm2o2x0x27r"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"client_secret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"AxT6U5K4QtcyS6gF48gndL7Ys22BL15BWJImuq1O"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"custom"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"preset"</span><span class="p">:</span><span class="w"> </span><span class="s2">"azure"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"tenant_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"46a6022g-4h33-1451-h1rc-08102ga3b5e4"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<h4 id="meshcentral-openidconnectstrategy-specifics_1"><em>Specifics</em></h4>
|
||
<p>As with all other types of configuration for the OIDC strategy, the Azure preset requires a client ID and secret.The tenant ID is used as part of the issuer URI to make even the most basic AuthN requests so it is also required for the azure preset. besides that groups are available to the Azure preset as well as the recursive feature of groups. This allows you to search user groups recursively for groups they have membership in through other groups.</p>
|
||
<blockquote>
|
||
<p>NOTE: The Azure AD preset uses the Tenant ID as part of the issuer URI:<br><code>"https://login.microsoftonline.com/"</code> + <code>strategy</code>.custom.tenant_id + <code>"/v2.0"</code></p>
|
||
</blockquote>
|
||
<h4 id="meshcentral-openidconnectstrategy-advanced-example-with-groups_1"><em>Advanced Example with Groups</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"oidc"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"client"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"client_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"a1gkl04i-40g8-2h74-6v41-2jm2o2x0x27r"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"client_secret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"AxT6U5K4QtcyS6gF48gndL7Ys22BL15BWJImuq1O"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"custom"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"preset"</span><span class="p">:</span><span class="w"> </span><span class="s2">"azure"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"tenant_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"46a6022g-4h33-1451-h1rc-08102ga3b5e4"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"groups"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"recursive"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"siteadmin"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"GroupA"</span><span class="p">,</span><span class="w"> </span><span class="s2">"GroupB"</span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"revokeAdmin"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"sync"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"callbackURL"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://mesh.your.domain/auth-oidc-azure-callback"</span>
|
||
<span class="p">},</span>
|
||
</code></pre></div>
|
||
<h4 id="meshcentral-openidconnectstrategy-schema_5"><em>Schema</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"custom"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"object"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"properties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"preset"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"enum"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"azure"</span><span class="p">,</span><span class="w"> </span><span class="s2">"google"</span><span class="p">]},</span>
|
||
<span class="w"> </span><span class="nt">"tenant_id"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Tenant ID from Azure AD."</span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"additionalProperties"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="p">},</span>
|
||
</code></pre></div>
|
||
<h2 id="meshcentral-openidconnectstrategy-depreciated-properties">Depreciated Properties</h2>
|
||
<h3 id="meshcentral-openidconnectstrategy-overview_3">Overview</h3>
|
||
<h4 id="meshcentral-openidconnectstrategy-introduction_6">Introduction</h4>
|
||
<p>As of MeshCentral <code>v1.1.22</code> and the writing of this documentation, the node module that handles everything was changed from <a href="https://github.com/jaredhanson/passport-openidconnect">passport-openid-connect</a> to <a href="https://github.com/panva/node-openid-client">openid-client</a>. As a result of this change, multiple properties in the config have been depcrecated; this means some options in the strategy arent being used anymore. These are often referred to as "old configs" by this documentation. </p>
|
||
<h4 id="meshcentral-openidconnectstrategy-migrating-old-configs"><em>Migrating Old Configs</em></h4>
|
||
<p>We upgraded but what about all the existing users, we couldn't just invalidate every config pre <code>v1.1.22</code>. So in an effort to allow greater flexibility to all users of MeshCentral, and what futures scholars will all agree was an obvious move, all the depreciated configs will continue working as expected. Using any of the old options will just generate a warning in the authlog and will not stop you from using this the OIDC strategy with outdated configs, however if both the equivalent new and old config are set the new config will be used.</p>
|
||
<h4 id="meshcentral-openidconnectstrategy-old-config-example"><em>Old Config Example</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"oidc"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"newAccounts"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"421326444155-i1tt4bsmk3jm7dri6jldekl86rfpg07r.apps.googleusercontent.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientsecret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"GNLXOL-kEDjufOCk6pIcTHtaHFOCgbT4hoi"</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>This example was chosen because I wanted to highlight an advantage of supporting these old configs long term, even in a depreciated status. That is, the ability to copy your existing config from one of the related strategies without making any changes to your config by using the presets. This allows you to test out the oidc strategy without commiting to anything, since the user is always appended with the strategy used to login. In this example, the config was originally a google auth strategy config, changing the <code>"google"</code> to <code>"oidc"</code> is all that was done to the above config, besides obsfuscation of course.</p>
|
||
<h4 id="meshcentral-openidconnectstrategy-advcanced-old-config-example"><em>Advcanced Old Config Example</em></h4>
|
||
<div class="highlight"><pre><span></span><code><span class="nt">"oidc"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"authorizationURL"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain/api/oidc/authorization"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"callbackURL"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://mesh.your.domain/oauth2/oidc/callback"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"tZiPTMDNuSaQPapAQJtwDXVnYjjhQybc"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"clientsecret"</span><span class="p">:</span><span class="w"> </span><span class="s2">"vrQWspJxdVAxEFJdrxvxeQwWkooVcqdU"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"issuer"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"tokenURL"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain/api/oidc/token"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"userInfoURL"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain/api/oidc/userinfo"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"logoutURL"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://sso.your.domain/logout?rd=https://mesh.your.domain/login"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"groups"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"recursive"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"required"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"Group1"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Group2"</span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"siteadmin"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"GroupA"</span><span class="p">,</span><span class="w"> </span><span class="s2">"GroupB"</span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"sync"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span>
|
||
<span class="w"> </span><span class="nt">"filter"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"Group1"</span><span class="p">,</span><span class="w"> </span><span class="s2">"GroupB"</span><span class="p">,</span><span class="w"> </span><span class="s2">"OtherGroup"</span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"newAccounts"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="p">},</span>
|
||
</code></pre></div>
|
||
<h4 id="meshcentral-openidconnectstrategy-upgrading-to-v1122"><em>Upgrading to v1.1.22</em></h4>
|
||
<p>If you were already using a meticulusly configured oidc strategy, all of your configs will still be used. You will simply see a warning in the logs if any depreciated properties were used. If you check the authLog there are additional details about the old config and provide the new place to put that information. In this advanced config, even the groups will continue to work just as they did before without any user intervention when upgrading from a version of MeshCentral pre v1.1.22. There are no step to take and no action is needed, moving the configs to the new locations is completely optional at the moment.</p>
|
||
<h1 id="meshcentral-openidconnectstrategy-links">Links</h1>
|
||
<p>https://cloud.google.com/identity/docs/reference/rest/v1/groups/list</p>
|
||
<p>https://www.onelogin.com/learn/authentication-vs-authorization</p>
|
||
<p>https://auth0.com/docs/authenticate/protocols/openid-connect-protocol</p>
|
||
<p>https://github.com/panva/node-openid-client</p>
|
||
<p>https://openid.net/connect/</p>
|
||
<blockquote>
|
||
<p>You just read <code>openidConnectStrategy.ms v1.0.1</code> by <a href="https://github.com/mstrhakr">@mstrhakr</a></p>
|
||
</blockquote></section></section>
|
||
<section class='print-page md-section' id='section-4' heading-number='4'>
|
||
<h1>Submodules and Features<a class='headerlink' href='#section-4' title='Permanent link'></a>
|
||
</h1>
|
||
<section class="print-page" id="meshcmd" heading-number="4.1"><h1 id="meshcmd-meshcmd">MeshCmd</h1>
|
||
<hr />
|
||
<p>Access the official MeshCmd user guide in your preferred format</p>
|
||
<blockquote>
|
||
<ul>
|
||
<li><a href="https://meshcentral.com/docs/MeshCmdUserGuide.pdf">📄 PDF version</a></li>
|
||
<li><a href="../documents/MeshCmd%20User%27s%20Guide%20v0.0.3.odt">📝 ODT version</a></li>
|
||
</ul>
|
||
</blockquote>
|
||
<hr />
|
||
<h2 id="meshcmd-video-walkthru">🎬 Video Walkthru</h2>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/AzdKyzqmpIs" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-11-39.png" /></p>
|
||
<h2 id="meshcmd-abstract">🧾 Abstract</h2>
|
||
<p>This user guide contains all essential information for the user to make full use of MeshCmd, a command line tool used to perform tasks on MeshCentral and for Intel® AMT. This tool run on Windows and Linux and perform a wide array of different tasks. From routing traffic over the Internet to activating Intel AMT, MeshCmd is a great do it all tool for computer management. </p>
|
||
<h2 id="meshcmd-introduction">📘 Introduction</h2>
|
||
<p>MeshCmd, called “Mesh Command”, is a command line tool that runs on both Windows and Linux and used to perform many tasks related to computer management. As the tool continues to evolve, it will continue to be improved and acquire more features.</p>
|
||
<p>Broadly, the tool is intended to perform three sets of tasks : </p>
|
||
<ul>
|
||
<li>
|
||
<p><code>MeshCentral2 command line operations</code></p>
|
||
<blockquote>
|
||
<p>There are command line operations that relate to interacting with the MeshCentral2 server. A good example of this is to route traffic from your computer to a remote computer on the internet thru a MeshCentral2 server. </p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><code>Intel AMT local actions</code></p>
|
||
<blockquote>
|
||
<p>If you happen to have Intel AMT on your computer, MeshCmd can take a look at the version and activation status, activate and de-activate Intel AMT and help with getting access to Intel AMT and more. </p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><code>Intel AMT remote actions</code></p>
|
||
<blockquote>
|
||
<p>Whether you have Intel AMT on your local computer or a remote computer on your network, MeshCmd can help unlock the features Intel AMT provides. From getting the state of Intel AMT remotely to running configuration scripts and loading MeshCommander into Intel AMT web storage. </p>
|
||
</blockquote>
|
||
</li>
|
||
</ul>
|
||
<p>To get started, you need to download MeshCmd for your computer. MeshCmd is a single file executable that you can get on MeshCommander.com at: <a href="http://www.meshcommander.com/meshcommander/meshcmd">http://www.meshcommander.com/meshcommander/meshcmd</a> </p>
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-21-12.png" />
|
||
If you have access to a MeshCentral2 server, the download link to MeshCmd is at the bottom left of the main device page. </p>
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-22-07.png" /></p>
|
||
<p>Once you click on the <code>MeshCmd</code> link, a dialog box will allow you to select the operating system you want to get a link to MeshCmd. MeshCentral will also provide an action file called meshaction.txt that contains information on how MeshCmd can connect back to that MeshCentral server. This is optional, and only used for some operations. </p>
|
||
<p>Once downloaded, just run it from the command prompt or terminal window. </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\T</span>emp>meshcmd
|
||
MeshCentral<span class="w"> </span>Command<span class="w"> </span><span class="o">(</span>MeshCmd<span class="o">)</span>
|
||
No<span class="w"> </span>action<span class="w"> </span>specified,<span class="w"> </span>use<span class="w"> </span>MeshCmd<span class="w"> </span>like<span class="w"> </span>this:
|
||
|
||
<span class="w"> </span>meshcmd<span class="w"> </span><span class="o">[</span>action<span class="o">]</span><span class="w"> </span><span class="o">[</span>arguments...<span class="o">]</span>
|
||
|
||
Valid<span class="w"> </span>MeshCentral<span class="w"> </span>actions:
|
||
<span class="w"> </span>Route<span class="w"> </span>-<span class="w"> </span>Map<span class="w"> </span>a<span class="w"> </span><span class="nb">local</span><span class="w"> </span>TCP<span class="w"> </span>port<span class="w"> </span>to<span class="w"> </span>a<span class="w"> </span>remote<span class="w"> </span>computer.
|
||
|
||
Valid<span class="w"> </span><span class="nb">local</span><span class="w"> </span>actions:
|
||
<span class="w"> </span>SMBios<span class="w"> </span>-<span class="w"> </span>Display<span class="w"> </span>System<span class="w"> </span>Management<span class="w"> </span>BIOS<span class="w"> </span>tables<span class="w"> </span><span class="k">for</span><span class="w"> </span>this<span class="w"> </span>computer.
|
||
<span class="w"> </span>RawSMBios<span class="w"> </span>-<span class="w"> </span>Display<span class="w"> </span>RAW<span class="w"> </span>System<span class="w"> </span>Management<span class="w"> </span>BIOS<span class="w"> </span>tables<span class="w"> </span><span class="k">for</span><span class="w"> </span>this<span class="w"> </span>computer.
|
||
<span class="w"> </span>MicroLMS<span class="w"> </span>-<span class="w"> </span>Run<span class="w"> </span>MicroLMS,<span class="w"> </span>allowing<span class="w"> </span><span class="nb">local</span><span class="w"> </span>access<span class="w"> </span>to<span class="w"> </span>Intel<span class="w"> </span>AMT.
|
||
<span class="w"> </span>AmtInfo<span class="w"> </span>-<span class="w"> </span>Show<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>version<span class="w"> </span>and<span class="w"> </span>activation<span class="w"> </span>state.
|
||
<span class="w"> </span>AmtVersions<span class="w"> </span>-<span class="w"> </span>Show<span class="w"> </span>all<span class="w"> </span>Intel<span class="w"> </span>ME<span class="w"> </span>version<span class="w"> </span>information.
|
||
<span class="w"> </span>AmtHashes<span class="w"> </span>-<span class="w"> </span>Show<span class="w"> </span>all<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>trusted<span class="w"> </span>activation<span class="w"> </span>hashes.
|
||
<span class="w"> </span>AmtCCM<span class="w"> </span>-<span class="w"> </span>Activate<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>into<span class="w"> </span>Client<span class="w"> </span>Control<span class="w"> </span>Mode.
|
||
<span class="w"> </span>AmtACM<span class="w"> </span>-<span class="w"> </span>Activate<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>into<span class="w"> </span>Admin<span class="w"> </span>Control<span class="w"> </span>Mode.
|
||
<span class="w"> </span>AmtDeactivate<span class="w"> </span>-<span class="w"> </span>Deactivate<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span><span class="k">if</span><span class="w"> </span>activated<span class="w"> </span><span class="k">in</span><span class="w"> </span>Client<span class="w"> </span>Control<span class="w"> </span>mode.
|
||
<span class="w"> </span>AmtAcmDeactivate<span class="w"> </span>-<span class="w"> </span>Deactivate<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span><span class="k">if</span><span class="w"> </span>activated<span class="w"> </span><span class="k">in</span><span class="w"> </span>Admin<span class="w"> </span>Control<span class="w"> </span>mode.
|
||
|
||
Valid<span class="w"> </span><span class="nb">local</span><span class="w"> </span>or<span class="w"> </span>remote<span class="w"> </span>actions:
|
||
<span class="w"> </span>MeshCommander<span class="w"> </span>-<span class="w"> </span>Launch<span class="w"> </span>a<span class="w"> </span><span class="nb">local</span><span class="w"> </span>MeshCommander<span class="w"> </span>web<span class="w"> </span>server.
|
||
<span class="w"> </span>AmtUUID<span class="w"> </span>-<span class="w"> </span>Show<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>unique<span class="w"> </span>identifier.
|
||
<span class="w"> </span>AmtAuditLog<span class="w"> </span>-<span class="w"> </span>Show<span class="w"> </span>the<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>audit<span class="w"> </span>log.
|
||
<span class="w"> </span>AmtLoadWebApp<span class="w"> </span>-<span class="w"> </span>Load<span class="w"> </span>MeshCommander<span class="w"> </span><span class="k">in</span><span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span><span class="m">11</span>.6+<span class="w"> </span>firmware.
|
||
<span class="w"> </span>AmtClearWebApp<span class="w"> </span>-<span class="w"> </span>Clear<span class="w"> </span>everything<span class="w"> </span>from<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>web<span class="w"> </span>storage.
|
||
<span class="w"> </span>AmtStorageState<span class="w"> </span>-<span class="w"> </span>Show<span class="w"> </span>contents<span class="w"> </span>of<span class="w"> </span>the<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>web<span class="w"> </span>storage.
|
||
<span class="w"> </span>AmtSaveState<span class="w"> </span>-<span class="w"> </span>Save<span class="w"> </span>all<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>WSMAN<span class="w"> </span>object<span class="w"> </span>to<span class="w"> </span>file.
|
||
<span class="w"> </span>AmtPresence<span class="w"> </span>-<span class="w"> </span>Heartbeat<span class="w"> </span>a<span class="w"> </span><span class="nb">local</span><span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>watchdog<span class="w"> </span>agent.
|
||
<span class="w"> </span>AmtScript<span class="w"> </span>-<span class="w"> </span>Run<span class="w"> </span>.mescript<span class="w"> </span>on<span class="w"> </span>Intel<span class="w"> </span>AMT.
|
||
<span class="w"> </span>AmtIDER<span class="w"> </span>-<span class="w"> </span>Mount<span class="w"> </span><span class="nb">local</span><span class="w"> </span>disk<span class="w"> </span>image<span class="w"> </span>to<span class="w"> </span>remote<span class="w"> </span>computer.
|
||
|
||
Help<span class="w"> </span>on<span class="w"> </span>a<span class="w"> </span>specific<span class="w"> </span>action<span class="w"> </span>using:
|
||
|
||
<span class="w"> </span>meshcmd<span class="w"> </span><span class="nb">help</span><span class="w"> </span><span class="o">[</span>action<span class="o">]</span>
|
||
</code></pre></div>
|
||
<p>By default you will get the help screen with all of the different actions you can take with the tool. You can also get help by typing <code>help</code> followed by the action name. In this document we will cover the main actions that MeshCmd can perform. If you don’t use Intel AMT at all, then only the MeshCentral actions are interesting for you. If you use Intel AMT, the rest of the actions will be of interest to you. </p>
|
||
<h2 id="meshcmd-meshcentral-tcp-port-mapping">🔌 MeshCentral TCP port mapping</h2>
|
||
<p>MeshCmd can map a TCP port from your local computer to any remote port on any computer with one of your MeshAgents installed. This port mapping will work over a local network or the Internet and should work even thru proxies and firewalls. </p>
|
||
<p>In order to start using MeshCmd in this way, you first need to have access to a MeshCentral server and at least one computer you already manage. TCP port mapping works by selecting a port on your local computer that will be routed to a remote device and port. Here, local port 123 is routed thru the server to port 123 on a remote device. </p>
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-23-45.png" /></p>
|
||
<p>Of course, this picture is a bit simplify. Firewalls, NAT routers and HTTP proxies may be in the way and the MeshAgent on the remote computer will act at the TCP traffic relay in most cases. </p>
|
||
<p>One typical use of this is to route local port <code>1234</code> to port Microsoft RDP port 3389 on a remote device. Once routed, you can start a RDP session on <code>localhost:1234</code> and get a RDP session to the remote device. The RDP protocol is feature rich and efficient, so you get a great user experience regardless of where in the world the remote computer is at. </p>
|
||
<p>To get started, click on a device in MeshCentral and click on the <code>Router</code> link on the bottom left of the device page. </p>
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-24-12.png" /></p>
|
||
<p>You can download MeshCmd is you have not done so already, but more importantly, download the action.txt file. The file is in text format and contain something like this : </p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"action"</span><span class="p">:</span><span class="w"> </span><span class="s2">"route"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"localPort"</span><span class="p">:</span><span class="w"> </span><span class="mi">1234</span><span class="p">,</span><span class="w"> </span><span class="err"></span><span class="w"> </span><span class="err">Cha</span><span class="kc">n</span><span class="err">ge</span><span class="w"> </span><span class="kc">t</span><span class="err">his</span>
|
||
<span class="w"> </span><span class="nt">"remoteName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"AmtMachine7"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"remoteNodeId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"node//@yw$s5jLUivpzZ49laprt4T0sBaOKImbDAiniothQwccZPukCB696$BvPWAW0Bg2"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"remotePort"</span><span class="p">:</span><span class="w"> </span><span class="mi">3389</span><span class="p">,</span><span class="w"> </span><span class="err"></span><span class="w"> </span><span class="err">Cha</span><span class="kc">n</span><span class="err">ge</span><span class="w"> </span><span class="kc">t</span><span class="err">his</span>
|
||
<span class="w"> </span><span class="nt">"username"</span><span class="p">:</span><span class="w"> </span><span class="s2">"admin"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"password"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span><span class="w"> </span><span class="err"></span><span class="w"> </span><span class="err">No</span><span class="kc">te</span><span class="w"> </span><span class="kc">t</span><span class="err">ha</span><span class="kc">t</span><span class="w"> </span><span class="kc">t</span><span class="err">he</span><span class="w"> </span><span class="err">password</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">emp</span><span class="kc">t</span><span class="err">y</span>
|
||
<span class="w"> </span><span class="nt">"serverId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"D99362D5ED8BAEA8BF9E743B34B242256370C460FD66CB62373C6CFCB204D6D70</span>
|
||
<span class="s2">7403E396CF0EF6DC2B3A42F735135FD"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"serverHttpsHash"</span><span class="p">:</span><span class="w"> </span><span class="s2">"D9DE9E27A229B5355708A3672FB23237CC994A680B3570D242A91E36B4AE5BC</span>
|
||
<span class="s2">96539E59746E2B71EEF3DBDABBF2AE138"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"debugLevel"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"serverUrl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"wss://devbox.mesh.meshcentral.com:443/meshrelay.ashx"</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>The action file contains almost all the parameters needed to perform the route. It indicates the local and remote ports, the remote computer unique identifier, server location and authentication information and more. You can just put the action file in the same folder as MeshCmd and run MeshCmd, it will automatically pick up the arguments from the meshaction.txt file. </p>
|
||
<p>You may want to change the local and remote port in the action file to suite your needs. By default, the Microsoft RDP port is the target. If the password is not specified in the <code>meshaction.txt</code> file, you can also specify it as a meshcmd argument. </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>--pass<span class="w"> </span>xxxxxxxx<span class="w"> </span>
|
||
Redirecting<span class="w"> </span><span class="nb">local</span><span class="w"> </span>port<span class="w"> </span><span class="m">1234</span><span class="w"> </span>to<span class="w"> </span>AmtMachine7:3389.<span class="w"> </span>Press<span class="w"> </span>ctrl-c<span class="w"> </span>to<span class="w"> </span>exit.<span class="w"> </span>
|
||
Now,<span class="w"> </span>the<span class="w"> </span>traffic<span class="w"> </span>router<span class="w"> </span>is<span class="w"> </span>ready.<span class="w"> </span>You<span class="w"> </span>can<span class="w"> </span>now<span class="w"> </span>RDP<span class="w"> </span>to<span class="w"> </span>localhost:1234<span class="w"> </span>and<span class="w"> </span>login<span class="w"> </span>to<span class="w"> </span>the<span class="w"> </span>remote<span class="w"> </span>computer.<span class="w"> </span>
|
||
</code></pre></div>
|
||
<h2 id="meshcmd-meshcommander">🧭 MeshCommander</h2>
|
||
<p>MeshCommander is a web based Intel AMT management console. MeshCmd has no less then three different versions of MeshCommander built-in, so if you are using Intel AMT, it’s worth a moment to get some knowledge about MeshCommander which is available as a standalone tool along with a full user’s guide at:<a href="http://www.meshcommander.com/">http://www.meshcommander.com/</a>and also included as part of MeshCentral. </p>
|
||
<p>The three versions included in MeshCmd are : </p>
|
||
<ul>
|
||
<li><strong>MeshCommander as a local web server</strong>. </li>
|
||
<li><strong>MeshCommander for LMS</strong> .</li>
|
||
<li><strong>MeshCommander for firmware</strong>. </li>
|
||
</ul>
|
||
<p>In this section, we review the three versions, how they are used and what can be done with them. </p>
|
||
<h3 id="meshcmd-1-meshcommander-local-web-server">1. MeshCommander local web server</h3>
|
||
<p>You can start MeshCommander on a local web server by typing <code>meshcmd meshcommander</code>. By default, local port <code>3000</code> is used, but you can optionally specify the port using <code>--localport [port]</code>. Running it with look like this: </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>meshcommander
|
||
MeshCommander<span class="w"> </span>running<span class="w"> </span>on<span class="w"> </span>HTTP<span class="w"> </span>port<span class="w"> </span><span class="m">3000</span>.<span class="w"> </span>Ctrl-C<span class="w"> </span>to<span class="w"> </span>exit.<span class="w"> </span>
|
||
</code></pre></div>
|
||
<p>Once running, use a web browser and go to <code>http://localhost:3000</code> to see the MeshCommander web page. The page will start out without any computers in it and you will have to add some. </p>
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-27-41.png" /></p>
|
||
<p>In this mode, the local computers that are added will be stored in the browser’s storage cache. So, clearing the browser’s cache will also clear the list of computers. You can however load and save the list of computers using the <code>Open…</code> and <code>Save…</code> buttons. This version of MeshCommander will have some limitations when compared to the full version installed using the <em>Windows .MSI installer</em>. Notably : </p>
|
||
<ul>
|
||
<li>No certificate management or validation. </li>
|
||
<li>Mutual-Authenticated TLS is not supported. </li>
|
||
<li>Kerberos authentication is not supported. </li>
|
||
<li>IDE-R is not supported. </li>
|
||
</ul>
|
||
<p>This said, features like KVM, Terminal and most Intel AMT configuration options are available which makes this a fairly powerful Intel AMT management console.</p>
|
||
<p>You can run MeshCommander as a background server on both Windows and Linux. To do this, use the install, uninstall, start and stop commands like this: </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>meshcommander<span class="w"> </span>install
|
||
Installing<span class="w"> </span>to<span class="w"> </span><span class="s2">"C:\Program Files (x86)\Open Source\MeshCmd\MeshCommander.exe"</span><span class="w"> </span>MeshCommander<span class="w"> </span>installed.
|
||
</code></pre></div>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>meshcommander<span class="w"> </span>start
|
||
MeshCommander<span class="w"> </span>starting.
|
||
</code></pre></div>
|
||
<p>On Linux computers, both systemd and initd are supported. When installing, the MeshCmd executable will be copied to a different installation folder. </p>
|
||
<h3 id="meshcmd-2-lms-meshcommander">2. LMS & MeshCommander</h3>
|
||
<p>The Layered Management Service (LMS) is a background process that runs in the operating system and provides local OS access to Intel AMT. More specifically, it redirects local TCP ports <code>16992</code> and <code>16993</code> to Intel AMT thru the MEI driver. One way to check if the LMS service is installed on your computer is to try <em><a href="http://localhost:16992/">http://localhost:16992</a></em> or <em><a href="https://localhost:16993/">https://localhost:16993</a></em> in a browser. A page should generally show up. </p>
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>On Windows, LMS is a Windows service that must be downloaded and installed as part of the OEM drivers for a computer.</p>
|
||
<p>On Linux, it’s generally never installed and users normally have to download the source code and compile it themselves.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<p>MeshCmd has its own LMS implementation, so is LMS is not installed it will automatically use its own internal one. In addition, you can run MicroLMS alone by typing the following list while running as root or local administrator: </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>microlms
|
||
MicroLMS<span class="w"> </span>started,<span class="w"> </span>MeshCommander<span class="w"> </span>on<span class="w"> </span>HTTP/16994.<span class="w"> </span>
|
||
</code></pre></div>
|
||
<p>This will start MicroLMS and as indicated, start MeshCommander on local port <code>16994</code> at the same time.</p>
|
||
<p>In total, traffic redirection looks like this : </p>
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-30-02.png" /></p>
|
||
<p>In addition to providing normal services, MicroLMS that is part of MeshCmd will also start a web server on port <code>16994</code> and allow a browser to access LMS MeshCommander, a special version of MeshCommander specially made to run in this situation. </p>
|
||
<p>MeshCommander for LMS will show up even if the computer has Intel AMT un-configured and offer the user the choice to activate Intel AMT and perform configuration actions. In the following screen, we see a computer activated in Client Control Mode.</p>
|
||
<p>Because it’s in this mode, you can use the web interface to de-activate Intel AMT or login to perform additional configuration. </p>
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-30-41.png" /></p>
|
||
<p>MicroLMS along with MeshCommander for LMS is very useful, especially on Linux as it offers a single tool to setup and configuration Intel AMT. If you wish you run MicroLMS without MeshCommander being available on port 16994, run MeshCmd with <code>--noconsole</code>: </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>microlms<span class="w"> </span>--noconsole
|
||
MicroLMS<span class="w"> </span>started.<span class="w"> </span>
|
||
</code></pre></div>
|
||
<p>You can run MicroLMS as a background server on both Windows and Linux. To do this, use the MicroLMS install, uninstall, start and stop commands like this : </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>microlms<span class="w"> </span>install
|
||
Installing<span class="w"> </span>to<span class="w"> </span><span class="s2">"C:\Program Files (x86)\Open Source\MeshCmd\MicroLMS.exe"</span><span class="w"> </span>
|
||
MicroLMS<span class="w"> </span>installed.<span class="w"> </span>
|
||
</code></pre></div>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>microlms<span class="w"> </span>start
|
||
MicroLMS<span class="w"> </span>starting.<span class="w"> </span>
|
||
</code></pre></div>
|
||
<p>On Linux computers, both systemd and initd are supported. When installing, the MeshCmd executable will be copied to a different installation folder. </p>
|
||
<h3 id="meshcmd-3-meshcommander-for-firmware">3. MeshCommander for firmware</h3>
|
||
<p>MeshCmd also includes a surprising version of MeshCommander, the one you can load into the firmware of Intel AMT. Starting with Intel AMT 11.6, you can push into the small ~190k storage space of Intel AMT a replacement to the index.htm page served by the firmware on port <code>16992</code> & <code>16993</code>. In the following picture, the left side is the original Intel AMT web page, the right is the replaced MeshCommander built to go in firmware. </p>
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-32-15.png" /></p>
|
||
<p>The firmware version of MeshCommander has support for remote desktop, terminal and all sorts of Intel AMT usages and configuration. Probably the most surprising is that this entire page is between 40k and 100k depending on the version you select. It’s notable that with MeshCommander loaded into Intel AMT firmware, one does not need any other tool except for a browser to perform most Intel AMT maintenance operations. </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>amtloadwebapp<span class="w"> </span>--host<span class="w"> </span><span class="m">192</span>.168.2.144<span class="w"> </span>--pass<span class="w"> </span>xxxxxxxx
|
||
Uploading<span class="w"> </span>MeshCommander...
|
||
Verifying<span class="w"> </span>MeshCommander...
|
||
Done.
|
||
</code></pre></div>
|
||
<p>To get the current state of Intel AMT web storage, type this : </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>amtstoragestate<span class="w"> </span>--host<span class="w"> </span><span class="m">192</span>.168.2.144<span class="w"> </span>--pass<span class="w"> </span>xxxxxxxx
|
||
Storage<span class="w"> </span>State:<span class="w"> </span><span class="o">{</span>
|
||
<span class="w"> </span><span class="s2">"information"</span>:<span class="w"> </span><span class="o">{</span>
|
||
<span class="w"> </span><span class="s2">"version"</span>:<span class="w"> </span><span class="m">1</span>,
|
||
<span class="w"> </span><span class="s2">"realms"</span>:<span class="w"> </span><span class="m">7765759</span>,
|
||
<span class="w"> </span><span class="s2">"user"</span>:<span class="w"> </span><span class="s2">"admin"</span>
|
||
<span class="w"> </span><span class="o">}</span>,
|
||
<span class="w"> </span><span class="s2">"content"</span>:<span class="w"> </span><span class="o">{</span>
|
||
<span class="w"> </span><span class="s2">"index.htm"</span>:<span class="w"> </span><span class="o">{</span>
|
||
<span class="w"> </span><span class="s2">"size"</span>:<span class="w"> </span><span class="m">57246</span><span class="w"> </span><span class="w"> </span>Replacement<span class="w"> </span>index.htm<span class="w"> </span>with<span class="w"> </span>size.
|
||
<span class="w"> </span><span class="o">}</span>
|
||
<span class="w"> </span><span class="o">}</span>
|
||
<span class="o">}</span>
|
||
</code></pre></div>
|
||
<p>Here, a 57k index.htm replacement is present in the Intel AMT flash. You can clear the web storage, revering the web page back to the original like this: </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>amtclearwebapp<span class="w"> </span>--host<span class="w"> </span><span class="m">192</span>.168.2.144<span class="w"> </span>--pass<span class="w"> </span>xxxxxxxx
|
||
Done.
|
||
</code></pre></div>
|
||
<p>When MeshCommander is loaded into Intel AMT, you can access it from a different computer using <em><a href="http://computername:16992/">http://computername:16992 </a></em> or <em><a href="https://computername:16993/">https://computername:16993</a></em> You will need to authenticate first before getting access to the web page. </p>
|
||
<h2 id="meshcmd-intel-amt-state-activation">🔧 Intel AMT state & activation</h2>
|
||
<p>MeshCmd can easily be used to read the local state of the computer and Intel AMT. There are many commands available to do this. The <code>SMBios</code> action works on most computers and is used to get basic information about your current system. The output is JSON format. </p>
|
||
<div class="highlight"><pre><span></span><code><span class="err">C</span><span class="p">:</span><span class="err">\MeshCmd>meshcmd</span><span class="w"> </span><span class="err">smbios</span>
|
||
<span class="p">{</span>
|
||
<span class="w"> </span><span class="err">processorI</span><span class="kc">nf</span><span class="err">o</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="mi">0</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">Processor</span><span class="p">:</span><span class="w"> </span><span class="s2">"CPU"</span>
|
||
<span class="w"> </span><span class="err">MaxSpeed</span><span class="p">:</span><span class="w"> </span><span class="s2">"3800 Mhz"</span>
|
||
<span class="w"> </span><span class="err">Cores</span><span class="p">:</span><span class="w"> </span><span class="mi">4</span>
|
||
<span class="w"> </span><span class="err">Threads</span><span class="p">:</span><span class="w"> </span><span class="mi">8</span>
|
||
<span class="w"> </span><span class="err">Popula</span><span class="kc">te</span><span class="err">d</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span>
|
||
<span class="w"> </span><span class="err">S</span><span class="kc">tatus</span><span class="p">:</span><span class="w"> </span><span class="s2">"Enabled"</span>
|
||
<span class="w"> </span><span class="err">Socke</span><span class="kc">t</span><span class="p">:</span><span class="w"> </span><span class="s2">"CPU 1"</span>
|
||
<span class="w"> </span><span class="err">Ma</span><span class="kc">nufa</span><span class="err">c</span><span class="kc">turer</span><span class="p">:</span><span class="w"> </span><span class="s2">"Intel(R) Corporation"</span>
|
||
<span class="w"> </span><span class="err">Versio</span><span class="kc">n</span><span class="p">:</span><span class="w"> </span><span class="s2">"Intel(R) Core(TM) i7-3770 CPU @ 3.40GHz"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="err">memoryI</span><span class="kc">nf</span><span class="err">o</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">loca</span><span class="kc">t</span><span class="err">io</span><span class="kc">n</span><span class="p">:</span><span class="w"> </span><span class="s2">"System Board"</span>
|
||
<span class="w"> </span><span class="err">maxCapaci</span><span class="kc">t</span><span class="err">yKb</span><span class="p">:</span><span class="w"> </span><span class="mi">33554432</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="err">sys</span><span class="kc">te</span><span class="err">mI</span><span class="kc">nf</span><span class="err">o</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">uuid</span><span class="p">:</span><span class="w"> </span><span class="s2">"C57B83D9A94E11E18BA1505054503030"</span>
|
||
<span class="w"> </span><span class="err">wakeReaso</span><span class="kc">n</span><span class="p">:</span><span class="w"> </span><span class="s2">"Power Switch"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="err">sys</span><span class="kc">te</span><span class="err">mSlo</span><span class="kc">ts</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">uuid</span><span class="p">:</span><span class="w"> </span><span class="s2">"C57B83D9A94E11E18BA1505054503030"</span>
|
||
<span class="w"> </span><span class="err">wakeReaso</span><span class="kc">n</span><span class="p">:</span><span class="w"> </span><span class="s2">"Power Switch"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="err">am</span><span class="kc">t</span><span class="err">I</span><span class="kc">nf</span><span class="err">o</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="err">AMT</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="err">e</span><span class="kc">na</span><span class="err">bled</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="err">s</span><span class="kc">t</span><span class="err">orageRedirec</span><span class="kc">t</span><span class="err">io</span><span class="kc">n</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="err">serialOverLa</span><span class="kc">n</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="err">kvm</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="err">TXT</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||
<span class="w"> </span><span class="err">VMX</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="err">MEBX</span><span class="p">:</span><span class="w"> </span><span class="s2">"66.0.0.8"</span>
|
||
<span class="w"> </span><span class="err">Ma</span><span class="kc">na</span><span class="err">geme</span><span class="kc">nt</span><span class="err">E</span><span class="kc">n</span><span class="err">gi</span><span class="kc">ne</span><span class="p">:</span><span class="w"> </span><span class="s2">"8.1.0.57353"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>If you have Intel AMT on your system, you can use the <code>amtinfo</code>, <code>amtversions</code> and <code>amthashes</code> to get lots of information about Intel AMT current state. These commands use the Intel AMT MEI driver to get this information and require MeshCmd be run as root or administrator : </p>
|
||
<blockquote>
|
||
<p><code>meshcmd amtinfo</code>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>amtinfo
|
||
Intel<span class="w"> </span>AMT<span class="w"> </span>v8.1.71,<span class="w"> </span>activated<span class="w"> </span><span class="k">in</span><span class="w"> </span>client<span class="w"> </span>control<span class="w"> </span>mode.
|
||
Wired<span class="w"> </span>Enabled,<span class="w"> </span>DHCP,<span class="w"> </span><span class="m">00</span>:1E:8C:F5:4F:ED,<span class="w"> </span><span class="m">192</span>.168.2.10.
|
||
</code></pre></div></p>
|
||
<p><code>meshcmd amtversions</code>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>amtversions
|
||
MEI<span class="w"> </span><span class="nv">Version</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>MKQ7710H.86A.0072.2017.0519.1347
|
||
<span class="nv">Flash</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">8</span>.1.71
|
||
<span class="nv">Netstack</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">8</span>.1.71
|
||
<span class="nv">AMTApps</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">8</span>.1.71
|
||
<span class="nv">AMT</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">8</span>.1.71
|
||
<span class="nv">Sku</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">24584</span>
|
||
<span class="nv">VendorID</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">8086</span>
|
||
Build<span class="w"> </span><span class="nv">Number</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">3608</span>
|
||
Recovery<span class="w"> </span><span class="nv">Version</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">8</span>.1.71
|
||
Recovery<span class="w"> </span>Build<span class="w"> </span><span class="nv">Num</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">3608</span>
|
||
Legacy<span class="w"> </span><span class="nv">Mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>False
|
||
</code></pre></div></p>
|
||
<p><code>meshcmd amthashes</code>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>amthashes
|
||
VeriSign<span class="w"> </span>Class<span class="w"> </span><span class="m">3</span><span class="w"> </span>Primary<span class="w"> </span>CA-G1,<span class="w"> </span><span class="o">(</span>Default,<span class="w"> </span>Active<span class="o">)</span>
|
||
<span class="w"> </span>SHA256:<span class="w"> </span>E7685634EFACF69ACE939A6B255B7B4FABEF42935B50A265ACB5CB6027E44E70
|
||
VeriSign<span class="w"> </span>Class<span class="w"> </span><span class="m">3</span><span class="w"> </span>Primary<span class="w"> </span>CA-G3,<span class="w"> </span><span class="o">(</span>Default,<span class="w"> </span>Active<span class="o">)</span>
|
||
<span class="w"> </span>SHA256:<span class="w"> </span>EB04CF5EB1F39AFA762F2BB120F296CBA520C1B97DB1589565B81CB9A17B7244
|
||
…
|
||
</code></pre></div></p>
|
||
</blockquote>
|
||
<p>In addition to getting Intel AMT state, MeshCmd can activate Intel AMT in client control mode (CCM) and de-activate Intel AMT if it’s in this mode. Doing this is very simple, starting with Intel AMT not being activated, you use the <code>amtccm</code> and <code>amtdeactivate</code> actions. </p>
|
||
<blockquote>
|
||
<p><code>meshcmd amtinfo</code>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>amtinfo
|
||
Intel<span class="w"> </span>AMT<span class="w"> </span>v8.1.71,<span class="w"> </span>pre-provisioning<span class="w"> </span>state.
|
||
</code></pre></div>
|
||
<code>meshcmd amtccm --pass xxxxxxxx</code>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>amtccm<span class="w"> </span>--pass<span class="w"> </span>xxxxxxxx
|
||
Success
|
||
</code></pre></div>
|
||
<code>meshcmd amtinfo</code>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>amtinfo
|
||
Intel<span class="w"> </span>AMT<span class="w"> </span>v8.1.71,<span class="w"> </span>activated<span class="w"> </span><span class="k">in</span><span class="w"> </span>client<span class="w"> </span>control<span class="w"> </span>mode.
|
||
</code></pre></div>
|
||
<code>meshcmd amtdeactivate</code>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>amtdeactivate
|
||
Success
|
||
</code></pre></div></p>
|
||
</blockquote>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>Note that when using the <code>amtccm</code> action, you need to provide a password that will be used for authentication into Intel AMT. This password must be strong with at least 8 characters including a lower case, an uppercase, a numeric value and a non-alpha-numeric value.</p>
|
||
</blockquote>
|
||
<hr />
|
||
<h2 id="meshcmd-intel-amt-audit-log">📋 Intel AMT Audit Log</h2>
|
||
<p>One very useful feature of MeshCmd is its ability to fetch the Intel AMT audit log. This can be valuable when doing forensics on a computer or just trying figure out what is being done thru Intel AMT. MeshCmd can pull the audit log on a local computer without any credentials, as long as it’s running as root or administrator, or pull the audit log remotely if usual credentials are provided. </p>
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-37-16.png" /></p>
|
||
<p>The Intel AMT audit log will show when a computer’s Intel AMT was activated, when remote desktop sessions where initiated and more. To get the local audit log, just use the “AmtAuditLog” action. </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>amtauditlog
|
||
<span class="m">2004</span>-01-01<span class="w"> </span><span class="m">19</span>:17:58.000-08:00<span class="w"> </span>-<span class="w"> </span>Local:<span class="w"> </span>Provisioning<span class="w"> </span>Started
|
||
<span class="m">2018</span>-01-26<span class="w"> </span><span class="m">14</span>:03:16.000-08:00<span class="w"> </span>-<span class="w"> </span>Local:<span class="w"> </span>Unprovisioning<span class="w"> </span>Started
|
||
<span class="m">2018</span>-01-26<span class="w"> </span><span class="m">14</span>:03:31.000-08:00<span class="w"> </span>-<span class="w"> </span>Local:<span class="w"> </span>Provisioning<span class="w"> </span>Started
|
||
<span class="m">2018</span>-02-01<span class="w"> </span><span class="m">12</span>:13:14.000-08:00<span class="w"> </span>-<span class="w"> </span>admin:<span class="w"> </span>KVM<span class="w"> </span>Enabled
|
||
<span class="m">2018</span>-02-01<span class="w"> </span><span class="m">12</span>:16:01.000-08:00<span class="w"> </span>-<span class="w"> </span>admin:<span class="w"> </span>KVM<span class="w"> </span>Session<span class="w"> </span>Started
|
||
<span class="m">2018</span>-02-01<span class="w"> </span><span class="m">12</span>:16:07.000-08:00<span class="w"> </span>-<span class="w"> </span>admin:<span class="w"> </span>KVM<span class="w"> </span>Session<span class="w"> </span>Ended
|
||
<span class="m">2018</span>-02-02<span class="w"> </span><span class="m">10</span>:56:06.000-08:00<span class="w"> </span>-<span class="w"> </span>admin:<span class="w"> </span>KVM<span class="w"> </span>Session<span class="w"> </span>Started
|
||
<span class="m">2018</span>-02-02<span class="w"> </span><span class="m">10</span>:56:08.000-08:00<span class="w"> </span>-<span class="w"> </span>admin:<span class="w"> </span>KVM<span class="w"> </span>Session<span class="w"> </span>Ended
|
||
</code></pre></div>
|
||
<p>To get a remote audit log : </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>amtauditlog<span class="w"> </span>--host<span class="w"> </span><span class="m">192</span>.168.2.144<span class="w"> </span>--user<span class="w"> </span>admin<span class="w"> </span>--pass<span class="w"> </span>xxxxxxxx
|
||
<span class="m">2003</span>-12-31<span class="w"> </span><span class="m">23</span>:06:58.000-08:00<span class="w"> </span>-<span class="w"> </span><span class="nv">$$</span>OsAdmin:<span class="w"> </span>Intel<span class="o">(</span>r<span class="o">)</span><span class="w"> </span>ME<span class="w"> </span>Time<span class="w"> </span>Set
|
||
<span class="m">2017</span>-08-15<span class="w"> </span><span class="m">06</span>:53:31.000-07:00<span class="w"> </span>-<span class="w"> </span><span class="nv">$$</span>OsAdmin:<span class="w"> </span>Intel<span class="o">(</span>r<span class="o">)</span><span class="w"> </span>ME<span class="w"> </span>Time<span class="w"> </span>Set
|
||
<span class="m">2017</span>-10-13<span class="w"> </span><span class="m">17</span>:55:11.000-07:00<span class="w"> </span>-<span class="w"> </span>Local:<span class="w"> </span>Provisioning<span class="w"> </span>Started
|
||
<span class="m">2017</span>-10-13<span class="w"> </span><span class="m">17</span>:55:54.000-07:00<span class="w"> </span>-<span class="w"> </span>Local:<span class="w"> </span>Opt-In<span class="w"> </span>Policy<span class="w"> </span>Change
|
||
<span class="m">2017</span>-10-15<span class="w"> </span><span class="m">06</span>:44:38.000-07:00<span class="w"> </span>-<span class="w"> </span>admin:<span class="w"> </span>KVM<span class="w"> </span>Enabled
|
||
</code></pre></div>
|
||
<p>You can also save the audit log to file using the <code>--output</code> option. </p>
|
||
<h2 id="meshcmd-running-intel-amt-script">💻 Running Intel AMT script</h2>
|
||
<p>MeshCmd has a full WSMAN stack built-in and can be used to run <code>.mescript</code> file on a target Intel AMT computer. Script file are useful when you want to run a set of actions on one or more Intel AMT computers at once. You can build a .mescript file using the script editor within MeshCommander. </p>
|
||
<p>This script editor allows the user to drag & drop script blocks, set parameters on each block and test the script against a connected Intel AMT computer. </p>
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-39-40.png" /></p>
|
||
<p>In addition to building your own scripts, you can download a CIRA setup script from a MeshCentral server. When running this script, Intel AMT will be setup to call back to the server using an encrypted connection. This enables remote management of Intel AMT over the Internet. The CIRA setup script is available in the <code>Add CIRA</code> link for meshes that are Intel AMT only (no agent). </p>
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-40-05.png" /></p>
|
||
<p>Once you got the script, run it with MeshCmd like this. You specify the host if it’s not localhost, the password and the script file. </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\M</span>eshCmd>meshcmd<span class="w"> </span>amtscript<span class="w"> </span>--host<span class="w"> </span><span class="m">192</span>.168.2.106<span class="w"> </span>--pass<span class="w"> </span>xxxxxxxx<span class="w"> </span>--script<span class="w"> </span>cira_setup.mescript
|
||
Script<span class="w"> </span>Started
|
||
Policies<span class="w"> </span>removed<span class="w"> </span>successfully
|
||
Adding<span class="w"> </span>root<span class="w"> </span>certificate...
|
||
Management<span class="w"> </span>Presence<span class="w"> </span>Server<span class="w"> </span><span class="o">(</span>MPS<span class="o">)</span><span class="w"> </span>successfully<span class="w"> </span>added
|
||
Found<span class="w"> </span>matching<span class="w"> </span><span class="o">(</span>primary<span class="o">)</span><span class="w"> </span>mps:<span class="w"> </span>Intel<span class="o">(</span>r<span class="o">)</span><span class="w"> </span>AMT:Management<span class="w"> </span>Presence<span class="w"> </span>Server<span class="w"> </span><span class="m">0</span>
|
||
Setting<span class="w"> </span>policy...
|
||
Policy<span class="w"> </span>added<span class="w"> </span>successfully
|
||
Remote<span class="w"> </span>Access<span class="w"> </span>user<span class="w"> </span>interfaces<span class="w"> </span><span class="nb">set</span><span class="w"> </span>to:<span class="w"> </span>BIOS<span class="w"> </span><span class="p">&</span><span class="w"> </span>OS<span class="w"> </span>Enabed
|
||
Parsing<span class="w"> </span>block<span class="w"> </span>parameters
|
||
Setting<span class="w"> </span>Environment<span class="w"> </span>Detection
|
||
Environment<span class="w"> </span>Detection<span class="w"> </span><span class="nb">set</span><span class="w"> </span>successfully
|
||
Script<span class="w"> </span>Completed
|
||
</code></pre></div>
|
||
<p>In this example, the CIRA setup script was run on a remote computer. After the script is run, the computer got configured and connected back to the server. MeshCentral show the new connection state for this computer. </p>
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-41-20.png" /></p>
|
||
<h2 id="meshcmd-ide-redirection">➡️ IDE Redirection</h2>
|
||
<h2 id="meshcmd-video-walkthru_1">🎬 Video Walkthru</h2>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/iG73j7Toz1c" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<p>MeshCmd has all the code needed to perform Intel AMT IDE Redirection from the command line. This allows disk images on the administrator’s computer to be remotely mounted to an Intel AMT computer. You need to start with a floppy disk .img file and/or an .iso CDROM file. </p>
|
||
<p><img alt="" src="../meshcmd/images/2022-05-15-15-42-01.png" /></p>
|
||
<p>Then use the <code>AmtIDER</code> command of MeshCMD to start an IDER session. The help command for AmtIDER looks like this: </p>
|
||
<div class="highlight"><pre><span></span><code>C:<span class="se">\T</span>emp>meshcmd<span class="w"> </span><span class="nb">help</span><span class="w"> </span>amtider
|
||
AmtIDER<span class="w"> </span>will<span class="w"> </span>mount<span class="w"> </span>a<span class="w"> </span><span class="nb">local</span><span class="w"> </span>disk<span class="w"> </span>images<span class="w"> </span>to<span class="w"> </span>a<span class="w"> </span>remote<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>computer.<span class="w"> </span>Example<span class="w"> </span>usage:
|
||
|
||
<span class="w"> </span>meshcmd<span class="w"> </span>amtider<span class="w"> </span>--host<span class="w"> </span><span class="m">1</span>.2.3.4<span class="w"> </span>--user<span class="w"> </span>admin<span class="w"> </span>--pass<span class="w"> </span>mypassword<span class="w"> </span>--tls<span class="w"> </span>--floppy<span class="w"> </span>disk.img<span class="w"> </span>--cdrom<span class="w"> </span>disk.iso
|
||
|
||
Possible<span class="w"> </span>arguments:
|
||
|
||
<span class="w"> </span>--host<span class="w"> </span><span class="o">[</span>hostname<span class="o">]</span><span class="w"> </span>The<span class="w"> </span>IP<span class="w"> </span>address<span class="w"> </span>or<span class="w"> </span>DNS<span class="w"> </span>name<span class="w"> </span>of<span class="w"> </span>Intel<span class="w"> </span>AMT.
|
||
<span class="w"> </span>--user<span class="w"> </span><span class="o">[</span>username<span class="o">]</span><span class="w"> </span>The<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>login<span class="w"> </span>username,<span class="w"> </span>admin<span class="w"> </span>is<span class="w"> </span>default.
|
||
<span class="w"> </span>--pass<span class="w"> </span><span class="o">[</span>password<span class="o">]</span><span class="w"> </span>The<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>login<span class="w"> </span>password.
|
||
<span class="w"> </span>--tls<span class="w"> </span>Specifies<span class="w"> </span>that<span class="w"> </span>TLS<span class="w"> </span>must<span class="w"> </span>be<span class="w"> </span>used.
|
||
<span class="w"> </span>--floppy<span class="w"> </span><span class="o">[</span>file<span class="o">]</span><span class="w"> </span>Specifies<span class="w"> </span>.img<span class="w"> </span>file<span class="w"> </span>to<span class="w"> </span>be<span class="w"> </span>mounted<span class="w"> </span>as<span class="w"> </span>a<span class="w"> </span>flppy<span class="w"> </span>disk.
|
||
<span class="w"> </span>--cdrom<span class="w"> </span><span class="o">[</span>file<span class="o">]</span><span class="w"> </span>Specifies<span class="w"> </span>.img<span class="w"> </span>file<span class="w"> </span>to<span class="w"> </span>be<span class="w"> </span>mounted<span class="w"> </span>as<span class="w"> </span>a<span class="w"> </span>CDROM<span class="w"> </span>disk.
|
||
<span class="w"> </span>--timeout<span class="w"> </span><span class="o">[</span>seconds<span class="o">]</span><span class="w"> </span>Optional,<span class="w"> </span>disconnect<span class="w"> </span>after<span class="w"> </span>number<span class="w"> </span>of<span class="w"> </span>seconds<span class="w"> </span>without<span class="w"> </span>disk<span class="w"> </span>read.
|
||
</code></pre></div>
|
||
<p>The command is fairly simple. It takes as input a remote host, username/password for Intel AMT login, the disk images and TLS option. One can also specify the timeout option so that MeshCMD will automatically disconnect when no disk read operations are performed for a set number of seconds. </p>
|
||
<h2 id="meshcmd-conclusion">🏁 Conclusion</h2>
|
||
<p>MeshCmd is a cross-platform command line tools that perform an ever-growing list of actions that are important for remote computer management. MeshCmd works alone or with MeshCentral and MeshCommander to offer a suite of free, opens source and powerful tools that work well together. </p>
|
||
<h2 id="meshcmd-license">License</h2>
|
||
<p>MeshCmd and this document are both opens source and licensed using Apache 2.0, the full license can be found at <a href="https://www.apache.org/licenses/LICENSE-2.0">https://www.apache.org/licenses/LICENSE-2.0</a> </p></section><section class="print-page" id="meshctrl" heading-number="4.2"><h1 id="meshctrl-meshctrl">MeshCtrl</h1>
|
||
<p>MeshCmd Guide <a href="https://meshcentral.com/docs/MeshCtrlUsersGuide.pdf">as .pdf</a> <a href="../documents/MeshCtrl%20User%27s%20Guide%20v0.0.1.odt">as .odt</a></p>
|
||
<h2 id="meshctrl-video-walkthru">Video Walkthru</h2>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/p_jdtYJyuBQ" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<p><img alt="" src="../meshctrl/images/2022-05-16-21-33-47.png" /></p>
|
||
<h2 id="meshctrl-abstract">Abstract</h2>
|
||
<p>This user guide contains all essential information for the user to make full use of MeshCtrl, a command line tool used to perform tasks on the MeshCentral server. This tool is built in NodeJS and can be run on the same computer as the server, or on a different computer. It’s typically used by administrators to perform various management operations on the MeshCentral server. </p>
|
||
<h2 id="meshctrl-introduction">Introduction</h2>
|
||
<p>MeshCtrl, also called “Mesh Control”, is a command line tool built in NodeJS that comes with MeshCentral and allows command line management operation of the MeshCentral server. It can be run both on the same computer as the MeshCentral server, or on a different computer. This tool allows an administrator to list user accounts, create and remove user accounts, list device groups and much more. All of the operations performed by this tool can also be performed using the MeshCentral website, however it’s sometimes useful to automate and script some management operations from the command line and this tool can do this. </p>
|
||
<p><img alt="" src="../meshctrl/images/2022-05-16-21-40-21.png" /></p>
|
||
<p>MeshCtrl will login to the MeshCentral server using a web socket connection, just like the web application does and so, it needs to login to the server using user or administrator credentials. In the next section, we will cover how to login using MeshCtrl, we then follow with the operations that MeshCtrl can perform. </p>
|
||
<h2 id="meshctrl-running-meshctrl">Running MeshCtrl</h2>
|
||
<p>MeshCtrl.js is a file that is installed with MeshCentral and is located in the “./node_modules/meshcentral” folder. You can normally run MeshCtrl like this: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node\_modules/meshcentral/meshctrl
|
||
</code></pre></div>
|
||
<p>In this case, when the above command is run without parameters, you should see something like this: </p>
|
||
<div class="highlight"><pre><span></span><code>MeshCtrl performs command line actions on a MeshCentral server.
|
||
Information at: https://meshcommander.com/meshcentral
|
||
No action specified, use MeshCtrl like this:
|
||
|
||
meshctrl [action] [arguments]
|
||
|
||
Supported actions:
|
||
Help [action] - Get help on an action.
|
||
ServerInfo - Show server information.
|
||
UserInfo - Show user information.
|
||
ListUsers - List user accounts.
|
||
ListDevices - List devices.
|
||
ListDeviceGroups - List device groups.
|
||
ListUsersOfDeviceGroup - List the users in a device group.
|
||
AddUser - Create a new user account.
|
||
RemoveUser - Delete a user account.
|
||
AddDeviceGroup - Create a new device group.
|
||
RemoveDeviceGroup - Delete a device group.
|
||
AddUserToDeviceGroup - Add a user to a device group.
|
||
RemoveUserFromDeviceGroup - Remove a user from a device group.
|
||
SendInviteEmail - Send an agent install invitation email.
|
||
Broadcast - Display a message to all online users.
|
||
|
||
Supported login arguments:
|
||
--url [wss://server] - Server url, wss://localhost:443 is default.
|
||
--loginuser [username] - Login username, admin is default.
|
||
--loginpass [password] - Login password.
|
||
--token [number] - 2nd factor authentication token.
|
||
--loginkey [hex] - Server login key in hex.
|
||
--loginkeyfile [file] - File containing server login key in hex.
|
||
--domain [domainid] - Domain id, default is empty.
|
||
</code></pre></div>
|
||
<p>This indicated you have a good version of MeshCentral with support for MeshCtrl. MeshCentral and MeshCtrl will be updated together, so as changes are made to the server, MeshCtrl will also be updated to match. </p>
|
||
<p>The next step is to login to the server with MeshCtrl before we can start performing commands. For this document, we will assume we are connection to the local MeshCentral server on port 443 using TLS. For connecting to a different server, use the --url argument to set a different server. </p>
|
||
<h2 id="meshctrl-login">Login</h2>
|
||
<p>There are two ways to login to MeshCentral using MeshCtrl. You can use the normal username/password, or use a login key. In this section we look at both. </p>
|
||
<h3 id="meshctrl-login-using-username-password">Login using username & password</h3>
|
||
<p>This is the easiest way to login and start issuing commands is to login using a username and password. </p>
|
||
<p><img alt="" src="../meshctrl/images/2022-05-16-21-47-32.png" /></p>
|
||
<p>You do this by using the "loginuser" and "loginpass" argument like this: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl serverinfo --loginuser "admin" --loginpass "mypassword"
|
||
</code></pre></div>
|
||
<p>In this example we are trying to run the “serverinfo” command using the “admin” user and “mypassword” as the password. Because “admin” if the default username for MeshCtrl, you can omit it and just type: </p>
|
||
<div class="highlight"><pre><span></span><code>Authentication token required, use --token [number].
|
||
</code></pre></div>
|
||
<p>In this case, you need to use the Google Authenticator application or a similar application to enter your time based second factor like this: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl serverinfo --loginpass "mypassword" –token 123456
|
||
</code></pre></div>
|
||
<p>Once the command is run successfully, you should see a response like this: </p>
|
||
<div class="highlight"><pre><span></span><code>name: devbox.meshcentral.com
|
||
mpsname: devbox.meshcentral.com
|
||
mpsport: 4433
|
||
port: 443
|
||
emailcheck: true
|
||
domainauth: false
|
||
tlshash: E7A41E1A56D8D716F7D7729B876E48693F2D19C4761F22B1…
|
||
https: true
|
||
redirport: 80
|
||
</code></pre></div>
|
||
<p>This is a typical response for the “serverinfo” command and a good way to test that everything is working as expected. </p>
|
||
<h3 id="meshctrl-login-using-the-server-login-key">Login using the server login key</h3>
|
||
<p>This technique needs some setup, but allows MeshCtrl to login as any account without knowing the password of the account, making it very powerful. Care must be taken when doing this and it’s recommended to only be done on the local server itself unless you know when you are doing. </p>
|
||
<p><img alt="" src="../meshctrl/images/2022-05-16-21-50-39.png" /></p>
|
||
<p>In this technique, we will get a special encryption key from the server and use this to generate a login token to the server. First, we must activate the login token feature of the server by setting “AllowLoginToken” to “true” in the “settings” section of config.json: </p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"AllowLoginToken"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>Then run the MeshCentral server with the --logintokenkey parameter, you should see something like this: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral --logintokenkey
|
||
f3bd69a08a2dde4a3423bec8f20d8626b1e6365381f2d9919e7dfe256ace9cbbdea66bed2bdcd00b71eea9d7c727cb6eb37f3148c0c2d240d5ed44c8f3f6795a479c949159dad366571fea4db7f31c24
|
||
</code></pre></div>
|
||
<p>The hex value presented here is a sensitive secret that allows anyone to create login tokens that can be used for user impersonation. This key is used when MeshCentral does server peering and load balancing for example. You should save this key in a file, for example “key.txt”, you can do it like this: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral –logintokenkey > key.txt
|
||
</code></pre></div>
|
||
<p>Now that you have the server key, you can use MeshCtrl like this: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt --loginuser admin
|
||
</code></pre></div>
|
||
<p>Instead of using a password, we use the key file instead. MeshCtrl will generate a time limited cookie and use that to login as “admin”. Since “admin” is the default username for MeshCtrl, we can omit this parameter: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt
|
||
</code></pre></div>
|
||
<p>Like the username and password example above, the result will be the server information we requested. Something like this: </p>
|
||
<div class="highlight"><pre><span></span><code>name: devbox.meshcentral.com
|
||
mpsname: devbox.meshcentral.com
|
||
mpsport: 4433
|
||
port: 443
|
||
emailcheck: true
|
||
domainauth: false
|
||
tlshash: E7A41E1A56D8D716F7D7729B876E48693F2D19C4761F22B1…
|
||
https: true
|
||
redirport: 80
|
||
</code></pre></div>
|
||
<h3 id="meshctrl-login-into-a-different-domain">Login into a different domain</h3>
|
||
<p>So far, we have seen how to login to a MeshCentral server using a username/password or username/key technique for the default domain. MeshCentral supports many domains at once with each of the domain having its own set of users, groups and administrators. </p>
|
||
<p><img alt="" src="../meshctrl/images/2022-05-16-21-54-38.png" /></p>
|
||
<p>To do this, using the username and password, we have to tell MeshCtrl to login using the URL that would be used to access that domain, for example: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl serverinfo --url wss://server/domainname --loginuser "admin" --loginpass "mypassword"
|
||
</code></pre></div>
|
||
<p>or for servers have a DNS name for a domain: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl serverinfo --url wss://domainname.server --loginuser "admin" --loginpass "mypassword"
|
||
</code></pre></div>
|
||
<p>Note the "--url" argument is different and so, the server will see MeshCtrl access the server using a different domain. </p>
|
||
<p>Doing a domain login using the login is key file is a bit different. We need to specify both the url to access that domain and specify the domain name explicitly using the --domain argument. For example: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt --url wss://server/domainname --domain mycustomer
|
||
</code></pre></div>
|
||
<p>So, we add both the url to access the correct domain and the domain name explicitly. The domain name must be exactly the one that is used in the domain section of the config.json for of MeshCentral. For example, if the MeshCentral config.json file looks like this: </p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"myserver.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"Port"</span><span class="p">:</span><span class="w"> </span><span class="mi">443</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Default domain"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"customer1"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"dns"</span><span class="p">:</span><span class="w"> </span><span class="s2">"c1.myserver.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Customer1 domain"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>The domain login for MeshCtrl with a key file would look like this: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt --url wss://c1.myserver.com --domain customer1
|
||
</code></pre></div>
|
||
<p>In the next section, we start making use of MeshCtrl to do useful things on the server. From now on, we will omit the login arguments, but note that they are required for all commands. </p>
|
||
<h2 id="meshctrl-making-use-of-meshctrl">Making use of MeshCtrl</h2>
|
||
<p>We can start doing useful operations with MeshCtrl. The current list of operations are: </p>
|
||
<div class="highlight"><pre><span></span><code>edituser
|
||
listusers
|
||
listusersessions
|
||
listdevicegroups
|
||
listdevices
|
||
listusersofdevicegroup
|
||
listevents
|
||
logintokens
|
||
serverinfo
|
||
userinfo
|
||
adduser
|
||
removeuser
|
||
adddevicegroup
|
||
removedevicegroup
|
||
editdevicegroup
|
||
broadcast
|
||
showevents
|
||
addusertodevicegroup
|
||
removeuserfromdevicegroup
|
||
addusertodevice
|
||
removeuserfromdevice
|
||
sendinviteemail
|
||
generateinvitelink
|
||
config
|
||
movetodevicegroup
|
||
deviceinfo
|
||
editdevice
|
||
addusergroup
|
||
listusergroups
|
||
removeusergroup
|
||
runcommand
|
||
shell
|
||
upload
|
||
download
|
||
deviceopenurl
|
||
devicemessage
|
||
devicetoast
|
||
addtousergroup
|
||
removefromusergroup
|
||
removeallusersfromusergroup
|
||
devicesharing
|
||
devicepower
|
||
indexagenterrorlog
|
||
agentdownload
|
||
report
|
||
</code></pre></div>
|
||
<p>You can get this list by just running MeshCtrl without any argument and can get more information on each action by typing “meshctrl help [action]” </p>
|
||
<p><img alt="example" src="../meshctrl/images/amt_commands.png" /></p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Note that when using Intel AMT only (no agent) you can do wake (on) and power off and reset from the group action. MeshCentral should automatically using Intel AMT to perform these actions when you select "Wake-up devices", "Power off devices" or "Reset devices".</p>
|
||
</div>
|
||
<h3 id="meshctrl-gathering-information">Gathering information</h3>
|
||
<p>The following commands are really easy to use: serverinfo, userinfo, listusers, listdevices, listdevicegroups. They just request information from the server. Note that for these commands, you can optionally use “--json" to receive the response in JSON format. For example, getting the list of users will look like this: </p>
|
||
<div class="highlight"><pre><span></span><code>node meshctrl.js listusers
|
||
id, name, email
|
||
---------------
|
||
"admin", "admin", "username@domain.com"
|
||
"joe", "joe", "joe@domain.com"
|
||
"mytestuser", "MyTestUser", "a@a.com"
|
||
"test.user", "test.user", "test.user@user.com"
|
||
</code></pre></div>
|
||
<p>In the --json argument is used, it looks like this: </p>
|
||
<div class="highlight"><pre><span></span><code>node meshctrl.js listusers --json
|
||
{
|
||
"_id": "user//admin",
|
||
"name": "admin",
|
||
"creation": 1417814230,
|
||
"siteadmin": 4294967295,
|
||
…
|
||
</code></pre></div>
|
||
<p>The JSON version is much long and contain much more information. This format can be useful if you take the output of MeshCtrl and dump it into a file for later parsing. One really useful command is “listdevices” that just displays all the devices in the account grouped by device groups. For example: </p>
|
||
<div class="highlight"><pre><span></span><code>node meshctrl listdevices
|
||
|
||
Device group: "Lab Computers"
|
||
id, name, icon, conn, pwr, ip
|
||
-----------------------------
|
||
p3HOhDapgT@VyO$upGJYxEa$v4YCY76Y2G@hOGmJnbPXjkSHP@AgJ1M6FkqSEUqg, "raspberrypi", 5, 1, 1
|
||
yjbMXlQBf09TSIqKlkwrRucm767TcXfNbSinQWXgpdBBY5MEU1gg0kzshwiwFCOp, "tinkerboard", 5, 1, 1
|
||
DRvCLkYIgk744tqqMr9Xvy5TK8aXkLoOXUQETnFdFepVQojyFV5gaBi5Gh4f6B6d, "LattePanda", 5, 1, 1
|
||
ggifepc5wqK7sCVnOIjOZy9i9kaJizalIarz7Qwe5bJ4icpLD69zWYpjAaU@sfY$, "MeshLabTop", 1, 5, 1
|
||
ECAI7NO893JoN3ntK7@mbniyDq0qriG82wqGKQF4s8SpXs3NdnvuHR76Bzq14Pik, "MeshLabRight", 1, 1, 1
|
||
fCLFeHaxQ$T6mgICdVkCdkifiU8LNJdU73YknmxfAb@0jBF2BrhTsEIBwgpoCNx$, "DevLinux", 1, 1, 1
|
||
hfbJ7zAgwZK@LQfsZkr1cqTSp6mjjZ3MjGC$v4X8E7HM1cZEnlGBgcorELu1hZWe, "AmtMachine11", 1, 1, 1
|
||
YRGm4AQVRR38Ypisuo40KhvBGhDl2pE5YCp4j4eIbLaX3kmH3tmumOUbxb44A@Rh, "CoffeeTable", 1, 1, 1
|
||
PpMJiPxtjRjfoEal$9RHdm5s31BaqDSbGc3329s49rzcXcVuTDvm4VO0YllO5XR7, "DevBox", 1, 0, 0
|
||
tyR7l2j5@wOjDeRbOQNfjU7xB$ss6VZQPDkFsALPzJ4zbTI4IamV$OdwHeqiXV0K, "MeshLabLeft", 1, 5, 1
|
||
i@BNTAHB5NMtDyrHMiCaz3GzYlJUUQn7qZZfh@N6271DWAM3EH6ujRNPc2snGXYX, "raspberrypi", 5, 1, 1
|
||
2E$CjXw2Aldh3DGAzSNo5qTSgEhd4OTWcO9KGBi9ja4EOxEUHq8J1135Y2IvxOlX, "AmtMachine7", 1, 5, 1
|
||
0Ab3O@4fgHjwVOpC0qaARfURTtKCa@QjxWPDpT5WQ0Wz5s4OvRWAgeoGT9j8k5JF, "RaspberryPi", 5, 1, 1
|
||
|
||
Device group: "IntelAMT only"
|
||
id, name, icon, conn, pwr, ip
|
||
-----------------------------
|
||
LN8qsH634RGjDwATIOd3ICzfKrB@t@ERow8AEyDndyAs3yqwfrfhEaMPABMg53cg, "AmtMachine7", 0, 0, 0
|
||
Ea3GcF$EoMnDEc9Tbz$Vu9wnmTziqqcOZ0URSdYeuVn4LU9LLMT@91P5s1WLSgVA, "DevBox", 0, 0, 0
|
||
</code></pre></div>
|
||
<p>It’s also possible to list only the display the list of devices for a single group. Just add --id followed by the group identifier. You can find the group identifier using the “DeisplayDeviceGroups” command. For example: </p>
|
||
<div class="highlight"><pre><span></span><code>node meshctrl listdevices --id 7b4b43cdad850135f36ab31124b52e47c167fba055…
|
||
|
||
id, name, icon, conn, pwr, ip
|
||
-----------------------------
|
||
p3HOhDapgT@VyO$upGJYxEa$v4YCY76Y2G@hOGmJnbPXjkSHP@AgJ1M6FkqSEUqg, "raspberrypi", 5, 1, 1
|
||
yjbMXlQBf09TSIqKlkwrRucm767TcXfNbSinQWXgpdBBY5MEU1gg0kzshwiwFCOp, "tinkerboard", 5, 1, 1
|
||
DRvCLkYIgk744tqqMr9Xvy5TK8aXkLoOXUQETnFdFepVQojyFV5gaBi5Gh4f6B6d, "LattePanda", 5, 1, 1
|
||
ggifepc5wqK7sCVnOIjOZy9i9kaJizalIarz7Qwe5bJ4icpLD69zWYpjAaU@sfY$, "MeshLabTop", 1, 5, 1
|
||
ECAI7NO893JoN3ntK7@mbniyDq0qriG82wqGKQF4s8SpXs3NdnvuHR76Bzq14Pik, "MeshLabRight", 1, 1, 1
|
||
fCLFeHaxQ$T6mgICdVkCdkifiU8LNJdU73YknmxfAb@0jBF2BrhTsEIBwgpoCNx$, "DevLinux", 1, 1, 1
|
||
hfbJ7zAgwZK@LQfsZkr1cqTSp6mjjZ3MjGC$v4X8E7HM1cZEnlGBgcorELu1hZWe, "AmtMachine11", 1, 1, 1
|
||
YRGm4AQVRR38Ypisuo40KhvBGhDl2pE5YCp4j4eIbLaX3kmH3tmumOUbxb44A@Rh, "CoffeeTable", 1, 1, 1
|
||
PpMJiPxtjRjfoEal$9RHdm5s31BaqDSbGc3329s49rzcXcVuTDvm4VO0YllO5XR7, "DevBox", 1, 0, 0
|
||
tyR7l2j5@wOjDeRbOQNfjU7xB$ss6VZQPDkFsALPzJ4zbTI4IamV$OdwHeqiXV0K, "MeshLabLeft", 1, 5, 1
|
||
i@BNTAHB5NMtDyrHMiCaz3GzYlJUUQn7qZZfh@N6271DWAM3EH6ujRNPc2snGXYX, "raspberrypi", 5, 1, 1
|
||
2E$CjXw2Aldh3DGAzSNo5qTSgEhd4OTWcO9KGBi9ja4EOxEUHq8J1135Y2IvxOlX, "AmtMachine7", 1, 5, 1
|
||
0Ab3O@4fgHjwVOpC0qaARfURTtKCa@QjxWPDpT5WQ0Wz5s4OvRWAgeoGT9j8k5JF, "RaspberryPi", 5, 1, 1
|
||
</code></pre></div>
|
||
<p>You can also add “--count" to just return the number of devices instead of displaying them. An example of this would be: </p>
|
||
<div class="highlight"><pre><span></span><code>node meshctrl listdevices --id 7b4b43cdad850135f36ab31124b52e47c167fba055… --count
|
||
13
|
||
</code></pre></div>
|
||
<p>Here we see that in a specific device group, there are 13 devices.</p>
|
||
<h3 id="meshctrl-adding-and-removing-accounts">Adding and removing accounts</h3>
|
||
<p>MeshCtrl can be used to add and remove user accounts. This is great is you want to automate MeshCentral in some situations. Normally, an administrator can go to the “My Users” tab and press “New Account…” button to create a new account. </p>
|
||
<p><img alt="" src="../meshctrl/images/2022-05-16-22-04-06.png" /></p>
|
||
<p>With MeshCtrl the same process can be accomplished using the following command line:</p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl adduser --user SampleUser --pass SamplePassword
|
||
</code></pre></div>
|
||
<p>This will create a basic user account with the specified “SampleUser” username and “SamplePassword” password. In addition to the basic example above, there are plenty of additional arguments that can be used. There is a list: </p>
|
||
<div class="highlight"><pre><span></span><code>--email [email] - New account email address.
|
||
--emailverified - New account email is verified.
|
||
--resetpass - Request password reset on next login.
|
||
--siteadmin - Create the account as full site administrator.
|
||
--manageusers - Allow this account to manage server users.
|
||
--fileaccess - Allow this account to store server files.
|
||
--serverupdate - Allow this account to update the server.
|
||
--locked - This account will be locked.
|
||
--nonewgroups - Account will not be allowed to create device groups
|
||
--notools - Account not see MeshCMD download links.
|
||
</code></pre></div>
|
||
<p>Instead of specifying a password, one can specify “--randompass" to have MeshCtrl generate a random password, this is typically use along with “--resetpass" and “--email" to cause the user to perform a password reset the first time a login occurs. </p>
|
||
<p>The permission arguments are used to grant server permissions to the new account. The “-- siteadmin" argument will grant this account full site administrator rights and all other permission arguments are ignored. The other permission arguments can be combined. </p>
|
||
<p>To remove a user account, use the following command: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl removeuser --userid SampleId
|
||
</code></pre></div>
|
||
<p>Note that when creating a new user, the username is passed in. However, when removing a user account, the userid is used. One can get the list of userid’s by using the “ListUsers” command. </p>
|
||
<p>MeshCtrl will return “ok” if the command is successful and the account will be added in real-time to the “My Users” tab on the website. </p>
|
||
<h3 id="meshctrl-creating-and-removing-device-groups">Creating and removing device groups</h3>
|
||
<p>MeshCtrl can be used to add and remove device groups. When a group is created, it’s added in the account that MeshCtrl is logged into and that account gets full rights over that device group. Typically, a new device group is created using the “Add Device Group” link in the main website. </p>
|
||
<p><img alt="" src="../meshctrl/images/2022-05-16-22-06-35.png" /></p>
|
||
<p>A group has a name, type and optionally a description text. To add a device group using MeshCtrl, we use the “AddDeviceGroup” command like this: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl adddevicegroup --name "Sample group name" --desc "Sample description"
|
||
</code></pre></div>
|
||
<p>Here we specify the name and description of the new device group. This will create a normal device group that requires agents to be installed on each computer. You can also create an agent-less Intel AMT device group by adding the "--amtonly" argument. Once done, MeshCtrl will return “ok" and the group will be created in the logged in account in real-time. </p>
|
||
<p>You can delete a group by using the “RemoveDeviceGroup” command like this: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl removedevicegroup --id 7b4b43cd…dc89fe0e581c
|
||
</code></pre></div>
|
||
<p>To remove a device group, the group identifier needs to be specified. You can get that identifier using the "ListDeviceGroups" command. For device groups, the group identifier is a long hex value. </p>
|
||
<h3 id="meshctrl-adding-and-removing-users-from-device-groups">Adding and removing users from device groups</h3>
|
||
<p>Once you created user account and device groups, the next important operation is to connect the two and grant users access to some device groups. In the web interface, this is typically done by clicking on a device group and managing the users in that page. </p>
|
||
<p><img alt="" src="../meshctrl/images/2022-05-16-22-20-44.png" /></p>
|
||
<p>To do this, you first have to get the user and group identifiers. You can get these using the “listusers” and “listdevicegroups” commands. Then, you can for example do this: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl addusertodevicegroup --id 7b4b43cd…dc89fe0e581c --userid bob --fullrights
|
||
</code></pre></div>
|
||
<p>Typically, the group identifier is a long hex value. The command will add user “bob” to a given group with full rights. You can also add a user to a group with only some rights, the list is as follows: </p>
|
||
<div class="highlight"><pre><span></span><code> --fullrights - Allow full rights over this device group.
|
||
--editgroup - Allow the user to edit group information.
|
||
--manageusers - Allow the user to add/remove users.
|
||
--managedevices - Allow the user to edit device information.
|
||
--remotecontrol - Allow device remote control operations.
|
||
--agentconsole - Allow agent console operations.
|
||
--serverfiles - Allow access to group server files.
|
||
--wakedevices - Allow device wake operation.
|
||
--notes - Allow editing of device notes.
|
||
--desktopviewonly - Restrict user to view-only remote desktop.
|
||
--limiteddesktop - Limit remote desktop keys.
|
||
--noterminal - Hide the terminal tab from this user.
|
||
--nofiles - Hide the files tab from this user.
|
||
--noamt - Hide the Intel AMT tab from this user.
|
||
</code></pre></div>
|
||
<p>Note that if “fullrights” are granted, all other access right arguments are ignored. If successful, MeshCtrl will display “ok”, otherwise it will show an error message. </p>
|
||
<p>To remove a user from a group, use the “removeuserfromdevicegroup” command. For example: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node_modules/meshcentral/meshctrl removeuserfromdevicegroup --id 7b4b43cd…dc89fe0e581c --userid bob
|
||
</code></pre></div>
|
||
<p>The syntax of this command is identical to the “addusertodevicegroup” command, but there are no rights arguments. MeshCtrl will also display “ok” if the command got processed correctly. </p>
|
||
<h3 id="meshctrl-message-broadcast">Message Broadcast</h3>
|
||
<p>One fun command the MeshCtrl offers is the “broadcast” command. It sends a short notification message that all connected users will see in real-time. For example, you can do this: </p>
|
||
<div class="highlight"><pre><span></span><code>node ./node\_modules/meshcentral/meshctrl broadcast --msg "This is a test"
|
||
</code></pre></div>
|
||
<p>All connected users will see this: </p>
|
||
<p><img alt="" src="../meshctrl/images/2022-05-16-22-23-40.png" /></p>
|
||
<p>The broadcast command is great for notifying users of upcoming server downtime or other events. </p>
|
||
<h2 id="meshctrl-conclusion">Conclusion</h2>
|
||
<p>MeshCtrl is an essential tools in every MeshCentral administrator’s tool box. It allows administrators to automate various MeshCentral management tasks which can be useful for large scale management of many devices and users. </p>
|
||
<h2 id="meshctrl-license">License</h2>
|
||
<p>MeshCtrl and this document are both opens source and licensed using Apache 2.0, the full license can be found at <a href="https://www.apache.org/licenses/LICENSE-2.0">https://www.apache.org/licenses/LICENSE-2.0</a> </p></section><section class="print-page" id="meshrouter" heading-number="4.3"><h1 id="meshrouter-meshcentral-router">MeshCentral Router</h1>
|
||
<p><img alt="" src="../meshrouter/images/Aspose.Words.954ea56c-626b-416a-8b2a-efde10ebd3a9.002.png" /></p>
|
||
<p>MeshCentral Router Guide <a href="https://meshcentral.com/docs/MeshCentral2RouterUserGuide.pdf">as .pdf</a> <a href="../documents/MeshCentral%20Router%20User%20Guide%20v0.0.2.odt">as .odt</a></p>
|
||
<h2 id="meshrouter-video-walkthru">Video Walkthru</h2>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/BubeVRmbCRM" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<h2 id="meshrouter-abstract">Abstract</h2>
|
||
<p>This document takes a look at MeshCentral Router, a Windows application that performs TCP and UDP port mapping from a local machine to any remote computer thru a MeshCentral servers. This document should allow the user to Internet relay traffic thru NAT routers and firewalls. </p>
|
||
<h2 id="meshrouter-introduction">Introduction</h2>
|
||
<p>MeshCentral is a remote management web site that connects users to remote computers over a local network or the internet. In addition to remote management features, MeshCentral is capable of relaying TCP and UDP traffic thru the server and thru mesh agents installed on remote computers. This feature can be useful to, for example, perform a remote desktop session using RDP or route custom traffic that would otherwise be difficult to route. </p>
|
||
<h2 id="meshrouter-downloading">Downloading</h2>
|
||
<p>MeshCentral router is a Windows application that comes built-into the MeshCentral server or can
|
||
be downloaded at: <a href="https://meshcentral.com/tools/MeshCentralRouter.exe">https://meshcentral.com/tools/MeshCentralRouter.exe</a></p>
|
||
<p>It’s probably best to use the MeshCentral router that comes with your version of the MeshCentral
|
||
server as the two will likely be most compatible. A given MeshCentral Router version may not
|
||
work with any MeshCentral server versions. On MeshCentral, you can download MeshCentral
|
||
Router with this link:</p>
|
||
<p><img alt="Download" src="../meshrouter/images/download-link.png" /></p>
|
||
<p><em>The router link will only show up on Windows browsers.</em></p>
|
||
<h2 id="meshrouter-login">Login</h2>
|
||
<p>MeshCentral router will need to login to your MeshCentral server just like any browser. You can
|
||
do this by entering the server name and account username and password. Depending on your
|
||
server and account situation, you may see some or all of the following screens.</p>
|
||
<p><img alt="Login" src="../meshrouter/images/login.png" /></p>
|
||
<p>If the second factor authentication is required, MeshCentral Router does not support hardware
|
||
keys (WebAuthn), but does support the YubiKey™ OTP.</p>
|
||
<h2 id="meshrouter-creating-port-maps">Creating Port Maps</h2>
|
||
<p>Once logged in, you can start adding port maps using the “Add Map…” and “Add Relay Map…”
|
||
buttons on the bottom right. You can then create a map and open the associated application
|
||
using the “Open…” button and remote to port map using the “Remove” button.</p>
|
||
<p><img alt="port_maps" src="../meshrouter/images/port_maps.png" /></p>
|
||
<p>There are two different types of ports mappings. A normal port map and a relay port map. A
|
||
normal port map will route packets to the selected destination computer that is running the mesh
|
||
agent as shown here.</p>
|
||
<p><img alt="port_maps" src="../meshrouter/images/port_maps2.png" /></p>
|
||
<p>A relay port map will route traffic thru the server and thru the remote agent to a target IP address
|
||
on the remote agent’s network as shown here.</p>
|
||
<p><img alt="" src="../meshrouter/images/port_maps3.png" /></p>
|
||
<p>Note that all traffic is encrypted using TLS from MeshCentral Router to the MeshCentral server
|
||
and from the server to the MeshAgent. The server and the agent do have access the traffic so it’s
|
||
recommended to use port mappings to tunnel data that is also encrypted for that end-to-end
|
||
encryption is assured.</p>
|
||
<h2 id="meshrouter-custom-apps">Custom Apps</h2>
|
||
<p><em>Starting v1.0.21</em></p>
|
||
<p><img alt="1" src="../meshrouter/images/custom_apps1.png" /></p>
|
||
<p><img alt="2" src="../meshrouter/images/custom_apps2.png" /></p>
|
||
<p><img alt="3" src="../meshrouter/images/custom_apps3.png" /></p>
|
||
<h2 id="meshrouter-command-line-arguments">Command Line Arguments</h2>
|
||
<p>MeshCentral router can be run with command line arguments to make it quicker and easier to
|
||
use. The arguments range from debugging to being able to quickly login and setting up port
|
||
maps.</p>
|
||
<div class="highlight"><pre><span></span><code>-debug
|
||
</code></pre></div>
|
||
<p>Causes MeshCentral Router to generate a “debug.log” dump file that can be useful for
|
||
debugging.</p>
|
||
<div class="highlight"><pre><span></span><code>-host:<hostname>
|
||
-user:<username>
|
||
-pass:<password>
|
||
-ignorecert
|
||
</code></pre></div>
|
||
<p>This set of command line arguments make logging into the MeshCentral server easier. Note that
|
||
specifying the password using a command line argument may not be secure as the command
|
||
shell can record the password in the command history. The “ignorecert” argument is not
|
||
recommended as it’s going to cause MeshCentral Router to ignore untrusted server certificates.
|
||
This should only be used for debugging.</p>
|
||
<div class="highlight"><pre><span></span><code>-map:<protocol>:<localport>:<computername>:<app>:<remoteport>
|
||
</code></pre></div>
|
||
<p>The “map” argument will automatically create a network map once MeshCentral Router is logged
|
||
In. The protocol must be “TCP” or “UDP, the local port can be 0 for any. The computer name is
|
||
the server-side name of the computer, if many computers have the same one, one of them will be
|
||
selected. The app can be empty for a custom application, or can be “HTTP”, “HTTPS”, “RDP”,
|
||
“PuTTY” or “WinSCP”. For the UDP protocol, no apps are currently supported so it should be left
|
||
blank. For example you can use:</p>
|
||
<div class="highlight"><pre><span></span><code>-map:TCP:0:<span class="s2">"MyComputer"</span>:HTTP:80
|
||
-map:UDP:1235:<span class="s2">"MyComputer"</span>::1234
|
||
</code></pre></div>
|
||
<p>The first example will map a random local port to port 80 of “MyComputer” and is expected for
|
||
use with HTTP traffic. The second example maps local UDP port 1235 to port 1234 on
|
||
“MyComputer”. It’s best for the computer name to be in quotes.</p>
|
||
<p>In addition to port mapping, you can also setup relay maps where a remote computer is used as a
|
||
traffic relay like this:</p>
|
||
<div class="highlight"><pre><span></span><code>-relaymap:<protocol>:<localport>:<computername>
|
||
<span class="w"> </span>:<app>:<remoteip>:<remoteport>
|
||
</code></pre></div>
|
||
<p>This will relays a local port to thru the server and thru a remote agent to a target IP address and
|
||
port. For example:</p>
|
||
<div class="highlight"><pre><span></span><code>-relaymap:TCP:555:<span class="s2">"MyComputer"</span>:HTTP:192.168.1.1:80
|
||
</code></pre></div>
|
||
<p>This will relay local port 555 to a 192.168.1.1:80 for HTTP traffic. A typical use of this is to be able
|
||
to remotely configure a home router from anywhere on the Internet.</p>
|
||
<div class="highlight"><pre><span></span><code>-all
|
||
</code></pre></div>
|
||
<p>The “all” switch will bind local ports to all network interfaces so that other computers on the
|
||
network can use the port maps provided by MeshCentral Router. By default, local ports will be
|
||
bound to the loopback interface so that only local application can use the port mappings.</p>
|
||
<div class="highlight"><pre><span></span><code>-tray
|
||
</code></pre></div>
|
||
<p>The “tray” switch will place MeshCentral Router on the Windows system tray instead of the
|
||
normal application bar.</p>
|
||
<h2 id="meshrouter-meshcentral-router-with-saml-or-oauth">MeshCentral Router with SAML or OAuth</h2>
|
||
<p>You can't use the MeshCentral Router (MCR) login dialog box to login to a server that uses SAML or OAuth. However, you can still use MCR</p>
|
||
<ol>
|
||
<li>Download MCR and run it. </li>
|
||
<li>In the first dialog box, there will be an "Install..." button to setup MeshCentral router with the "mcrouter://" protocol in your system registry. </li>
|
||
<li>Once done, close MCR.</li>
|
||
<li>Now log into the web UI of your MeshCentral server. Go in the bottom of the "My Devices" tab, hit the "Router" link and hit "Launch MeshCentral Router".</li>
|
||
<li>This will launch the router and connect directly to your server using a login cookie.</li>
|
||
</ol>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The only drawback is you will have to manually load mappings saved in an .mcrouter file. When not using SAML, you can click on the .mcrouter file to load the mappings and MCR at the same time. </p>
|
||
</div>
|
||
<h2 id="meshrouter-conclusion">Conclusion</h2>
|
||
<p>MeshCentral Router is a free, open source tool for routing TCP and UDP traffic over the internet. It’s a powerful as it allows for any traffic to go thru NAT routers and firewalls while being encrypted using TLS. </p>
|
||
<h2 id="meshrouter-license">License</h2>
|
||
<p>MeshCentral, MeshCentral Router and this document are all opens source and licensed using
|
||
Apache 2.0, the full license can be found at <a href="https://www.apache.org/licenses/LICENSE-2.0">https://www.apache.org/licenses/LICENSE-2.0</a>.</p></section><section class="print-page" id="intelamt" heading-number="4.4"><h1 id="intelamt-intel-amt">Intel AMT</h1>
|
||
<p>Intel AMT Guide <a href="../documents/MeshCentral%20Intel%20AMT%20Guide%20v0.0.1.odt">as .odt</a></p>
|
||
<h2 id="intelamt-video-walkthru">Video Walkthru</h2>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/naWKE3rT6e8" frameborder="0" allowfullscreen></iframe>
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/TaKsFEVaMpg" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<h2 id="intelamt-abstract">Abstract</h2>
|
||
<p>This user guide contains all essential information for activating and using Intel® Active Management Technology (Intel® AMT) with MeshCentral. We will review how to activate, connect to and use Intel AMT features and how this benefit administrators that want to manage computers remotely. This document expect the reader to already be familiar with how to install and operate MeshCentral and have a basic understanding of how Intel® AMT works.</p>
|
||
<h2 id="intelamt-history-of-amt">History of AMT</h2>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/_SXT0Gr4Mls" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<h2 id="intelamt-introduction">Introduction</h2>
|
||
<p>MeshCentral is a free open source web-based remote computer management software and it fully supports Intel® Active Management Technology (Intel® AMT). MeshCentral does not require that computers it manages support Intel AMT, but if a remote computer has this capability, MeshCentral will make use of it.</p>
|
||
<p>Intel AMT can be seen as a hardware based management agent that is built into some Intel PC’s. Once setup, Intel AMT can be used to remotely manage a computer regardless of the operating system health. It can be used to power on a computer when it’s in soft-off state or to provide enhanced monitoring and security to remote systems.</p>
|
||
<p>Once setup, a computer can have up to management connections to MeshCentral. One of them by the Mesh Agent that lives in the operating system and another connection from Intel AMT. When remote management is made using an operating system agent, we call this “in-band management” and when management is done using a hardware based agent like Intel AMT, we call this “out-of-band management”</p>
|
||
<p><img alt="" src="../intelamt/images/2022-05-16-23-08-15.png" /></p>
|
||
<p>MeshCentral can support computers that have either or both agents. So, you can setup a computer with just the Mesh Agent, just Intel AMT or both. In this document we will show how to install computers with both agent connections or with just Intel AMT. When Intel AMT is used alone, we call this “agent-less” as there will be no operating system software required to remotely manage the computer.</p>
|
||
<p>The Mesh Agent and Intel® AMT have very different and complementary capabilities and so, it’s often beneficial to use both and one will offer features the other can’t provide. Here are some of the benefits each has to offer:</p>
|
||
<p>Mesh Agent</p>
|
||
<ul>
|
||
<li>Fast remote desktop / clipboard access.</li>
|
||
<li>Remote access to operating system files.</li>
|
||
<li>Remote chat and other OS features.</li>
|
||
</ul>
|
||
<p>Intel® AMT</p>
|
||
<ul>
|
||
<li>Remote desktop even when the agent or operating system is not functional.</li>
|
||
<li>Remote access to BIOS.</li>
|
||
<li>Connectivity when soft-off / sleeping.</li>
|
||
<li>Remote power actions.</li>
|
||
</ul>
|
||
<p>If you are looking into managing remote computers that would be difficult to physically get access to for remote support or maintenance, one should probably look at getting a PC with Intel AMT.</p>
|
||
<h2 id="intelamt-bare-metal-activation-server">Bare-Metal Activation Server</h2>
|
||
<p>The <code>AmtProvisioningServer</code> section in the <code>settings</code> section of the config.json will enable this feature. MeshCentral will then listen for activation requests, match against your ACM activation certificates and if everything goes well, will activate and add the device to a Intel AMT only device group. No agent or MeshCMD is involved.</p>
|
||
<p>This bare-metal activation server is not enabled by default and only makes sense when activating devices on the local network.</p>
|
||
<p>Once enabled, Intel AMT can send “hello” data to the MeshCentral provisioning server on port 9971 and MeshCentral will respond by connecting back, authenticating, and activating Intel AMT. MeshCentral will then log the event, add the device to a pre-defined agent-less device group and complete any remaining configuration. A trusted CA certificate is required to perform this operation fully automatically.</p>
|
||
<p><img alt="baremetal" src="../intelamt/images/amtprovisioningserver.png" /></p>
|
||
<h2 id="intelamt-meshcentral-group-types">MeshCentral Group Types</h2>
|
||
<p>Once MeshCentral is installed, a user will typically create a new device group. Here is the first hint that MeshCentral supports Intel AMT. Device groups come in two types. You can manage using a software agent, or using Intel AMT only.</p>
|
||
<p><img alt="" src="../intelamt/images/2022-05-16-23-10-40.png" /></p>
|
||
<p>Note that if you use the OS agent to manage computers, you can also set and use Intel AMT. However, if you opt to create an Intel AMT only group, then Mesh Agents are not supported. One can create groups of both types in order to manage devices that have and don’t have the Mesh Agent installed.</p>
|
||
<p><img alt="" src="../intelamt/images/2022-05-16-23-10-59.png" /></p>
|
||
<p>The main benefit of “Intel AMT only” group is if someone does not want to install a background agent on remote systems or already have a remote management solution and intends to only use MeshCentral to supplement the existing solution with Intel AMT features.</p>
|
||
<p>Once a group is created, the links MeshCentral provides to on-board devices will change depending on the group type and how the server is setup. The device on-boarding links are located in the “My Devices” page, next to the group name.</p>
|
||
<p><img alt="" src="../intelamt/images/2022-05-16-23-11-24.png" /></p>
|
||
<p>If the MeshCentral server is setup in “LAN mode” or “Hybrid mode”, options will be available to add computers on the local network. If you have an Intel AMT computer that is already activated, you can select the “Add Local” or “Scan Network” options in the “Intel AMT only” group type and start adding local network computers this way. If MeshCentral is in “WAN mode”, you will need to setup Intel AMT to connect back to MeshCentral using a feature called “Client Initiated Remote Access” or CIRA for short. We will cover that in a later section.</p>
|
||
<h2 id="intelamt-client-initiated-remote-access-mps-server">Client Initiated Remote Access & MPS server</h2>
|
||
<p>Client Initiated Remote Access (CIRA) is a feature of Intel AMT that, then configured, makes Intel AMT connect back to the server using a TLS tunneling connection similar with a SSH tunnel. Once this tunnel connection is established, the server can perform remote management operations on Intel AMT.</p>
|
||
<p>CIRA is great when remotely managing Intel AMT devices over the Internet thru network address translator (NAT) routers where the server would not be able to connect to Intel AMT. This is similar to the Mesh Agent that initiated and keeps an idle connection to the server.</p>
|
||
<p>By default, MeshCentral will be configured to receive Mesh Agent connections on TCP port 443 and Intel AMT connections on TCP port 4433. These port values can be configured in the config.json file of MeshCentral.</p>
|
||
<p><img alt="" src="../intelamt/images/2022-05-16-23-12-04.png" /></p>
|
||
<p>Once connected to port 443, the Mesh agent will using secure HTTPS WebSocket to securely communicate with the server. Intel AMT will use TLS to connect to port 4433 and use a binary tunneling protocol called the Intel AMT Port Forwarding Protocol (APF). You can find documentation on this protocol at the following URL: </p>
|
||
<p><a href="https://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide/HTMLDocuments/MPSDocuments/Intel%20AMT%20Port%20Forwarding%20Protocol%20Reference%20Manual.pdf">https://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide/HTMLDocuments/MPSDocuments/Intel%20AMT%20Port%20Forwarding%20Protocol%20Reference%20Manual.pdf</a></p>
|
||
<p>It’s not necessary to know or understand the details of this protocol, MeshCentral will take care of handling this. In Intel AMT nomenclature, the server that receives a CIRA connection is called a “Management Presence Server” or MPS for short. In other words, MeshCentral has a MPS server on port 4433 ready to receive Intel AMT CIRA connections.</p>
|
||
<p><img alt="" src="../intelamt/images/2022-05-16-23-12-37.png" /></p>
|
||
<p>When MeshCentral is first setup, a self-signed root certificate is created along with a MPS certificate that will be presented when a device connects on port 4433. There is typically no need to use a CA signed & trusted certificate on port 4433 was we only expect Intel AMT computers to connect to this port and we will be loading our self-signed root in Intel AMT for authentication purposes.</p>
|
||
<p>One way to check that the MeshCentral MPS server is running correctly is to use a browser and access port 4433 using HTTPS. The browser will display a warning because the port 4433 certificate is not trusted, but this is expected.</p>
|
||
<p><img alt="" src="../intelamt/images/2022-05-16-23-12-58.png" /></p>
|
||
<p>The CIRA protocol is binary, but MeshCentral will detect that the request is made from a browser and return a short message:</p>
|
||
<div class="highlight"><pre><span></span><code>MeshCentral2 MPS server.
|
||
Intel® AMT computers should connect here.
|
||
</code></pre></div>
|
||
<p>This is practical to make sure connectivity with the MeshCentral MPS server is working. Now that we know the basics of Intel AMT CIRA and the MPS server, we can configure Intel AMT to connect.</p>
|
||
<h2 id="intelamt-activation-certificate-setup">Activation Certificate Setup</h2>
|
||
<p>If you have an Intel AMT activation certificate, you should configure MeshCentral to take advantage of it. Your activation certificate must have been issued by one of the certificate authorities (CA’s) that is trusted by Intel AMT and MeshCentral will need the entire certificate chain to be provided since the entire chain is needed to perform Intel AMT ACM activation.</p>
|
||
<p><img alt="" src="../intelamt/images/2022-05-16-23-13-44.png" /></p>
|
||
<p>The leaf certificate will have the Intel AMT activation option and a specific domain name while the hash of the trusted CA certificate must be trusted by Intel AMT. The certificate chain will have to be setup in the domain section of the MeshCentral config.json file.</p>
|
||
<p>If you have a certificate chain in a .pfx or .p12 format, place that file in the “meshcentral-data” folder and add the “AmtAcmActivation” section in the domain section like so:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"devbox.mesh.meshcentral.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"My Server"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"AmtAcmActivation"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"log"</span><span class="p">:</span><span class="w"> </span><span class="s2">"amtactivation.log"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"certs"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"myamtcert"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"certpfx"</span><span class="p">:</span><span class="w"> </span><span class="s2">"amtcert.pfx"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"certpfxpass"</span><span class="p">:</span><span class="w"> </span><span class="s2">"pfxpassword"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>If you have the certificate chain in PEM format as a set of .crt files and a .key file, start by placing all of the certificate files in the “meshcentral-data” folder and setup the certificate chain like this:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"Cert"</span><span class="p">:</span><span class="w"> </span><span class="s2">"devbox.mesh.meshcentral.com"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"domains"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"My Server"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"AmtAcmActivation"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"log"</span><span class="p">:</span><span class="w"> </span><span class="s2">"amtactivation.log"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"certs"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"myvprocert"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"certfiles"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"amtacm-vprodemo.crt"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"amtacm-intermediate1.crt"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"amtacm-intermediate2.crt"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="s2">"amtacm-root.crt"</span><span class="w"> </span><span class="p">],</span>
|
||
<span class="w"> </span><span class="nt">"keyfile"</span><span class="p">:</span><span class="w"> </span><span class="s2">"amtacm-vprodemo.key"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>It’s important that the leaf certificate file be the first file in the “certfiles” array. The order of the other certificates is not important as MeshCentral will figure out and re-order them correctly. </p>
|
||
<p>Within the new “AmtAcmActivation” section, there is a “log” entry. This is a log file that will contain every activation attempt including the details of the computer being activation and what Intel AMT administrator password was used for activation. This log file should be kept securely as it will contain Intel AMT credentials. It’s also important to have this file as a backup so that Intel AMT credentials are not lost after activation. If MeshCentral can’t write to this log, the activation will not go forward and will fail.</p>
|
||
<p>Once the config.json was modified, restart the server. There will be two indications that the server has the new certificate correctly configured. For “Intel AMT only” groups, a new “Activation” link will show up. Clicking this link will show a command that can be run to perform ACM activation.</p>
|
||
<p><img alt="" src="../intelamt/images/2022-05-16-23-14-42.png" /></p>
|
||
<p>For device groups that operate with a Mesh Agent, you can edit the group and select the “Simple Admin Control Mode” Intel AMT activation policy. This policy is not available unless a correct Intel AMT ACM activation certificate is configured.</p>
|
||
<p><img alt="" src="../intelamt/images/2022-05-16-23-15-04.png" /></p>
|
||
<p>Once setup, Intel AMT will not automatically activate to Intel AMT unless the right situation is met. The Intel AMT activation certificate is for a specific domain name suffix, for example “meshcentral.com”. Intel AMT must be in a situation where this domain can be accepted. One of the following must be true:</p>
|
||
<ul>
|
||
<li>Intel AMT must have a wired Ethernet interface that is connected to a local network with a DHCP server responding with option 15 set to “xxx.meshcentral.com”.</li>
|
||
<li>The name “meshcentral.com” by have been set as “Trusted FQDN” in MEBx.</li>
|
||
<li>The name “meshcentral.com” must have been set using a USB key with a setup.bin file.</li>
|
||
</ul>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/mhq0bsWJEOw" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<p>Once Intel AMT is in a situation where ACM activation can occur, the activation command line can be run or the Mesh Agent will detect this situation and ask the server to perform activation.</p>
|
||
<p><img alt="" src="../intelamt/images/2022-05-16-23-16-05.png" /></p>
|
||
<p>The best way to test this feature is to create an “Intel AMT only” device group and run the MeshCMD command on the remote system to perform activation. If there is a problem, this process should clearly display why ACM activation fails.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
</div>
|
||
<p>Activation over wifi has some additional issues.<br>
|
||
First you need to add your WiFi access point to that wifi configuration to allow CSME to take over WiFi when OS is not functioning. Then it should work.<br>
|
||
Please also make sure you install Intel WiFi driver and Intel LMS package. It should work. You can detach the ethernet and then try connecting to that device using the IP address acquired by WiFi interface.
|
||
See <a href="https://www.intel.com/content/www/us/en/developer/topic-technology/edge-5g/tools/open-amt-cloud-toolkit.html">Open AMT Cloud Toolkit</a> project - a close relative to this project. It has an AMT activation component and newer remote provisioning client can activate locally and also can manage Wi-Fi profile.</p>
|
||
<h2 id="intelamt-intel-amt-mei-and-lms">Intel AMT MEI and LMS</h2>
|
||
<p>Intel Active Management Technology (Intel AMT) can communicate to the local platform using the Management Engine Interface (MEI). We show how your can use that to get Intel AMT information. For more advanced usages, you need to connect using TCP and TLS which requires Intel Local Manageability Service (LMS). We show how MeshCentral's Mesh Agent and MeshCMD have a small version of LMS built-in and how it works</p>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/mStyhe-fSC0" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<h2 id="intelamt-intel-amt-system-defense">Intel AMT System Defense</h2>
|
||
<p>As part of Intel AMT there are hardware filters in the network interface you can setup to match and perform actions on packets. This happens at Ethernet speeds with no slow down and independent of the OS.</p>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/q7RyboI4uew" frameborder="0" allowfullscreen></iframe>
|
||
</div></section></section><section class="print-page" id="how-to-contribute" heading-number="5"><h1 id="how-to-contribute-contribute-to-meshcentral">Contribute to MeshCentral</h1>
|
||
<hr />
|
||
<h2 id="how-to-contribute-contributing-to-meshcentral-via-github-pull-request">📤 Contributing to MeshCentral via GitHub Pull Request</h2>
|
||
<p>If you're looking to contribute beyond translations, such as updating documentation or enhancing the software by adding features or fixing bugs, the process involves several key steps :</p>
|
||
<ol>
|
||
<li>
|
||
<p><strong>Fork the Repository :</strong></p>
|
||
<blockquote>
|
||
<p>Start by forking the <a href="https://github.com/Ylianst/MeshCentral">MeshCentral</a> repository on GitHub.</p>
|
||
<p>This creates a copy of the repository under your own GitHub account, allowing you to make changes without affecting the original project.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Make Your Changes</strong></p>
|
||
<blockquote>
|
||
<ul>
|
||
<li>
|
||
<p>In your forked repository, create a new branch to keep your changes organized. This helps in managing different contributions separately.</p>
|
||
</li>
|
||
<li>
|
||
<p>Make the necessary changes in your repository. This could involve updating documentation files or modifying code to add new features or fix bugs.</p>
|
||
</li>
|
||
</ul>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Review Your Changes :</strong></p>
|
||
<blockquote>
|
||
<p>Before submitting your work, carefully review the changes you’ve made. Check the "Files Changed" section on GitHub to ensure that all modifications are intended and correctly implemented.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Submit a Pull Request</strong></p>
|
||
<blockquote>
|
||
<ul>
|
||
<li>Once your changes are ready and reviewed, submit a pull request (PR) from your branch to the <code>master</code> branch of the main MeshCentral repository.</li>
|
||
<li>When creating the pull request, provide a clear and detailed description of what changes have been made and why. This helps maintainers understand the purpose of your contributions.</li>
|
||
</ul>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Wait for Review :</strong></p>
|
||
<blockquote>
|
||
<p>After submitting your pull request, wait for a project maintainer to review your contribution. Review time can vary depending on the complexity of the changes and the availability of the maintainers.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Respond to Feedback :</strong></p>
|
||
<blockquote>
|
||
<p>The maintainer may request further modifications or provide feedback on your pull request. Be prepared to make additional changes based on their suggestions to ensure that your contribution meets the project’s standards and requirements.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Final Steps :</strong></p>
|
||
<blockquote>
|
||
<p>Once your pull request is approved and merged by a maintainer, your contributions will be incorporated into the MeshCentral project. Congratulations, and thank you for helping improve MeshCentral!</p>
|
||
</blockquote>
|
||
</li>
|
||
</ol>
|
||
<hr />
|
||
<h2 id="how-to-contribute-contribute-to-meshcentrals-multilingual-support">🗣️ Contribute to MeshCentral's Multilingual Support</h2>
|
||
<p>To make MeshCentral multilingual, your contributions are crucial. Follow these steps to translate the interface into various languages.</p>
|
||
<ol>
|
||
<li>
|
||
<p><strong>Remove Local Translations :</strong></p>
|
||
<blockquote>
|
||
<p>Delete <code>translate.json</code> from your <code>meshcentral-data</code> folder. This file contains your local copy of translations, which may become outdated as new features and texts are added.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Access MeshCentral :</strong></p>
|
||
<blockquote>
|
||
<p>Ensure you are logged into MeshCentral.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Open Translation Tool:</strong></p>
|
||
<blockquote>
|
||
<p>Visit <code>https://YOURMESHCENTRALSERVER.COM/translator.htm</code> to access the translation interface.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Choose a Language :</strong></p>
|
||
<blockquote>
|
||
<p>Select the language you wish to translate from the list provided.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Translate Text :</strong></p>
|
||
<blockquote>
|
||
<p>Use the search function or scroll through the list to find text segments you want to translate. Utilize the "show no translations only" checkbox to filter untranslated texts.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Enter Translations :</strong></p>
|
||
<blockquote>
|
||
<p>For each text segment, enter your translation in the bottom box (not the top one) and click <code>SET (F1)</code>.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Repeat Translation :</strong> Continue translating by repeating steps 5 and 6 for other texts as desired.</p>
|
||
</li>
|
||
<li>
|
||
<p><strong>Save and Apply Translations</strong></p>
|
||
<blockquote>
|
||
<ul>
|
||
<li>Click <code>SAVE TO SERVER (F3)</code> to save your translations to <code>meshcentral-data/translate.json</code> locally in your MeshCentral server.</li>
|
||
<li>Optionally, click <code>SAVE TO FILE (F4)</code> to download the <code>translate.json</code> file for offline review or sharing.</li>
|
||
</ul>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Deploy Translations :</strong></p>
|
||
<blockquote>
|
||
<p>Click <code>TRANSLATE SERVER</code> and allow some time for the process to complete (approximately 5-15 minutes depending on server specifications). This command line output will indicate when the translation is complete.</p>
|
||
<p><img alt="" src="../how-to-contribute/images/translation-msg-output.png" /></p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Finalize Changes :</strong></p>
|
||
<blockquote>
|
||
<p>It’s crucial to restart MeshCentral to ensure that the translated files are picked up correctly.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>Share your translations :</strong></p>
|
||
<blockquote>
|
||
<p>Once a language translation is complete, take the latest <code>translation.json</code> and share it by emailing it to the maintainer (Ylianst, <code>ylianst@gmail.com</code>) or by submitting it to the MeshCentral GitHub repository via a pull request.</p>
|
||
</blockquote>
|
||
</li>
|
||
</ol>
|
||
<hr />
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Additional Information :</p>
|
||
<p>If you make any changes to <code>default.handlebars</code>, run the translate server to propagate these modifications to the language-specific handlebar files located in <code>node_modules/meshcentral/views/translations</code>.</p>
|
||
</div>
|
||
<p>By following these steps, you help MeshCentral support any language you choose, making it more accessible worldwide. By sharing your translations with us, you also help make these languages available to other users, improving the community and extending the software's reach.</p></section><section class="print-page" id="design" heading-number="6"><h1 id="design-design-and-architecture">Design and Architecture</h1>
|
||
<p><img alt="" src="../design/images/2022-05-15-12-57-36.jpg" /></p>
|
||
<h2 id="design-video-walkthru">🎬 Video Walkthru</h2>
|
||
<div class="video-wrapper">
|
||
<iframe src="https://www.youtube.com/embed/MOQ0uCUs7_M" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<h2 id="design-abstract">🧾 Abstract</h2>
|
||
<p>This document attempts to describe the architecture and design of the second version of MeshCentral on which work started in late 2016. The document covers the overview of the design, goes in details about the protocol and various decisions and trade-offs. This document is intended for anyone that wants to understand the inner workings of MeshCentral or someone that wants to make a security review of the software. </p>
|
||
<hr />
|
||
<blockquote>
|
||
<p><strong>📌 Note :</strong></p>
|
||
<p>The software and added documentation and tutorial videos are available at :
|
||
<a href="https://www.meshcommander.com/meshcentral2"> https://www.meshcommander.com/meshcentral2 </a></p>
|
||
</blockquote>
|
||
<hr />
|
||
<h2 id="design-introduction">📘 Introduction</h2>
|
||
<p>MeshCentral is a free open source web-based remote computer management software. After over 8 years of working on the first version of MeshCentral, work as moved to version 2 which this document described. In 2010, when MeshCentral v1 was first designed, the Internet was very different. HTML5 and WebSocket did not exists, no such thing as a software container, etc. With MeshCentral version 2, a complete redesign was made to make the software much more in line with modern Internet deployment models. </p>
|
||
<p>The advent of NodeJS, WebSocket, WebRTC and other web technologies coming out in the last 10 years has really made the design of MeshCentral v2 not only possible, but quite amazing. Being able to use a single programming language across platforms to JavaScript. Being able to easily exchange objects using web socket and JSON, being able to scale with WebRTC, deploy quickly with containers, etc. Looking back at the incredible advances in web technologies lead to an almost mandatory MeshCentral redesign. </p>
|
||
<h2 id="design-goals-requirements">🎯 Goals & Requirements</h2>
|
||
<p>The goal of MeshCentral is to be the best open source remote management software in the world. Remote computer management is a big area with many different usages and requirements. To best suite this, it’s important to have software that is as flexible as possible.</p>
|
||
<p>Additionally, there are many other goals : </p>
|
||
<blockquote>
|
||
<ul>
|
||
<li><strong>Must be quick and easy to install.</strong> </li>
|
||
<li><strong>Must install on all major operating systems and platforms.</strong> </li>
|
||
<li><strong>Can be deployed on small computers and the cloud.</strong></li>
|
||
<li><strong>Can be deployed within containers.</strong> </li>
|
||
<li><strong>Can be deployed in many network environments.</strong> </li>
|
||
<li><strong>Must support both software agent and Intel® AMT hardware agent.</strong> </li>
|
||
<li><strong>Must only use open source dependencies.</strong></li>
|
||
<li><strong>Must provide all basic remote management features (desktop, terminal, files…)</strong> </li>
|
||
<li><strong>Must use the network efficiently.</strong></li>
|
||
<li><strong>Must have a real time user interface.</strong> </li>
|
||
<li><strong>Must be easy to use.</strong></li>
|
||
<li><strong>Must be fast.</strong> </li>
|
||
<li><strong>Etc.</strong></li>
|
||
</ul>
|
||
</blockquote>
|
||
<p>Basically, all the requirements you would expect from open source software that can go viral. Since this software is sponsored by Intel, it’s going to support Intel® AMT really well, making it possible to manage a remote computer regardless of its OS or power state. Intel® AMT is not required to use this software, however it’s a great fit. </p>
|
||
<h2 id="design-design-overview">🖥️ Design Overview</h2>
|
||
<p>In this section, we do a very high level overview of MeshCentral’s design. MeshCentral has 3 big components :</p>
|
||
<ul>
|
||
<li><em>The server</em>,</li>
|
||
<li><em>The agent and</em> </li>
|
||
<li><em>The web application</em>. </li>
|
||
</ul>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-01-56.jpg" /></p>
|
||
<p>There is of course more software that support these 3 components like the Windows Server Installer, ClickOnce application, MeshCentral Discovery Tool and more. These will be covered later. Most of the document will focus on these 3 main components. Another component that is significant but not part of the software itself is Intel® AMT (Intel® Active Management Technology). MeshCentral supports Intel AMT that acts like an optional hardware based agent for MeshCentral. </p>
|
||
<p>When it comes to programming languages used, MeshCentral is mostly built with JavaScript with the agent having significant portable C code. This makes things pretty simple since the browser, server and agents can share some of the code. More importantly, JavaScript is great at parsing JSON and so, the main protocol used between the components is JSON over Web Socket. </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-03-25.jpg" /></p>
|
||
<p>It’s important to note that while JavaScript is used in all 3 components, the JavaScript runtime is very different. The JavaScript written to run within a browser sandbox uses different calls than the one running in NodeJS on the server or on the agent with DukTape. </p>
|
||
<p>This is probably a good time to introduce DukTape <a href="https://www.duktape.org/">(https://www.duktape.org/)</a>. Unlike the browser and NodeJS JavaScript engines, DukTape is a less known JavaScript runtime written in C. The agent is built in C code with little smarts other than being able to securely connect back to the server. The server then pushes to the agent a JavaScript file that the agent runs. This makes the agent very flexible since a developers can quickly change the JavaScript that is pushed to the agent and change the agent’s behavior instantly. </p>
|
||
<p>Another interesting design decision is that MeshCentral makes almost no use of RESTful API’s. Instead, almost everything is done using WebSocket. This allows JSON objects to be exchanged fully asynchronously. There is no pushing the refresh button or polling as events are sent by all actors in real time. </p>
|
||
<h2 id="design-meshcentral-server">🗄️ MeshCentral server</h2>
|
||
<p>The MeshCentral server is a NodeJS application that is published on NPM at : <a href="https://www.npmjs.com/package/meshcentral">https://www.npmjs.com/package/meshcentral</a> Many administrators can get started quickly using “npm install meshcentral” once NodeJS is installed. MeshCentral will work on Node 6.x and higher. </p>
|
||
<h2 id="design-dependencies">📦 Dependencies</h2>
|
||
<p>The server makes use of the following dependencies on NPM. These are all automatically installed by NPM when installing MeshCentral. </p>
|
||
<p>Can be found in the file : <code>MeshCentralServer.njsproj</code></p>
|
||
<p>The main takeaway is that MeshCentral is mostly an ExpressJS application. This is not a complete list of dependencies as many of these packages have their own dependencies creating a large tree. The security of these packages is a concern and all of the dependency tree is a concern. In addition to the dependencies that are “hard coded”, there are a few more that are installed only when needed. These are : </p>
|
||
<h3 id="design-node-windows">node-windows</h3>
|
||
<ul>
|
||
<li>
|
||
<p><strong>greenlock, le-store-certbot, le-challenge-fs</strong> :</p>
|
||
<blockquote>
|
||
<p>Installed on all Windows install. Allows background service install: </p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>le-acme-core</strong> :</p>
|
||
<blockquote>
|
||
<p>Installed only when Let’s Encrypt must be used: </p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>mongojs</strong> :</p>
|
||
<blockquote>
|
||
<p>Installed when MongoDB is in used. </p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><strong>nodemailer</strong> :</p>
|
||
<blockquote>
|
||
<p>Installed when SMTP server support is in used. </p>
|
||
</blockquote>
|
||
</li>
|
||
</ul>
|
||
<p>MeshCentral will run <code>npm install</code> automatically when any of these optional modules are needed but not currently available. </p>
|
||
<h2 id="design-understanding-the-different-modes-lan-wan-and-hybrid">🎬 Understanding the different modes: LAN, WAN and Hybrid</h2>
|
||
<div class="video-wrapper">
|
||
<iframe width="320" height="180" src="https://www.youtube.com/embed/gx5Fh3pQOns" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
<h2 id="design-code-files-and-folders">📁 Code files and folders</h2>
|
||
<p>Someone would think the server is rather simple when taking a look at the MeshCentral server code files. At a high level, the entire server has 3 folders, 3 text files and a manageable number of .js files that are fairly self-descriptive. Here is a list of the source files and folders. </p>
|
||
<h3 id="design-folders">Folders</h3>
|
||
<p><code>agents</code>: Compiled agents, install scripts, tools and agent JavaScript.</p>
|
||
<p><code>public</code>: Static web elements such as images, CSS, HTML and more.</p>
|
||
<p><code>views</code>: Main web application, login screen and messenger app.</p>
|
||
<h3 id="design-configuration-text-files">Configuration & text files</h3>
|
||
<p><code>package.json</code>: Description of the MeshCentral package on NPM.</p>
|
||
<p><code>sample-config.json</code>: A sample “config.json” file to get started.</p>
|
||
<p><code>readme.txt</code>: Readme file published with the MeshCentral package.</p>
|
||
<h3 id="design-code-files">Code files</h3>
|
||
<div class="highlight"><pre><span></span><code><span class="w"> </span>amtevents.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>decode<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>WSMAN<span class="w"> </span>events.
|
||
<span class="w"> </span>amtmanager.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>handle<span class="w"> </span>Intel<span class="w"> </span>AMT/CIRA<span class="w"> </span>things.
|
||
<span class="w"> </span>amtprovisioningserver.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>Provision<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>on<span class="w"> </span>a<span class="w"> </span>Local<span class="w"> </span>Network.
|
||
<span class="w"> </span>amtscanner.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>scan<span class="w"> </span>a<span class="w"> </span><span class="nb">local</span><span class="w"> </span>network<span class="w"> </span><span class="k">for</span><span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>machines.<span class="w"> </span>
|
||
<span class="w"> </span>amtscript.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>run<span class="w"> </span>Intel<span class="w"> </span>AMT<span class="w"> </span>scripts<span class="w"> </span>from<span class="w"> </span>MeshCommander.<span class="w"> </span>
|
||
<span class="w"> </span>certoperations.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>generate<span class="w"> </span>and<span class="w"> </span>perform<span class="w"> </span>certificate<span class="w"> </span>operations.<span class="w"> </span>
|
||
<span class="w"> </span>common.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Various<span class="w"> </span>commonly<span class="w"> </span>used<span class="w"> </span>methods.
|
||
<span class="w"> </span>crowdsec.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>handle<span class="w"> </span>all<span class="w"> </span>crowdsec<span class="w"> </span>security<span class="w"> </span>features<span class="w"> </span>
|
||
<span class="w"> </span>db.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>access<span class="w"> </span>the<span class="w"> </span>MongoDB<span class="w"> </span>or<span class="w"> </span>NeDB<span class="w"> </span>database.<span class="w"> </span>
|
||
<span class="w"> </span>exeHandler.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>modify<span class="w"> </span>windows<span class="w"> </span>executables.
|
||
<span class="w"> </span>firebase.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>handle<span class="w"> </span>Google<span class="w"> </span>Firebase<span class="w"> </span>things.
|
||
<span class="w"> </span>interceptor.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>insert<span class="w"> </span>credentials<span class="w"> </span><span class="k">in</span><span class="w"> </span>an<span class="w"> </span>HTTP<span class="w"> </span>stream.<span class="w"> </span>
|
||
<span class="w"> </span>letsencrypt.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>obtain<span class="w"> </span>and<span class="w"> </span>use<span class="w"> </span>a<span class="w"> </span>Let’s<span class="w"> </span>Encrypt<span class="w"> </span>certificate.
|
||
<span class="w"> </span>mcrec.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Standalone<span class="w"> </span>Session<span class="w"> </span>Recording<span class="w"> </span>Indexer.
|
||
<span class="w"> </span>meshaccelerator.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>offload<span class="w"> </span>RSA<span class="w"> </span>sign<span class="w"> </span>to<span class="w"> </span>other<span class="w"> </span>CPU<span class="w"> </span>cores.<span class="w"> </span>
|
||
<span class="w"> </span>meshagent.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>communicate<span class="w"> </span>to<span class="w"> </span>agents.
|
||
<span class="w"> </span>meshbot.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Sample<span class="w"> </span>bot<span class="w"> </span>to<span class="w"> </span>connect<span class="w"> </span>to<span class="w"> </span>meshcentral<span class="w"> </span>and<span class="w"> </span>preform<span class="w"> </span>various<span class="w"> </span>tasks<span class="w"> </span>
|
||
<span class="w"> </span>meshcentral.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>The<span class="w"> </span>is<span class="w"> </span>the<span class="w"> </span>main<span class="w"> </span>module,<span class="w"> </span>gets<span class="w"> </span>the<span class="w"> </span>server<span class="w"> </span>started.
|
||
<span class="w"> </span>meshctrl.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>MeshCtrl<span class="w"> </span>performs<span class="w"> </span><span class="nb">command</span><span class="w"> </span>line<span class="w"> </span>actions<span class="w"> </span>on<span class="w"> </span>a<span class="w"> </span>MeshCentral<span class="w"> </span>server.
|
||
<span class="w"> </span>meshcore.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Main<span class="w"> </span>Agent<span class="w"> </span>Code<span class="w"> </span>that<span class="w"> </span>runs<span class="w"> </span>on<span class="w"> </span>your<span class="w"> </span>remote<span class="w"> </span>devices.
|
||
<span class="w"> </span>meshdesktopmultiplex.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>handle<span class="w"> </span>remote<span class="w"> </span>desktop<span class="w"> </span>multiplexing.
|
||
<span class="w"> </span>meshdevicefile.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>handle<span class="w"> </span>file<span class="w"> </span>download<span class="w"> </span>requests.
|
||
<span class="w"> </span>meshipkvm.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>handle<span class="w"> </span>IP<span class="w"> </span>KVM<span class="w"> </span>integration
|
||
<span class="w"> </span>meshmail.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>send<span class="w"> </span>SMTP<span class="w"> </span>mails.
|
||
<span class="w"> </span>meshmessaging.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>handle<span class="w"> </span>all<span class="w"> </span>users<span class="w"> </span>messaging<span class="w"> </span>methods<span class="w"> </span>like<span class="w"> </span>2FA.
|
||
<span class="w"> </span>meshrelay.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>relay<span class="w"> </span>agent<span class="w"> </span>and<span class="w"> </span>browser<span class="w"> </span>web<span class="w"> </span>socket<span class="w"> </span>connections.<span class="w"> </span>
|
||
<span class="w"> </span>meshscanner.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>MeshCentral<span class="w"> </span>server<span class="w"> </span>discovery<span class="w"> </span>when<span class="w"> </span><span class="k">in</span><span class="w"> </span>LAN<span class="w"> </span>mode.
|
||
<span class="w"> </span>meshsms.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>handle<span class="w"> </span>all<span class="w"> </span>users<span class="w"> </span>sms<span class="w"> </span>methods.
|
||
<span class="w"> </span>meshuser.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>communicate<span class="w"> </span>with<span class="w"> </span>browsers.<span class="w"> </span>
|
||
<span class="w"> </span>mpsserver.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>communicate<span class="w"> </span>to<span class="w"> </span>Intel®<span class="w"> </span>AMT<span class="w"> </span>CIRA.
|
||
<span class="w"> </span>mqttbroker.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>create/handle<span class="w"> </span>an<span class="w"> </span>MQTT<span class="w"> </span>broker<span class="w"> </span><span class="o">(</span>beta<span class="o">)</span><span class="w"> </span>
|
||
<span class="w"> </span>multiserver.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span><span class="k">for</span><span class="w"> </span>server-to-server<span class="w"> </span>communication.<span class="w"> </span>
|
||
<span class="w"> </span>pass.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Performs<span class="w"> </span>password<span class="w"> </span><span class="nb">hash</span><span class="w"> </span>+<span class="w"> </span>salt.<span class="w"> </span>
|
||
<span class="w"> </span>redirserver.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>handle<span class="w"> </span>HTTP<span class="w"> </span>traffic.<span class="w"> </span>
|
||
<span class="w"> </span>swarmserver.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span>to<span class="w"> </span>upgrade<span class="w"> </span>legacy<span class="w"> </span>MeshCentralv1<span class="w"> </span>agents.<span class="w"> </span>
|
||
<span class="w"> </span>webauthn.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Handles<span class="w"> </span>all<span class="w"> </span>WebAuthN<span class="w"> </span>things.
|
||
<span class="w"> </span>webrelayserver.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Used<span class="w"> </span><span class="k">for</span><span class="w"> </span>all<span class="w"> </span>HTTP/HTTPS<span class="w"> </span>web<span class="w"> </span>relaying<span class="w"> </span>from<span class="w"> </span>agents.<span class="w"> </span>
|
||
<span class="w"> </span>webserver.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Handles<span class="w"> </span>HTTPS<span class="w"> </span>traffic.<span class="w"> </span>
|
||
<span class="w"> </span>winservice.js<span class="w"> </span><span class="p">|</span><span class="w"> </span>Server<span class="w"> </span>background<span class="w"> </span>install<span class="w"> </span>on<span class="w"> </span>Windows.
|
||
</code></pre></div>
|
||
<p>At a high level, the MeshCentral.js file will get the server started.</p>
|
||
<p>By default, it will start :</p>
|
||
<ul>
|
||
<li><code>webserver.js</code> on port <code>443</code>,</li>
|
||
<li><code>redirectserver.js</code> on port <code>80</code> and </li>
|
||
<li><code>mpssrver.js</code> on port <code>4433</code>.</li>
|
||
</ul>
|
||
<p>The <code>webserver.js</code> file will create a <code>meshuser.js</code> or <code>meshagent.js</code> instance each time a user or agent connects. The other files support various usages, but this is the basic working on the server. </p>
|
||
<h3 id="design-server-database">Server database</h3>
|
||
<p>One of the big design decision on the server is its database. We want something that scales and so, opted to deal with the good and the bad of a NoSQL database, MongoDB. On the other hand, we want the server to be really simple to install for people who want to try it out or want to manage 100 computers or less. We don’t want the added learning curve of MongoDB for people that don’t really need it. It turned out, we can have both. NeDB is a NPM package that provides a simple MongoDB-like API while being completely implemented in NodeJS. For most people, this is plenty good to get started. </p>
|
||
<p>By default, MeshCentral will just create and use a NeDB database, but can be configured to use MongoDB. The internal code path for both databases are almost exactly identical so the “db.js” file handles both, almost the same way and the exact database in use is completely abstracted from the rest of the server code. </p>
|
||
<h2 id="design-certificates">🔐 Certificates</h2>
|
||
<p>MeshCentral makes use of many certificates to accomplish many security tasks. When first running the server or an agent, both of these actors will generate certificates. The agent will generate one or two certificates on the first run and the server will generate four certificates. </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-36-01.jpg" /></p>
|
||
<p>In this section we review what certificates are created, what are their uses and how they are stored. Most administrators using MeshCentral will not need a deep understanding of this section to run the server, however, a basic understanding of this section can help understand how to best protect the server’s critical security assets. </p>
|
||
<h3 id="design-server-certificates">Server Certificates</h3>
|
||
<p>As indicated above, the MeshCentral server creates four certificates when it first runs. It uses ForgeJS to perform certificate creation and all four certificates below are saved in the <code>meshcentral-data</code> folder. The four certificates are: </p>
|
||
<h4 id="design-server-root">Server root</h4>
|
||
<p><code>root-cert-public.crt</code></p>
|
||
<p>This is a self-signed root certificate that is used only to issue the 3 next certificates. This certificate can be useful when it’s installed as a root of trust in some situations. For example, when Intel AMT connects to the MPS server on port <code>4433</code>, it will correctly connect only if this root certificate is loaded into Intel AMT as a trusted certificate. Browser can also be setup to trust this root certificate in order to create a trusted connection between a browser and the servers HTTPS port. This certificate is RSA3072 unless the option <code>--fastcert</code> is used, in that case a RSA2048 certificate is generated. </p>
|
||
<h4 id="design-mps-certificate">MPS certificate</h4>
|
||
<p><code>mpsserver-cert-public.crt</code></p>
|
||
<p>This is a TLS certificate signed by the root above used as a TLS server certificate on the MPS port 4433. Intel AMT computers will connect to this port and verify the certificate time, common name and that it’s signed by the root above. This certificate is not typically changed, even when the server is running in production. This certificate is always generated as RSA2048 because older Intel AMT firmware will not accept certificates with larger keys. </p>
|
||
<h4 id="design-web-certificate">Web certificate</h4>
|
||
<p><code>webserver-cert-public.crt</code></p>
|
||
<p>This is the default certificate used to secure the HTTPS port <code>443</code>. It is signed by the root above and is the certificate users will first see then connecting the browser to the server. Often, users will need to ignore the browser security warning. This certificate is RSA3072 unless the option <code>--fastcert</code> is used, in that case a RSA2048 certificate is generated. In production environments, this certificate is replaced with a real certificate. </p>
|
||
<p>There are many ways to change this certificate for a more appropriate certificate in production environments : </p>
|
||
<ul>
|
||
<li>
|
||
<p>You can replace the <code>webserver-cert-\*</code> files in the <code>meshcentral-data</code> folder.</p>
|
||
</li>
|
||
<li>
|
||
<p>You can use Let’s Encrypt which will override this certificate automatically.</p>
|
||
</li>
|
||
<li>
|
||
<p>You can use a reverse-proxy in front of the server with <code>--tlsoffload</code>. </p>
|
||
</li>
|
||
</ul>
|
||
<h4 id="design-agent-certificate">Agent certificate</h4>
|
||
<p><code>agentserver-cert-public.crt</code></p>
|
||
<p>This certificate is used to authenticate the server to agents. It’s signed by the root above and when installing an agent, the hash of this certificate is given to the agent so that it can connect back to the server securely. This certificate is RSA3072 unless the option <code>--fastcert</code> is used, in that case a RSA2048 certificate is generated. </p>
|
||
<p>The <code>meshcentral-data</code> folder contains critical server information including private keys therefore, it’s important that it be well protected. It’s important to backup the <code>meshcentral-data</code> folder and keep the backup in a secure place. If, for example the “agent certificate” on the server is lost, there is no hope for agents ever be able to connect back to this server. All agents will need to be re-installed with a new trusted certificate. </p>
|
||
<p>If someone re-installs a server, placing the <code>meshcentral-data</code> folder back with these certificates should allow the server to resume normal operations and accept connections for Intel AMT and agents as before. </p>
|
||
<h3 id="design-agent-certificates">Agent Certificates</h3>
|
||
<p>The mesh agent generates one or two RSA certificates when it first starts. On smaller IoT devices such as a Raspberry Pi, this can take a little while to do and the CPU will spike to 100% during this time. This is normal and only occurs the first time the agent runs. </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-41-26.jpg" /></p>
|
||
<p>The certificates are generated a little differently depending on the platform. On Windows, the Mesh Agent will use Microsoft cryptographic providers to harder the agent root cert. If available, the agent will use the platform TPM to harden the certificate. On other platforms, only one certificate is generated and used for both agent authentication to the server and WebRTC session authentication. </p>
|
||
<h4 id="design-agent-root-certificate">Agent root certificate</h4>
|
||
<p>This certificate is the root trust of the agent. The SHA384 hash of this certificates public key is the agent’s identifier on the server. When a agent connects to the server using web socket, it performs a secondary authentication check using this certificate. The server will compute the agent’s identifier after the agent sent a signed proof to the server. This certificate is also used to sign the secondary certificate below when it’s needed. </p>
|
||
<h4 id="design-secondary-certificate">Secondary certificate</h4>
|
||
<p>This is a certificate signed by the agent root above. It’s currently only used by WebRTC to perform dTLS authentication to a remote browser. This certificate does not need to be signed by a trusted CA for WebRTC purposes since the hash of the certificate will be sent to the browser using a trusted path. If the agent root certificate is not hardened using platform cryptography, the secondary certificate is not created and the agent root cert is used for all purposes. </p>
|
||
<p>A possible attack would occur if someone were to be able to access the agent root certificate. They could impersonate the agent to the server. Agents don’t have any rights to perform management operations on the server or other agents, but by impersonating a agent, a rogue agent would pretend to be an office computer to which administrator would login with their username & password, especially when the root is not hardened. Some care should be taken to protect the <code>meshagent.db</code> file and to not give important information to untrusted agents. </p>
|
||
<h2 id="design-tls-security">🔒 TLS Security</h2>
|
||
<p>MeshCentral makes heavy use of Transport Layer Security (TLS) and datagram-TLS (dTLS) to authenticate and encrypt network traffic between the browser, server and agent. Configuring TLS settings correctly is essential to making sure communications are secure and to minimize attacks on open ports. </p>
|
||
<p>Probably the most important TLS configuration is for the MeshCentral server ports <code>443</code> and <code>4433</code>. These two ports are exposed to the Internet and so, should be setup as securely as possible. </p>
|
||
<h3 id="design-meshcentral-https-port-443">MeshCentral HTTPS port 443</h3>
|
||
<p>The HTTPS port on the MeshCentral server will only support TLS 1.2 and above, and makes use of only 6 cypher suites: </p>
|
||
<div class="highlight"><pre><span></span><code>TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384 (0xc030)
|
||
TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA384 (0xc028)
|
||
TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA (0xc014)
|
||
TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256 (0xc02f)
|
||
TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA256 (0xc027)
|
||
TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA (0xc013)
|
||
</code></pre></div>
|
||
<p>Note that these cipher suites are all perfect forward secrecy (PFS) suites and are considered cryptographically secure as of the writing of this document. When the server is deployed on the Internet,<a href="https://ssllabs.com/"> https://ssllabs.com </a>gives the server an A rating with no known vulnerabilities and no weak ciphers detected. </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-44-41.jpg" /></p>
|
||
<p>SSL Labs confirms that all major browsers should be able to connect correctly to this server. </p>
|
||
<h3 id="design-meshcentral-mps-port-4433">MeshCentral MPS port 4433</h3>
|
||
<p>The Manageability Presence Server (MPS) port <code>4433</code> is used for incoming Intel AMT CIRA connections. By default it uses a TLS certificate that is signed by a self-signed root certificates. This port is not intended to be connected to by typical browsers, only Intel AMT should connect to this port. Note that the TLS certificate generated by MeshCentral for port <code>4433</code> is RSA 2048bits, this is because older Intel AMT firmware don’t support RSA 3072. Because the port is not secured using a trusted certificate, SSL Labs will not rate the security of this server. </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-47-26.jpg" /></p>
|
||
<p>This is fully expected. Note that SSL Labs will not test servers that are not on port 443. To perform a test like this MeshCentral must be set temporarily with the MPS port set to 443 and the normal HTTPS port set to a different value. </p>
|
||
<p>Because older Intel AMT computers that only support TLS 1.0 are common, the server supports TLS v1.0, v1.1 and v1.2 with the following 12 cipher suites: </p>
|
||
<div class="highlight"><pre><span></span><code>TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384 (0xc030)
|
||
TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA384 (0xc028)
|
||
TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA (0xc014)
|
||
TLS\_RSA\_WITH\_AES\_256\_GCM\_SHA384 (0x9d)
|
||
TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA256 (0x3d)
|
||
TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA (0x35)
|
||
TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256 (0xc02f)
|
||
TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA256 (0xc027)
|
||
TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA (0xc013)
|
||
TLS\_RSA\_WITH\_AES\_128\_GCM\_SHA256 (0x9c)
|
||
TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA256 (0x3c)
|
||
TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA (0x2f)
|
||
</code></pre></div>
|
||
<p>The suites starting with <code>TLS\_RSA\_</code> don’t have perfect forward secrecy (PFS) and so, are considered weak by SSL Labs. However, these are generally the suites that are supported by Intel AMT. </p>
|
||
<h2 id="design-agent-to-server-handshake">🛰️ Agent to server handshake</h2>
|
||
<p>One interesting aspect of MeshCentral’s design is how the agent connects to the server. We wanted a way for the agent to connect to the server that would be similar to how browsers connect to web servers. This allows for a large number of agents to connect just like if a large number of browsers where connecting. All of the infrastructure that helps web server’s scale would be put to use in the same way for agent connections. For example: TLS offload hardware, load balancers, reverse-proxies, web server scaling, etc. could all be put to use. It also makes the server easier to setup because only one port (HTTPS 443) is needed for both users and agents. </p>
|
||
<p>One big difference between the agent connecting and a typical browser is how the server is authenticated. Browsers have a set of known trusted root certificates. The server’s web certificate is checked for validity including the name, time trusted CA and more. The agent does not have this. Instead, it just has a hash to a private server certificate. </p>
|
||
<p>The public facing web certificate of the server can change frequently. For example, Let’s Encrypt certificates are valid 90 days. Agents need to be able to validate a specific server for a long time and don’t really need to trust anything else except one specific server. We also don’t want to tie the agents to a specific domain name as we could change that in the future or want to support servers with dynamic IP addresses and no fixed DNS names. </p>
|
||
<p>To handle all this, the agent performs a TLS connection to the server and will first see the web certificate of the server. It will then exchange a set of web socket binary messages to the server to perform a secondary authentication with the server. </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-54-44.jpg" /></p>
|
||
<p>The secondary check allows the agent to confirm that this server does own the private key of the private certificate expected by the agent. The agent caches the hash of the “outer” web certificate. When re-connecting, if the agent sees the same outer web certificate, it will skip the secondary check. For obvious security raisons, it’s important that the agent not accept any management messages until the secondary check is completed or skipped. </p>
|
||
<p>To prevent man-in-the-middle attacks, the secondary check also “pins” the outer web certificate. That is, the server both confirms it’s the right server and indicates to the agent the hash of the outer certificate that it must have seen during the TLS connection. The agent must check this hash to make sure there is no attacker in the middle. </p>
|
||
<p>The agent connection design allows for reverse-proxies and TLS offload hardware. The agent will first connect a TLS session to the offload hardware. Clear traffic flows between the offload hardware and the server which will perform the secondary check if needed. </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-55-28.jpg" /></p>
|
||
<p>To makes all this work, the MeshCentral server must be able to fetch the hash of the outer web certificate from the reverse proxy. In this case, the server does not need the private key to the web certificate. Note that when the outer web certificate is updated, the server may have to perform many secondary checks at the same time causing a server slowdown during this time. To help with this, MeshCentral will offload the RSA signing operation to many slave processes (as many as the CPU core count on the server) to speed this up. In addition, native NodeJS RSA signing is used (not ForgeJS). </p>
|
||
<p>The details of the secondary certificate check look like the diagram below. To boost speed, the exchange is fully asynchronous and both sides send the first message as soon as the TLS connection completes. </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-56-09.jpg" /></p>
|
||
<p>Note that these messages are binary (not JSON). The agent must be able to connect to the server independently of the JavaScript that is running in DukTape. So this exchange is handled by native C code in the agent. Binary message 1 is sent immediately after the TLS connection is setup. Both sides will send binary message 2 when message 1 is received and message 3 when message 2 is received. </p>
|
||
<p>In addition, there are two extra messages of interest that can be sent by the agent right at the start. The agent may send the server message number 4 if the secondary check can be skipped and may send binary message number 5 indicating what server hash it expects to verify. Message number 5 is interesting because a server may have many “identities” at the same time, and so, the server will use message number 5 in order to use the right Agent Server certificate. </p>
|
||
<p>In order to be as secure as possible, all hashes use SHA384 and certificates are RSA3072 and nonces are generated on both sides using a cryptographic random source.</p>
|
||
<p>The server and agent signatures are computed like this : </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-56-46.jpg" /></p>
|
||
<p>While the server will often skip its RSA signature operation due to the agents caching the outer web certificate, the server must perform an RSA verify to each agent connection. This can’t be skipped but is needed to authenticate the agent. </p>
|
||
<p>Once connected, the trust relationship between the server and the agent is one-way. That is, the server has management rights on the agent, but the agent does not have any right on the server. This is important since the agent does not, by default, have any credentials to the server. Any agent can connect to the server and claim to be part of a device group. </p>
|
||
<h2 id="design-browser-to-agent-relay-and-webrtc">🌍 Browser to agent relay and WebRTC</h2>
|
||
<p>Browsers and agents often need to communicate to each other. Data sessions are used for desktop, terminal, file transfers, etc. and must be setup securely. </p>
|
||
<p>To setup a session between a browser and the agent, the server will send a URL to both sides to connect to. The URL is generated by the server and includes a unique connection token. It is sent to both the browser and agent using the web socket control channel and a JSON message. Both sides perform a websocket connection to the target URL and the server will “pipe” both sessions together to act as a passive relay. For security, the agent will only accept connections to the URL given by the server if the server has the same outer web certificate as its control connection. Also note that in this mode, the session is not end-to-end encrypted. The server is performing a TLS decrypt and re-encrypt and the traffic cost is high as each byte of data has to be received and sent again. </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-58-06.jpg" /></p>
|
||
<p>The relay server is just websocket server that will wait for connections with session tokens. When two connection with the same connection token arrive, the server makes sure that at least one of the two connections is an authenticated user, it then sends the character <code>c</code> on both sides to inform both parties that the relay is starting and then pipes both sessions together. Once the session is started, the browser and agent are free to send messages to each other. Note that when the server sends the relay URL to the agent, it also sends to the agent the user’s permissions flags. This may be used by the agent to limit what the user can do on this session. </p>
|
||
<p>With this design, the flow control between the browser and agent is simple, each session gets its own end-to-end connection and the server will apply appropriate TCP back pressure on both sides as needed. </p>
|
||
<p>A unique feature of MeshCentral is its use of WebRTC. WebRTC was introduced in major browsers as a way to allow browsers to directly communicate to each other and perform audio/video streaming. The mesh agent has a WebRTC data-only stack that is custom built for this project in C code. It’s compatible with Chrome and Firefox implementations and once a session is set up, allows data to flow directly from the browser to the agent, bypassing the server. </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-58-29.jpg" /></p>
|
||
<p>The use of WebRTC allows MeshCentral to scale better, to offer a faster user experience and lower hosting costs all at the same time. However, WebRTC is not easy, especially when you must maintain the C code for it and have to keep up with browser implementations, but the benefits are clear. </p>
|
||
<p>To setup WebRTC, browsers typically use STUN and TURN servers to get traffic thru any network obstacles (routers, proxies, firewalls). This infrastructure can be complex to setup especially if an administrator is not familiar with WebRTC concepts. To make things easy, MeshCentral opted to always start by using a websocket relay thru the server to get things started. While a session is active, the browser and agent will attempt to automatically switch the session traffic to WebRTC when possible. This way, the session always works and gets more efficient when network conditions allow. </p>
|
||
<p>To perform the switch-over, both browser and agent will exchange WebRTC control messages over the newly established web socket relay session. </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-58-56.jpg" /></p>
|
||
<p>In order to differentiate session traffic from WebRTC control traffic, the browser and agent agree to send WebRTC setup traffic using web socket text fragments. All other session traffic is sent using binary fragments. The agent has a special API allowing a session to be piped for a single fragment type. So we can perform a remote desktop session to the agent while trying to setup WebRTC at the same time. </p>
|
||
<p>The browser will kick off the WebRTC setup sending the initial WebRTC offer with the agent responding with a WebRTC answer. If the WebRTC session gets setup, both sides need to negotiate a clear transition from the web socket session to the WebRTC session. To do this, both sides send a start switch control fragment (this is a text fragment), the other side will respond with an ACK when the web socket session is flushed out and it’s safe to switch. </p>
|
||
<p>On the agent side, the new WebRTC session inherits the user access rights of the web socket. Currently, the web socket channel is still maintained open. While it’s not strickly needed, the web socket session terminates more cleanly than WebRTC and so, oddly its closure is used to signal the end of the WebRTC session. </p>
|
||
<h2 id="design-messenger">💬 Messenger</h2>
|
||
<p>MeshCentral includes its own messaging web application it can be used to chat, transfer files and optionally used for audio and video chat. It’s used to support two different usages :</p>
|
||
<ul>
|
||
<li>
|
||
<p><em>User-to-user and</em></p>
|
||
</li>
|
||
<li>
|
||
<p><em>user-to-computer communication.</em> </p>
|
||
</li>
|
||
</ul>
|
||
<p>In the first usage, two users that are connected to the same MeshCentral server at the same time can chat. If you are a MeshCentral administrator, you can see the list of currently logged in users and hit the chat button to launch a chat invitation. If accepted, the Messenger is open on both sides and the session starts. Alternatively, while managing a remote computer, an administrator can hit the chat button to cause the remote computer to open a web browser to the chat application. </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-13-59-54.jpg" /></p>
|
||
<p>The chat app is standalone web application that is served by the MeshCentral server using a connection token and title in the URL. Once loaded in its own web frame, the messenger web application will get the connection token and title from the URL and proceed to connect to the URL using web socket. The same web socket relay that is used for browser-to-agent connections is also used in this case for browser-to-browser connections. The server relay acts the same and pipes both sessions together after sending the character <code>c</code> to both sides. At this point, the messenger application will show the remote user as connected and chat and file transfers can start. File transfers are just a set of binary messages sent over the web socket session with lots of JSON control messages. </p>
|
||
<p>Once the web socket session is setup, the messenger application will then attempt to perform a switch over to WebRTC. Both web application start by selecting a random number (not cryptographic) and the highest number will initiate the WebRTC offer. The other party will answer and both sides will trade interface candidates as they are discovered. If successful, the web socket session are flushed and the traffic is switched over to WebRTC. Because the switchover is done cleanly, it can occur while in the middle of a file transfer without the file being corrupted. </p>
|
||
<p><img alt="" src="../design/images/2022-05-15-14-00-21.jpg" /></p>
|
||
<p>Finally, the web application will determine if the local computer is attached to a microphone and if it has a camera. If so, these options are offered in the chat window and audio/video chat is available for use. The chat app allows for one way setup of audio & video sessions. This is typically what is needed in support scenarios where the audio/video session is one-way. </p>
|
||
<p>The messenger web application will setup a separate WebRTC connection for audio/video in each direction but the code is present to augment the WebRTC control channel with audio/video which is a bit more efficient but more testing is needed before defaulting to this mode. </p>
|
||
<h2 id="design-additional-resources">💡 Additional Resources</h2>
|
||
<p>In addition to this document, there are a growing set of MeshCentral resources at :</p>
|
||
<ul>
|
||
<li>
|
||
<p><strong><a href="https://www.meshcommander.com/meshcentral2">https://www.meshcommander.com/meshcentral2.</a></strong> :</p>
|
||
<p>This includes an Installer’s documents, a User’s Guide and plenty of YouTube tutorial videos.</p>
|
||
</li>
|
||
</ul>
|
||
<p>For developers, it’s best to start on the MeshCentral GitHub repository at :</p>
|
||
<ul>
|
||
<li><strong><a href="https://github.com/Ylianst/MeshCentral"> https://github.com/Ylianst/MeshCentral</a></strong></li>
|
||
</ul>
|
||
<p>If any issues are found, it’s best to create a new issue in GitHub or mail <a href="mailto:ylianst@gmail.com">ylianst@gmail.com</a></p>
|
||
<h2 id="design-conclusion">🏁 Conclusion</h2>
|
||
<p>MeshCentral is a free, open source and powerful remote management solution that is cross- platform. In this document, we have covered the goals, overview, design and some details of the software. It’s hoped that this document will encourage developers to take a look at MeshCentral for more usages and review its security in detail. MeshCentral’s use of modern web technologies make it a unique and amazing solution for remote management of computers. As with any good software, MeshCentral will continue to be updated and evolve. </p>
|
||
<h2 id="design-license">License</h2>
|
||
<p>MeshCentral and this document are both opens source and licensed using Apache 2.0, the full license can be found at <a href="https://www.apache.org/licenses/LICENSE-2.0">https://www.apache.org/licenses/LICENSE-2.0</a></p>
|
||
<h2 id="design-pdf-and-odt-handouts">PDF and ODT handout(s).</h2>
|
||
<p><a href="https://meshcentral.com/docs/MeshCentral2UserGuide.pdf">MeshCentral Guide</a></p>
|
||
<p>MeshCmd Guide <a href="https://meshcentral.com/docs/MeshCmdUserGuide.pdf">as .pdf</a> <a href="../documents/MeshCentral%20Design%20%26%20Architecture%20v0.0.4.odt">as .odt</a></p></section>
|
||
<section class='print-page md-section' id='section-7' heading-number='7'>
|
||
<h1>Other<a class='headerlink' href='#section-7' title='Permanent link'></a>
|
||
</h1>
|
||
<section class="print-page" id="other-adfs_sso_guide" heading-number="7.1"><h1 id="other-adfs_sso_guide-adfs-sso-guide">ADFS SSO Guide</h1>
|
||
<h2 id="other-adfs_sso_guide-assumptions">📋 Assumptions</h2>
|
||
<p>The following guide was built under the assumptions that :</p>
|
||
<ol>
|
||
<li>
|
||
<p><em>ADFS 4.0 running on Server 2016 using Active Directory</em></p>
|
||
</li>
|
||
<li>
|
||
<p><em>Main ADFS setup already completed / working. SSL certs installed and port forwarded as expected.</em></p>
|
||
</li>
|
||
</ol>
|
||
<p>The guide was built to deal specifically with adding mesh as a Relying Party. I’m far from an ADFS expert and some configurations may not be needed. Most of this was built by reading the code and taking guesses as to the needed values.</p>
|
||
<h2 id="other-adfs_sso_guide-guide">📘 Guide</h2>
|
||
<p>As with anything SSO, you need 2 pieces – the IDP setup (in this case ADFS) and the SP setup (in this case Mesh).</p>
|
||
<h3 id="other-adfs_sso_guide-mesh-setup">Mesh Setup</h3>
|
||
<p>Add the following to your mesh config file in the domains part :</p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-24-54.png" /></p>
|
||
<ul>
|
||
<li>
|
||
<p><code>Callback URL</code> : </p>
|
||
<blockquote>
|
||
<p>Should be the FQDN for your Mesh Server, ending with /auth-saml-callback</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><code>Entity ID</code> :</p>
|
||
<blockquote>
|
||
<p>This is how ADFS IDs which party the request goes to. You can set this to whatever you want, but you will need this value later on when working in ADFS.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><code>IDP URL</code>:</p>
|
||
<blockquote>
|
||
<p>This is the URL to ADFS. Ends with /adfs/ls unless you did something very weird in ADFS.</p>
|
||
</blockquote>
|
||
</li>
|
||
<li>
|
||
<p><code>Cert</code>:</p>
|
||
<blockquote>
|
||
<p>You will need to export the token signing cert from ADFS, then convert it to PEM format. This cert can be found in <code>ADFS -> Service -> Certificates</code>. You can use this openssl command to convert it from CRT to PEM format :
|
||
<div class="highlight"><pre><span></span><code>openssl<span class="w"> </span>x509<span class="w"> </span>-in<span class="w"> </span>mycert.crt<span class="w"> </span>-out<span class="w"> </span>mycert.pem<span class="w"> </span>-outform<span class="w"> </span>PEM
|
||
</code></pre></div></p>
|
||
</blockquote>
|
||
</li>
|
||
</ul>
|
||
<p>Save the config and restart the mesh server. </p>
|
||
<h3 id="other-adfs_sso_guide-windows-server-configuration">Windows Server Configuration</h3>
|
||
<p>ADFS setup (in pictures) :</p>
|
||
<p>Relying Party Trust -> New Relying Party Trust</p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-25-48.png" /></p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-26-01.png" /></p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-26-47.png" /></p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-26-56.png" /></p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-27-03.png" /></p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-27-09.png" /></p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-27-16.png" /></p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-27-22.png" /></p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-27-28.png" /></p>
|
||
<p>Edit the new “Relying Party Trust” Properties:</p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-27-41.png" /></p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-27-51.png" /></p>
|
||
<p>Then it’s time to add Claims…</p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-28-09.png" /></p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-28-15.png" /></p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-28-21.png" /></p>
|
||
<p>For the outgoing claim type, where it says firstname, lastname, and email, manually type it in as shown. All other fields should be selected from the dropdown.</p>
|
||
<p>Add another rule:</p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-28-41.png" /></p>
|
||
<p><img alt="" src="../other/images/adfs_sso2022-05-16-23-28-48.png" /></p>
|
||
<p>For all fields, select from the dropdowns</p></section><section class="print-page" id="other-meshcentral_satellite" heading-number="7.2"><h1 id="other-meshcentral_satellite-meshcentral-satellite">MeshCentral Satellite</h1>
|
||
<h3 id="other-meshcentral_satellite-coming-soon"><strong><em>🚀 Coming Soon!</em></strong></h3>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-00-58-46.png" /></p>
|
||
<h2 id="other-meshcentral_satellite-abstract">🧾 Abstract</h2>
|
||
<p>MeshCentral Satellite is a Windows application that acts as a relay between a Windows Active Directory Domain and a MeshCentral Server. Once setup, the MeshCentral server can request that MeshCentral Satellite create an 802.1x computer profile for Intel AMT in the domain, or ask a certificate authority to issue or revoke a certificate.</p>
|
||
<h2 id="other-meshcentral_satellite-introduction">📘 Introduction</h2>
|
||
<p>A MeshCentral server can run in the cloud on a Linux server, but it may occasionally need to interact with a domain controller to perform some operations. MeshCentral Satellite is built to perform this function. MeshCentral Satellite is a Windows application built in C# and must run on a computer that is part of a domain and must run with sufficient rights to perform LDAP object addition and removal. If a certificate authority (CA) needs to be used, MeshCentral Satellite needs to have sufficient rights to ask the CA issue or revoke certificates.</p>
|
||
<p>MeshCentral Satellite should run on a computer that is always on. Once running, it will attempt to connect to the MeshCentral server and keep the connection open awaiting requests.</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-00-59-21.png" /></p>
|
||
<p>Currently, MeshCentral Satellite can perform four operations on behalf of the MeshCentral server :</p>
|
||
<ul>
|
||
<li><strong>Create an Intel AMT domain computer</strong>.</li>
|
||
<li><strong>Remove an Intel AMT domain computer</strong>.</li>
|
||
<li><strong>Issue a certificate for Intel AMT</strong>.</li>
|
||
<li><strong>Revoke an Intel AMT certificate</strong>.</li>
|
||
</ul>
|
||
<p>MeshCentral Satellite can run both as a standalone application which is practical to get started and it can be setup as a background Windows Service for long term operations. To get started, we will run it as a standalone application and start working on getting it setup.</p>
|
||
<h2 id="other-meshcentral_satellite-installation-and-configuration">🧰 Installation and Configuration</h2>
|
||
<p>Start by creating an empty folder on a computer that is part of the domain you need to interact with. For example, create a <code>c:\MeshCentralSatellite</code> then copy <code>MeshCentralSatellite.exe</code> into that folder. You can find that executable in the <code>node_modules/meshcentral/agents</code> folder of your server. If it’s not present, update your server to the latest version and look again.</p>
|
||
<p>Once started you should see something this:</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-00-22.png" /></p>
|
||
<p>Go in the file menu and select “Settings…”, this is where all of the MeshCentral Satellite setting are. It includes sections to connect to your MeshCentral server. Security groups you want device to join and Certificate settings.</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-00-33.png" /></p>
|
||
<p>First, enter your MeshCentral server hostname and username and password. MeshCentral Satellite can’t use two-factor authentication (2FA) so you need to create a user account in MeshCentral for Satellite or you can create a login token in the “My Account” section of MeshCentral with an unlimited expire time and cut & paste the username and password given into MeshCentral Satellite.</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-00-45.png" /></p>
|
||
<p>If your MeshCentral server is a test server that does not have a real TLS certificate, you can opt to ignore the TLS certificate on connection but this is not secure and so, not recommended.</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-00-59.png" /></p>
|
||
<p>The <code>Device Name</code> has two options, <code>Operating System Name</code> or <code>Node Identifier</code>. If you opt for <code>Operating System Name</code>, Intel AMT devices will show as, for example, <code>iME-ComputerName</code> in the list of domain computers. If <code>node identifier</code> is used, Intel AMT devices will look like <code>iME-xxxxxxxxxxx</code> where xxx is the start of the MeshCentral node identifier for this device.</p>
|
||
<p>Using the node identifier is more secure as it can’t easily be replicate by any other device. The operating system name would be impersonated by another device causing various security issues.</p>
|
||
<p>The security groups section will list any security groups created until the <code>Computers</code> section of the domain controller. Checking one or more of these security groups will automatically going new Intel AMT devices to these groups.</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-01-13.png" /></p>
|
||
<p>Lastly, we have the certificate authority and certificate settings. If a certificate authority needs to used, enter the name of the CA which is in the format <code><computername>\<caname></code> you can then hit the check box next to the name and select the certificate template to use.</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-01-52.png" /></p>
|
||
<p>For certificate configuration, you can leave it as-is with <code>SAM Account Name</code> and the common name and all alternative names selected.</p>
|
||
<p>Once done, you can hit ok. The settings will be saved in a file called <code>config.txt</code> in plain text in the same folder as <code>MeshCentralSatellite.exe</code>. Make sure not to grant access to this file to anyone not authorized to do so as it will have the MeshCentral login username and password.</p>
|
||
<p>Once done, select <code>Local Connect</code> the <code>Files</code> menu to connect to the MeshCentral server.</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-02-04.png" /></p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-02-10.png" /></p>
|
||
<p>MeshCentral Satellite should be connected and ready to receive commands from the server.</p>
|
||
<h2 id="other-meshcentral_satellite-checking-the-connection">✅ Checking the connection</h2>
|
||
<p>In order to make sure the server correctly recognizes the MeshCentral Satellite connection, you can go to the server console and type <code>usersession</code>. The Satellite session should be marked.</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-02-39.png" /></p>
|
||
<p>Currently, you should only have a single satellite session per user. In the future, multiple sessions could be supported for redundancy.</p>
|
||
<h2 id="other-meshcentral_satellite-configuring-intel-amt-8021x">🔧 Configuring Intel® AMT 802.1x</h2>
|
||
<p>To start using MeshCentral Satellite, you can configure Intel AMT with an 802.1x profile, this is done in the domain section of the config.json.</p>
|
||
<p>Here is an example of an 802.1x EAP-TLS profile that will require that Intel AMT be issued a certificate :</p>
|
||
<div class="highlight"><pre><span></span><code><span class="w"> </span><span class="nt">"AmtManager"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"802.1x"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"AuthenticationProtocol"</span><span class="p">:</span><span class="w"> </span><span class="s2">"EAP-TLS"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"SatelliteCredentials"</span><span class="p">:</span><span class="w"> </span><span class="s2">"admin"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"WifiProfiles"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||
<span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"ssid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Network-8021x"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authentication"</span><span class="p">:</span><span class="w"> </span><span class="s2">"wpa2-802.1x"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"encryption"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ccmp-aes"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>In this following example, MSCHAPv2 is used and so, MeshCentral Satellite will need to generate a random password, save it in the active directory and send the password back to MeshCentral for Intel AMT configuration:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="w"> </span><span class="nt">"AmtManager"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"802.1x"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"AuthenticationProtocol"</span><span class="p">:</span><span class="w"> </span><span class="s2">"PEAPv0/EAP-MSCHAPv2"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"SatelliteCredentials"</span><span class="p">:</span><span class="w"> </span><span class="s2">"admin"</span>
|
||
<span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"WifiProfiles"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||
<span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"ssid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Network-8021x"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"authentication"</span><span class="p">:</span><span class="w"> </span><span class="s2">"wpa2-802.1x"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nt">"encryption"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ccmp-aes"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">]</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>The second example does not require that a certificate authority be setup, the first example does. In both cases, the WIFI profile is set to <code>wpa2-802.1x</code> and so, the 802.1x profile will be setup for both the Intel AMT wired interface and the specified WIFI profile for wireless.</p>
|
||
<p>Note that is both examples, <code>SatelliteCredentials</code> indicates the account name that MeshCentral Satellite will be connected on. In our case, we used the <code>admin</code> account that matches the account configuration we used in sections 3 and 4.</p>
|
||
<p>Make these changes to the <code>config.json</code> and restart the MeshCentral server. Once done, any device groups that are set to configure Intel AMT will generate operations for MeshCentral Satellite.</p>
|
||
<h2 id="other-meshcentral_satellite-computer-and-certificate-operations">🧾 Computer and certificate operations</h2>
|
||
<p>Once MeshCentral and MeshCentral Satellite are setup, make sure a device group has an active Intel AMT policy. In the example below, we have a device group with an Admin Control Mode (ACM) activation policy.</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-03-30.png" /></p>
|
||
<p>Computers connecting to this device group will automatically be setup with the new 802.1x and WIFI profile, but you can go in an agent console and type <code>amtconfig</code> to force the check of the Intel AMT configuration. In our case, it looks like this :</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-03-43.png" /></p>
|
||
<p>MeshCentral is adding a new WIFI profile, setting up 802.1x and issuing a new Intel AMT certificate from the domain CA. This was all done in a few seconds. On the MeshCentral Satellite side, we see this:</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-03-56.png" /></p>
|
||
<p>The MeshCentral Satellite received an 802.1x EAP-TLS request. It asked Intel AMT to generate a RSA key pair, to sign a certificate request, forwarded the request to the domain CA for signature and finally returned the final certificate to Intel AMT. The computer account in the domain was also updated and looks like this:</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-04-11.png" /></p>
|
||
<p>The new Intel AMT device was added to the domain along with the Intel AMT version and node identifier in the description. If <code>Node Identifier</code> was selected as the computer name in MeshCentral Satellite settings, the friendly name would be in the description and the node identifier would be used as the device name.</p>
|
||
<p>Finally, it’s worth taking a look at how Intel AMT was configured before and after this operation. Before setting up the 802.1x profile, Intel AMT looked like this :</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-04-22.png" /></p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-05-15.png" /></p>
|
||
<p>Note that there is no 802.1x profiles or WIFI profiles. After the new configuration, MeshCommander shows Intel AMT looking like this :</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-05-22.png" /></p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-05-28.png" /></p>
|
||
<p>There are now two new certificates in the <code>Security</code> tab. One if the root of the domain CA, the other is the certificate assigned to the Intel AMT device by the CA. You also see the WIFI 802.1x profile. In this example, the device did not have a wired network interface, but if it did, 802.1x would also be setup for the wired interface.</p>
|
||
<h2 id="other-meshcentral_satellite-running-as-a-background-service">🖥️ Running as a Background Service</h2>
|
||
<p>MeshCentral Satellite can be run as a background service. This is useful when running for lang periods on a domain server. You can use the <code>Service</code> menu in MeshCentral Satellite to install, start, stop and uninstall the Windows service. Make sure to come and run “MeshCentralSatellite.exe” from the correct location you want to install the Windows Service from.</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-05-51.png" /></p>
|
||
<p>Since MeshCentral Satellite need to have domain rights to add and remove computer objects from the active directory and to have certificate authority (CA) rights, you may want to install the service, go in the service manager and change the <code>Log On</code> account to one with the proper rights.</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-06-01.png" /></p>
|
||
<p>Once set, you can start the service from within MeshCentral Satellite. Once the service is started, there is a communication channel that will be create with the local application so you can still monitor what the service is doing.</p>
|
||
<p><img alt="" src="../other/images/sat2022-05-17-01-06-10.png" /></p>
|
||
<p>The lines starting with <code>Service:</code> are coming from the background service. At this point, you can close the local application and the service will keep running in the background.</p>
|
||
<h2 id="other-meshcentral_satellite-license">License</h2>
|
||
<p>MeshCentral, MeshCentral Satellite and this document are both opens source and licensed using Apache 2.0, the full license can be found at <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License 2.0</a>.</p></section></section></div><style>.print-site-enumerate-headings #section-1 > h1:before { content: '1 ' }
|
||
.print-site-enumerate-headings #index > h1:before { content: '1.1 ' }
|
||
|
||
.print-site-enumerate-headings #index h2:before { content: '1.1.' counter(counter-index-2) ' ' }
|
||
.print-site-enumerate-headings #index h2 { counter-increment: counter-index-2 }
|
||
|
||
.print-site-enumerate-headings #section-2 > h1:before { content: '2 ' }
|
||
.print-site-enumerate-headings #install-abstract > h1:before { content: '2.1 ' }
|
||
|
||
.print-site-enumerate-headings #install-abstract h2:before { content: '2.1.' counter(counter-install-abstract-2) ' ' }
|
||
.print-site-enumerate-headings #install-abstract h2 { counter-increment: counter-install-abstract-2 }
|
||
|
||
.print-site-enumerate-headings #install-quickstart > h1:before { content: '2.2 ' }
|
||
|
||
.print-site-enumerate-headings #install-quickstart h2:before { content: '2.2.' counter(counter-install-quickstart-2) ' ' }
|
||
.print-site-enumerate-headings #install-quickstart h2 { counter-increment: counter-install-quickstart-2 }
|
||
|
||
.print-site-enumerate-headings #section-2-3 > h1:before { content: '2.3 ' }
|
||
.print-site-enumerate-headings #install-abstract > h1:before { content: '2.3.1 ' }
|
||
|
||
.print-site-enumerate-headings #install-advanced > h1:before { content: '2.3.2 ' }
|
||
|
||
.print-site-enumerate-headings #install-container > h1:before { content: '2.3.3 ' }
|
||
|
||
.print-site-enumerate-headings #install-windows > h1:before { content: '2.3.4 ' }
|
||
|
||
.print-site-enumerate-headings #section-2-4 > h1:before { content: '2.4 ' }
|
||
.print-site-enumerate-headings #install-database-mongodb > h1:before { content: '2.4.1 ' }
|
||
|
||
.print-site-enumerate-headings #install-database-postgresql > h1:before { content: '2.4.2 ' }
|
||
|
||
.print-site-enumerate-headings #install-database-mariadb > h1:before { content: '2.4.3 ' }
|
||
|
||
.print-site-enumerate-headings #install-database-local > h1:before { content: '2.4.4 ' }
|
||
|
||
.print-site-enumerate-headings #section-2-5 > h1:before { content: '2.5 ' }
|
||
.print-site-enumerate-headings #install-security-crowdsec > h1:before { content: '2.5.1 ' }
|
||
|
||
.print-site-enumerate-headings #install-security-secure > h1:before { content: '2.5.2 ' }
|
||
|
||
.print-site-enumerate-headings #section-3 > h1:before { content: '3 ' }
|
||
.print-site-enumerate-headings #meshcentral > h1:before { content: '3.1 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral h2:before { content: '3.1.' counter(counter-meshcentral-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral h2 { counter-increment: counter-meshcentral-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-config > h1:before { content: '3.2 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-config h2:before { content: '3.2.' counter(counter-meshcentral-config-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-config h2 { counter-increment: counter-meshcentral-config-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-sslnletsencrypt > h1:before { content: '3.3 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-sslnletsencrypt h2:before { content: '3.3.' counter(counter-meshcentral-sslnletsencrypt-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-sslnletsencrypt h2 { counter-increment: counter-meshcentral-sslnletsencrypt-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-agents > h1:before { content: '3.4 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-agents h2:before { content: '3.4.' counter(counter-meshcentral-agents-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-agents h2 { counter-increment: counter-meshcentral-agents-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-assistant > h1:before { content: '3.5 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-assistant h2:before { content: '3.5.' counter(counter-meshcentral-assistant-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-assistant h2 { counter-increment: counter-meshcentral-assistant-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-codesigning > h1:before { content: '3.6 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-codesigning h2:before { content: '3.6.' counter(counter-meshcentral-codesigning-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-codesigning h2 { counter-increment: counter-meshcentral-codesigning-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-debugging > h1:before { content: '3.7 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-debugging h2:before { content: '3.7.' counter(counter-meshcentral-debugging-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-debugging h2 { counter-increment: counter-meshcentral-debugging-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-devicetabs > h1:before { content: '3.8 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-devicetabs h2:before { content: '3.8.' counter(counter-meshcentral-devicetabs-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-devicetabs h2 { counter-increment: counter-meshcentral-devicetabs-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-plugins > h1:before { content: '3.9 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-plugins h2:before { content: '3.9.' counter(counter-meshcentral-plugins-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-plugins h2 { counter-increment: counter-meshcentral-plugins-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-security > h1:before { content: '3.10 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-security h2:before { content: '3.10.' counter(counter-meshcentral-security-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-security h2 { counter-increment: counter-meshcentral-security-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-tokens > h1:before { content: '3.11 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-tokens h2:before { content: '3.11.' counter(counter-meshcentral-tokens-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-tokens h2 { counter-increment: counter-meshcentral-tokens-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-faq > h1:before { content: '3.12 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-faq h2:before { content: '3.12.' counter(counter-meshcentral-faq-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-faq h2 { counter-increment: counter-meshcentral-faq-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-tipsntricks > h1:before { content: '3.13 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-tipsntricks h2:before { content: '3.13.' counter(counter-meshcentral-tipsntricks-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-tipsntricks h2 { counter-increment: counter-meshcentral-tipsntricks-2 }
|
||
|
||
.print-site-enumerate-headings #messaging > h1:before { content: '3.14 ' }
|
||
|
||
.print-site-enumerate-headings #messaging h2:before { content: '3.14.' counter(counter-messaging-2) ' ' }
|
||
.print-site-enumerate-headings #messaging h2 { counter-increment: counter-messaging-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-customization > h1:before { content: '3.15 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-customization h2:before { content: '3.15.' counter(counter-meshcentral-customization-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-customization h2 { counter-increment: counter-meshcentral-customization-2 }
|
||
|
||
.print-site-enumerate-headings #meshcentral-openidconnectstrategy > h1:before { content: '3.16 ' }
|
||
|
||
.print-site-enumerate-headings #meshcentral-openidconnectstrategy h2:before { content: '3.16.' counter(counter-meshcentral-openidconnectstrategy-2) ' ' }
|
||
.print-site-enumerate-headings #meshcentral-openidconnectstrategy h2 { counter-increment: counter-meshcentral-openidconnectstrategy-2 }
|
||
|
||
.print-site-enumerate-headings #section-4 > h1:before { content: '4 ' }
|
||
.print-site-enumerate-headings #meshcmd > h1:before { content: '4.1 ' }
|
||
|
||
.print-site-enumerate-headings #meshcmd h2:before { content: '4.1.' counter(counter-meshcmd-2) ' ' }
|
||
.print-site-enumerate-headings #meshcmd h2 { counter-increment: counter-meshcmd-2 }
|
||
|
||
.print-site-enumerate-headings #meshctrl > h1:before { content: '4.2 ' }
|
||
|
||
.print-site-enumerate-headings #meshctrl h2:before { content: '4.2.' counter(counter-meshctrl-2) ' ' }
|
||
.print-site-enumerate-headings #meshctrl h2 { counter-increment: counter-meshctrl-2 }
|
||
|
||
.print-site-enumerate-headings #meshrouter > h1:before { content: '4.3 ' }
|
||
|
||
.print-site-enumerate-headings #meshrouter h2:before { content: '4.3.' counter(counter-meshrouter-2) ' ' }
|
||
.print-site-enumerate-headings #meshrouter h2 { counter-increment: counter-meshrouter-2 }
|
||
|
||
.print-site-enumerate-headings #intelamt > h1:before { content: '4.4 ' }
|
||
|
||
.print-site-enumerate-headings #intelamt h2:before { content: '4.4.' counter(counter-intelamt-2) ' ' }
|
||
.print-site-enumerate-headings #intelamt h2 { counter-increment: counter-intelamt-2 }
|
||
|
||
.print-site-enumerate-headings #how-to-contribute > h1:before { content: '5 ' }
|
||
|
||
.print-site-enumerate-headings #how-to-contribute h2:before { content: '5.' counter(counter-how-to-contribute-2) ' ' }
|
||
.print-site-enumerate-headings #how-to-contribute h2 { counter-reset: counter-how-to-contribute-3 ; counter-increment: counter-how-to-contribute-2 }
|
||
|
||
.print-site-enumerate-headings #how-to-contribute h3:before { content: '5.' counter(counter-how-to-contribute-2) '.' counter(counter-how-to-contribute-3) ' ' }
|
||
.print-site-enumerate-headings #how-to-contribute h3 { counter-increment: counter-how-to-contribute-3 }
|
||
|
||
.print-site-enumerate-headings #design > h1:before { content: '6 ' }
|
||
|
||
.print-site-enumerate-headings #design h2:before { content: '6.' counter(counter-design-2) ' ' }
|
||
.print-site-enumerate-headings #design h2 { counter-reset: counter-design-3 ; counter-increment: counter-design-2 }
|
||
|
||
.print-site-enumerate-headings #design h3:before { content: '6.' counter(counter-design-2) '.' counter(counter-design-3) ' ' }
|
||
.print-site-enumerate-headings #design h3 { counter-increment: counter-design-3 }
|
||
|
||
.print-site-enumerate-headings #section-7 > h1:before { content: '7 ' }
|
||
.print-site-enumerate-headings #other-adfs_sso_guide > h1:before { content: '7.1 ' }
|
||
|
||
.print-site-enumerate-headings #other-adfs_sso_guide h2:before { content: '7.1.' counter(counter-other-adfs_sso_guide-2) ' ' }
|
||
.print-site-enumerate-headings #other-adfs_sso_guide h2 { counter-increment: counter-other-adfs_sso_guide-2 }
|
||
|
||
.print-site-enumerate-headings #other-meshcentral_satellite > h1:before { content: '7.2 ' }
|
||
|
||
.print-site-enumerate-headings #other-meshcentral_satellite h2:before { content: '7.2.' counter(counter-other-meshcentral_satellite-2) ' ' }
|
||
.print-site-enumerate-headings #other-meshcentral_satellite h2 { counter-increment: counter-other-meshcentral_satellite-2 }
|
||
</style>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</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"/></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>
|
||
|
||
</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": "/MeshCentral/", "features": ["content.code.copy", "content.code.select", "navigation.tabs", "navigation.top", "navigation.sections", "navigation.instant", "search.suggest"], "search": "../assets/javascripts/workers/search.973d3a69.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.f55a23d4.min.js"></script>
|
||
|
||
<script src="../js/print-site.js"></script>
|
||
|
||
|
||
</body>
|
||
</html> |