Home

MeshCentral Documentation

About

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.

For more information, visit MeshCentral.com.

YouTube YouTube
Reddit Reddit
Telegram
Discord
BlueSky BlueSky
BlogSpot

📚 Documentation

The User's Guide 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.

The Installation Guide 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.

The Design and Architecture Guide 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.

📺 Video Tutorials

You can watch many tutorial videos on the MeshCentral YouTube Channel. Here are some essential ones to get you started :

MeshCentral - Installation
Installing MeshCentral on Windows, Linux, and macOS.

MeshCentral - Basics
Learn how to install the agent and use remote desktop, terminal, and file access features.

MeshCentral - Two Factor Authentication
Secure your MeshCentral instance with two-factor authentication.

MeshCentral - NGINX Reverse Proxy
Configure MeshCentral with an NGINX reverse proxy for better security and scalability.

MeshCentral - Android
Install and use the MeshCentral Android agent for mobile device management.

MeshCentral - Basics
Use MeshCentral Router to port map TCP connections securely.

💬 Feedback

If you encounter a problem or have a suggestion to improve the product, you may file an GitHub Issue.
If you are filing a problem report, you should include:

The version of the software you are using.

For example: 1.1.46
The Operating System and version.

For example: Debian 12
Any troubleshooting you took to resolve the issue yourself.

For example: Reinstalling MeshCentral (including OS)
Any other similar reports.

For example: other GitHub issues.
The observed output.
The expected output.

If you are having issues with the following other products, you should file a report on their respective issue pages MeshAgent MeshRouter License

This software is licensed under Apache 2.0.

Install

Installation

🧾 Abstract

These guides are specifically intended to help users install and configure MeshCentral.
Once installed, you can take a look at the MeshCentral user’s guide,
for information on how to configure MeshCentral for your specific use.
In this document, we will look at installing MeshCentral on different operating systems like:

And remember! The config.json is case insensitive in its keys.

📢 Quick-start
🧐 Advanced Information
🪟 Windows-specific

Quickstart

🚀 Quick Start Guide: Basic NPM Installation

MeshCentral is platform-agnostic, running almost anywhere thanks to being primarily written in JavaScript. This guide covers the simplest way to get started using NPM.

🛠️ Basic Setup

The only prerequisites are Node.js and npm.

1. Install Node.js

Linux: Find installation instructions for your distribution here.
Windows: Download the installer from the official site here.

🪟 Windows Users: If you prefer an automated setup, you can skip the manual installation and download the Windows MeshCentral Installer. However, this is not recommended for advanced users. Download Windows MeshCentral Installer

2. Install and Start MeshCentral

Create a dedicated directory (e.g., /opt/meshcentral) and run the following commands in your terminal.

⚠️ Do not use sudo with the npm install meshcentral command.

# Example: Create and move into the directory
mkdir -p /opt/meshcentral
cd /opt/meshcentral

# Install the MeshCentral package
npm install meshcentral

# Start the server
node node_modules/meshcentral

That's it! MeshCentral will now set itself up and begin managing computers on your local network that have the MeshAgent installed.

Running as a Service

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.

⚙️ Configuration and Customization

Default Mode and Initial Access

By default, MeshCentral starts in LAN-only mode. Agents use local network multicasting to find the server.

The first user account you create upon accessing the server will automatically become the server administrator. Access the login page in your web browser and create your account right away.
Once installed, server settings are stored in the config.json file, which is located inside the meshcentral-data folder.

Advanced Configuration

The config.json file holds hundreds of options for deep customization, including:

Switching the server from LAN-only to WAN/Hybrid mode by setting a known DNS name.
Customizing the server with your own branding.
Setting up an SMTP email server or SMS services.

The configuration file must be valid JSON. You can use an online tool or utilities like jq to validate its format.

You can find sample configuration files on the GitHub repository for reference:

Database and Scaling Notes

Database: By default, MeshCentral uses NeDB, its built-in database. For advanced use cases and better performance, it's recommended to switch to MongoDB or an SQL-based solution like Postgresql.
Hardware: MeshCentral is very lightweight. You can run a server capable of managing a few hundred devices on a small platform like a Raspberry Pi or an AWS t3.nano instance running Linux.
Service Mode: To run the server as a background service, start it with the --help argument to view options for background installation.

For a visual guide, check out the official YouTube Tutorial Videos.

\<div class="video-wrapper"> \<iframe src="https://www.youtube.com/embed/LSiWuu71k_U" frameborder="0" allowfullscreen>\</iframe> \</div>

Do you want to know more about configuring the server for WAN access or switching to a different database?

Installation Guides

Installation

🧾 Abstract

These guides are specifically intended to help users install and configure MeshCentral.
Once installed, you can take a look at the MeshCentral user’s guide,
for information on how to configure MeshCentral for your specific use.
In this document, we will look at installing MeshCentral on different operating systems like:

And remember! The config.json is case insensitive in its keys.

📢 Quick-start
🧐 Advanced Information
🪟 Windows-specific

📦 NPM Installation for Advanced Users

Prerequisites and Verification

Before beginning the installation, ensure Node.js and NPM (Node Package Manager) are installed on your host operating system.

If your server is behind an HTTP/HTTPS proxy, you may need to configure NPM's proxy settings.

1. Verify Node.js and NPM

Open your command-line terminal (CMD/PowerShell on Windows, or Shell on Linux) and run the following commands to check the installed versions:

Node.js:
```
node -v
```
NPM:
```
npm -v
```

2. Configure Proxy Settings (If Applicable)

If your server requires a proxy to access the internet, you must set the proxy configurations for NPM. Skip this step if not needed.

# Set HTTP proxy
npm config set proxy http://proxy.com:88
# Set HTTPS proxy
npm config set https-proxy http://proxy.com:88

MeshCentral Installation

3. Install MeshCentral

Create a dedicated directory for the installation, change into it, and use NPM to install the MeshCentral package.

Recommendation: On Linux, use the /opt directory.

⚠️ Important: Do not use sudo when executing the npm install meshcentral command.

# Create the directory
mkdir -p /opt/meshcentral
# Move into the directory
cd /opt/meshcentral
# Install MeshCentral
npm install meshcentral

4. Start the Server

Once the download is complete, start the MeshCentral server.

⚠️ Crucial: Do not cd into the node_modules/meshcentral directory to run the server. Running it from the directory above node_modules is required for features like auto-install and self-update to function correctly.

node node_modules/meshcentral [arguments]

LAN-Only Mode: If you run the command without arguments, MeshCentral will default to LAN-only mode, meaning you can only manage computers on the local network.

5. Configure for WAN/Internet Access (Optional)

To manage computers over the internet (WAN or Hybrid Mode), your server needs a static IP or a DNS record that resolves to its public address. This is how remote mesh agents "call home."

While command-line parameters exist, it's highly recommended to use a configuration file for persistent settings.

Here are examples of starting the server and generating initial certificates for a public address:

# Using a domain name
node node_modules/meshcentral --cert servername.domain.com
# Using an IP address
node node_modules/meshcentral --cert 1.2.3.4

Note: The first time you run in WAN or Hybrid Mode, MeshCentral will generate necessary certificates, which may take a few minutes.

Once running, immediately create your admin account by navigating to https://127.0.0.1 (or your public hostname) in a web browser.

🐳 Container (OCI-specification).

Open Container Initiative

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.

🔗 References:

Warning

Do not use the built-in MeshCentral update functionality (when using containers).
Update the container the 'docker way', by updating the image itself.

🏷️ Basic Tags:

Tag-name	Explanation
`master`	This tag belongs to the image which is built on every new commit to the main branch, therefor it has the latest code.
`latest`	This tag takes the latest released version of MeshCentral.
`1.1.51`	You can also specify the specific MeshCentral release with its tag, for example: `ghcr.io/ylianst/meshcentral:1.1.43`

All Tags

All master tags below follow the master branch of MeshCentral, the latest and version numbered versions follow the releases.

Tag-name	Explanation
`master-slim`	Docker image with no database packages present, which makes it the most lean. Uses NeDB.
`master-mongodb`	Docker image with the MongoDB packages installed.
`master-postgresql`	Docker image with the PostgreSQL packages installed
`master-mysql`	Docker image with the MySQL packages installed
`1.1.51-slim` and `latest-slim`	Docker image with no database packages present, which makes it the most lean. Uses NeDB.
`1.1.51-mongodb` and `latest-mongodb`	Docker image with the MongoDB packages installed.
`1.1.51-postgresql` and `latest-postgresql`	Docker image with the PostgreSQL packages installed.
`1.1.51-mysql` and `latest-mysql`	Docker image with the MySQL packages installed.

📌 Note: Refer to this page for more information on the container status.

🐋 Docker/Podman

For single-machine setups such as Docker and Podman.

Pulling the image:

To pull the container image use the following container registry.

docker pull ghcr.io/ylianst/meshcentral:latest

Docker CLI:

If you want to run the container from the Terminal, you can use the following command:

docker run -d \
  --name meshcentral \
  --restart unless-stopped \
  -p 80:80 \
  -p 443:443 \
  -v data:/opt/meshcentral/meshcentral-data \
  -v user_files:/opt/meshcentral/meshcentral-files \
  -v backup:/opt/meshcentral/meshcentral-backups \
  -v web:/opt/meshcentral/meshcentral-web \
  ghcr.io/ylianst/meshcentral:latest

Docker Compose:

If you want to use a docker compose yaml file, please refer to the example below.

services:
  meshcentral:
    image: ghcr.io/ylianst/meshcentral:latest
    environment:
      - DYNAMIC_CONFIG=false # Show the option but disable it by default, for safety.
    volumes:
      - meshcentral-data:/opt/meshcentral/meshcentral-data
      - meshcentral-files:/opt/meshcentral/meshcentral-files
      - meshcentral-web:/opt/meshcentral/meshcentral-web
      - meshcentral-backups:/opt/meshcentral/meshcentral-backups
    ports:
      - "80:80"
      - "443:443"
volumes:
  meshcentral-data:
  meshcentral-files:
  meshcentral-web:
  meshcentral-backups:

Refer to the Dockerfile for its environment variables.

☸️ Kubernetes

Using YAML deployment files.

📚 Extra sources

Github Docker Resources

Quickstart

🪟 Quick Start on Windows with the Installer

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 Node.js if necessary.

You can download the MeshCentral installer from the official website or by clicking this link.

Recommendation: We advise running the installer on a modern version of Windows (e.g., Windows 8.1, Windows 10, or Windows Server 2012 or newer).

Installation Prompts Explained

The installer will guide you through a few key settings:

Setting	Description
Multi-user Server	Enabled (Checked): The server is open to the public. Users can create accounts and manage their own devices. Disabled (Unchecked): The server is limited to a single-user mode, with no login screen, accessible only from the server host machine.
Auto-update Server	Enabled: 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.
Server Mode	Choose how agents find the server:
LAN Mode	Recommended for small, local networks. The server does not need a fixed IP or DNS name.
WAN/Hybrid Mode	Required for managing devices over the internet. You must enter the server's public DNS name or static IP address into the Server Name field. This name must be correct or agents will fail to connect. If unsure, start with LAN Mode.

Once installed, MeshCentral runs as a background Windows Service and can be accessed via the web browser link provided by the installer.

Updating and Maintenance

The installation tool can be run again at any time to:

Perform a Server Update: The tool compares your installed version to the latest one on NPM.
Re-install the server.
Un-install the server.

🔒 Windows Defender Firewall Settings

The installer automatically configures the Windows Defender Firewall to allow MeshCentral to accept incoming connections.

By default, MeshCentral uses the following ports: * TCP Ports: 80 (HTTP), 443 (HTTPS), and 4433 (Intel® AMT CIRA). * UDP Port: 16990 (Added for server discovery in LAN or Hybrid mode).

If you performed an advanced NPM installation or need to change the default ports, you may need to manually modify these firewall rules.

Accessing Firewall Settings

Open Control Panel.
Go to System and Security.
Click Windows Defender Firewall.
Click Advanced Settings on the left side.
Select Inbound Rules.

If you used the installer, you should see rules named MeshCentral Server TCP ports and optionally MeshCentral Server UDP ports.

1. Editing Existing Rules

To change the allowed ports (e.g., if you changed the MeshCentral configuration): 1. Double-click the existing rule (e.g., MeshCentral Server TCP ports). 2. Go to the Protocols and Ports tab. 3. Modify the Local ports field.

2. Adding New Rules

To create a new inbound firewall rule: 1. Click New Rule... on the right side. 2. Select Port and click Next. 3. Choose either TCP or UDP. 4. Select Specific local ports and enter the port numbers (e.g., 80, 443, 4433). Click Next. 5. Ensure Allow the connection is selected and click Next. 6. Select the profiles (Domain, Private, Public) where the rule should apply and click Next. 7. Enter a descriptive Name for the rule and click Finish.

Databases

This section will go into how to configure MongoDB as a database backend.

Following the schema we make the following changes to our config.json.
Some requires keys have been omitted to further the focus on database configuration. Don't remove these as well.

MeshCentral Cheatsheet:

MongoDB is configured using the MongoDB connection string.

{
  "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
  "__comment__": "Omitted these keys to focus on the database",
  "settings": {
    "mongoDb": "mongodb://localhost:27017/meshcentral"
  },
  "domains": {
    "": {
      "__comment__": "Omitted these keys to focus on the database",
    }
  },
  "_letsencrypt": {
    "__comment__": "Omitted these keys to focus on the database",
  }
}

This section will go into how to configure PostgreSQL as a database backend.

Following the schema we make the following changes to our config.json.
Some requires keys have been omitted to further the focus on database configuration. Don't remove these as well.

MeshCentral Cheatsheet:

The postgres installation inside settings is rather straightforward if you are familiar with it on MeshCentral its side.

{
  "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
  "__comment__": "Omitted these keys to focus on the database",
  "settings": {
    "postgres": {
        "host": "my-postgresql-hostname",
        "port": "5432",
        "user": "my-postgresql-user",
        "password": "my-postgresql-password",
        "database": "meshcentral-database"
    }
  },
  "domains": {
    "": {
      "__comment__": "Omitted these keys to focus on the database",
    }
  },
  "_letsencrypt": {
    "__comment__": "Omitted these keys to focus on the database",
  }
}

More options are available if needed. Refer to the schema above.

Postgres Cheatsheet

# Log into the server
psql -U postgres

-- Create the database user
postgres=# CREATE USER meshcentral WITH PASSWORD 'your-very-strong-password';
CREATE ROLE

-- Create the database and set the above user as owner
postgres=# CREATE DATABASE meshcentral OWNER meshcentral;
CREATE DATABASE

-- Exit the database
postgres=# exit

This section will go into how to configure MySQL/MariaDB as a database backend.

Following the schema we make the following changes to our config.json.
Some requires keys have been omitted to further the focus on database configuration. Don't remove these as well.

MeshCentral Cheatsheet:

Database specific:

MariaDB:

{
  "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
  "__comment__": "Omitted these keys to focus on the database",
  "settings": {
    "mariaDB": {
        "host": "my-mariadb-hostname",
        "port": "3306",
        "user": "my-mariadb-user",
        "password": "my-mariadb-password",
        "database": "meshcentral-database"
    }
  },
  "domains": {
    "": {
      "__comment__": "Omitted these keys to focus on the database",
    }
  },
  "_letsencrypt": {
    "__comment__": "Omitted these keys to focus on the database",
  }
}

Mysql:

{
  "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
  "__comment__": "Omitted these keys to focus on the database",
  "settings": {
    "mySQL": {
        "host": "my-mysql-hostname",
        "port": "3306",
        "user": "my-mysql-user",
        "password": "my-mysql-password",
        "database": "meshcentral-database"
    }
  },
  "domains": {
    "": {
      "__comment__": "Omitted these keys to focus on the database",
    }
  },
  "_letsencrypt": {
    "__comment__": "Omitted these keys to focus on the database",
  }
}

MariaDB/MySQL Cheatsheet:

mariadb -u root -p

or

mysql -u root -p

-- Create the database
CREATE DATABASE meshcentral;

-- Create the user (restricting login to localhost)
CREATE USER 'meshcentral'@'localhost' IDENTIFIED BY 'my-very-secure-password';

-- Grant privileges
GRANT ALL PRIVILEGES ON meshcentral.* TO 'meshcentral'@'localhost';

-- Apply changes
FLUSH PRIVILEGES;

This section will go into how to configure a local database as backend.

Following the schema we make the following changes to our config.json.
Some requires keys have been omitted to further the focus on database configuration. Don't remove these as well.

By default MeshCentral uses NeDB so therefor to change that to another database type, do the following:

MeshCentral Cheatsheet:

Sqlite3:

{
  "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
  "__comment__": "Omitted these keys to focus on the database",
  "settings": {
    "sqlite3": {
        "name": "meshcentral-db"
    }
  },
  "domains": {
    "": {
      "__comment__": "Omitted these keys to focus on the database",
    }
  },
  "_letsencrypt": {
    "__comment__": "Omitted these keys to focus on the database",
  }
}

Acebase:

{
  "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
  "__comment__": "Omitted these keys to focus on the database",
  "settings": {
    "acebase": {
        "sponsor": false
    }
  },
  "domains": {
    "": {
      "__comment__": "Omitted these keys to focus on the database",
    }
  },
  "_letsencrypt": {
    "__comment__": "Omitted these keys to focus on the database",
  }
}

Security

🛡️ Crowdsec

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.

🎬 Video Walkthru

Secure

🔒 Increased Security Installation on Debian/Ubuntu

For enhanced security on Debian-based Linux distributions (like Ubuntu), it's best practice to run MeshCentral under a dedicated, low-privilege user account. This prevents the server from making unauthorized changes to the system.

⚠️ Important: Running with restricted privileges disables MeshCentral's self-update capability. Updates must be performed manually. Additionally, this setup requires using an external database (like MongoDB) because the primary data folder will be read-only.

1. Create a Low-Privilege User

Start by creating a system user named meshcentral. This user will be restricted from logging in and changing files outside its designated directory.

sudo useradd -r -d /opt/meshcentral -s /sbin/nologin meshcentral

2. Install MeshCentral

Next, create the installation directory and install the package using NPM.

# Create the installation folder
sudo mkdir /opt/meshcentral

# Change to the installation directory
cd /opt/meshcentral

# Install MeshCentral (as the created user)
sudo -u meshcentral npm install meshcentral

3. Initialize Data Folders

Run the server once under the new low-privilege user to generate the necessary data folders and install any initial dependencies.

# Run once as the meshcentral user
sudo -u meshcentral node ./node_modules/meshcentral

Once the server is running and the folders have been created, press CTRL-C to stop the process.

4. Restrict Permissions

Now, set the ownership and permissions to ensure the meshcentral user has read-only access to the application code, enhancing security.

# Change ownership of all files to the meshcentral user and group
sudo chown -R meshcentral:meshcentral /opt/meshcentral

# Set read/execute permissions for the meshcentral user on data folders
# Note: meshcentral-* refers to meshcentral-data, meshcentral-files, etc.
sudo chmod -R 755 /opt/meshcentral/

5. Adjust Write Permissions for Functionality (Optional)

In a restricted environment, you need to explicitly grant write access to specific subfolders the server needs to modify during operation.

A. File Upload/Download

If you plan to use MeshCentral's file transfer features, the server needs to read and write to the meshcentral-files folder:

sudo chmod -R 755 /opt/meshcentral/meshcentral-files

B. Let's Encrypt Support

If you plan to use MeshCentral's built-in Let's Encrypt support, you must make its certificate folder writable to avoid ACCES: permission denied exceptions:

# Create the necessary sub-folders if they don't exist
sudo mkdir -p /opt/meshcentral/meshcentral-data/letsencrypt

# Grant write access to the letsencrypt folder
sudo chmod -R 775 /opt/meshcentral/meshcentral-data/letsencrypt

6. Manual Server Update

Because the meshcentral user lacks write access to the /node_modules directory, the server cannot update itself. To perform a manual update:

Use systemctl (or your service manager) to stop the MeshCentral server process.
Run the following commands:

cd /opt/meshcentral

# Update the MeshCentral package via NPM (requires sudo/root privileges)
sudo npm install meshcentral

# Re-set ownership to the meshcentral user
sudo chown -R meshcentral:meshcentral /opt/meshcentral

Use systemctl to restart the MeshCentral server.

This process updates the server to the latest version on NPM and reapplies the strict permissions.

MeshCentral

MeshCentral Guide

🧾 Abstract

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.

📘 Introduction

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.

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.

At a high level, there are only four (4) main steps : Setup, Install, Connect, and Control.

Setup the MeshCentral server on VM or PC
Log on to MeshCentral portal with a valid account, creates an administrative mesh to collect all end-points (systems to be managed)
Generates an agent and installs it on a target or each end-point that immediately attempts a connection back to MeshCentral server.
Controls/manages assets or end-points that are available in respective administrative mesh

🎬 Video Walkthru

🖥️ Server Installation

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 https://www.meshcommander.com/meshcentral2 for information on how to install the server.

📌 Note:

For information on how to install the server, please refer to the MeshCentral Installer’s Guide available at:
https://www.meshcommander.com/meshcentral2

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.

🚀 Basic Usage

In this section we will cover the basics of MeshCentral in your newly setup server.

Launch

Start your web browser and access MeshCentral via IP address/URL, http://serverFQDN/. If MeshCentral is running locally, enter http://127.0.0.1/. MeshCentral will redirect the browser to HTTPS if the server was accessed with HTTP. Once on HTTPS you will likely see this message:

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.

Proceeding with Browser Security Warnings

Firefox

To continue on Firefox:

Click on Advanced
Select Add Exception
Click Confirm Security Exception

Chrome

To continue on Chrome:

Click on Advanced
Click Proceed to http://serverIP (unsafe)

📌 Note:

You can also get to a device by specifying the device name in the URL by adding ?viewmode=10&gotodevicename=MyComputer to the URL of the MeshCentral web page. The new gotodevicename 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, &gotonode= is always the preferred way to access a device. This feature also works on the mobile web site.

Create Account

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 :

New device group

Once logged in, create a new device group. This is a group of computers that we want to manage. To proceed,

Click on “Click here to create a new group of devices”,
Key in a suitable “Name”, .e.g. “SampleGroup”
Leave “Type” to default “Manage using a software agent” and click ‘OK”.

Note

There are two types of groups:
- Software Agent Group: Commonly used to manage computers. Administrator must install a “remote management agent” on the remote computers.
- Intel® AMT Agent-less Group: Exclusive for remote computers that has Intel® AMT activated and needs to be managed independent of a “remote management agent”.

Add device

To add devices into new mesh

Click “Add Agent”,
Select the right Operating Systems (Windows* OS) and download the Mesh Agent executable.
Copy the Mesh Agent file into remote computers with Windows* OS

4. Run Mesh Agent and Click “install”

Note

Mesh Agent is available for Windows* and Linux*.

For Windows*, the mesh agent doesn’t contain any sensitive data and can copied and reused on many Windows* computers.
For Linux*, instead of an executable, an installation script is provided to add remote computers.

The script checks the type of computer and installs the proper agent automatically.

After agent install

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.

Manage Computer

Click on any computer and go into the “Desktop” and “Files” tabs to remotely manage the computer or perform file transfer.

For advance users with console/command line interface experience, go into “Terminal” to perform scripting or quick tasks with CLI tools.

Desktop Control

Depending on how the agent is connected to the server, there are multiple methods to remote control :

Mesh Agent,
RDP,
and AMT

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 General Tab > Credentials. Click pen to clear them.

🔐 Server Certificate

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.

Users have few ways to handle this certificate warning:

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 “webserver-cert-public.crt” file in the “meshcentral-data” folder of the server.
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.
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.

Important

Before adding/importing the certificate, user must check the validity of the certificate presented by the website and compare with “root-cert-public.crt” file in the “meshcentral-data” folder of the server.

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.

If a legitimate trusted certificate is available, replace “webserver-cert-public.crt” and `“webserver-cert-private.key” with your certificate. These files are located in “meshcentral-data” folder of the server.
If intermediate certificates are needed, add the files “webserver-cert-chain1.crt”, “webserver-cert-chain2.crt”, “webserver-cert-chain3.crt” respectively with the intermediate certificates.

📌 Note :

If you are using TLS offloading, see the section on “TLS Offloading” cover in the latter parts of this document.

📁 Files and Folder Structure

It’s important to know the basic file and folder structure from which MeshCentral was installed as shown below

Right after running the npm install meshcentral 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.

Important

User must periodically backup both meshcentral-data and meshcentral-files which contains all of server’s data.

The “meshcentral-data” folder will contain:

meshcentral.db :

The server’s database file which contains all of the user and computer information. This includes account information and other sensitive information.
Five .key and .crt files:

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.
config.json file:

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.

The “meshcentral-files” 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.

Important

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.

⚙️ Server Configuration File

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:

    {
        "settings": {
            "cert": "mesh.myserver.com",
            "port": 8080,
            "redirport": 81
        },
        "domains": {
            "": {
                "title": "MyServer",
                "title2": "Servername",
                "userQuota": 1048576,
                "meshQuota": 248576,
                "newAccounts" : 1
            },
            "Customer1": {
                "title": "Customer1",
                "title2": "Extra String",
                "newAccounts" : 0
            }
        },
        "peers": {
            "serverId" : "Server1",
            "servers": {
                "Server1": { "url": "wss://192.168.1.100:443/" },
                "Server2": { "url": "wss://192.168.1.101:443/" }
            }
        }
    }

First, we will look at each of the top levels of the configuration file. The tops levels are “settings”, “domains”, “peers”, and “smtp” as shown in the table below.

Settings

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 :

Setting	Description
Cert	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.
Port	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)
AliasPort	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.
RedirPort	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.
MpsPort	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.
TLSOffload	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.
SelfUpdate	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.
SessionKey	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.
Minify	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.
User	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.
NoUsers	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
MpsCert	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.
MpsAliasPort	Specify an alias port for the MPS server. See the section on "Server port aliasing" for use of this option.
ExactPorts	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.
Lanonly	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.
Wanonly	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.
AllowFraming	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.
AllowLoginToken	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.
MongoDB	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.
MongoDBCol	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.
DbEncryptKey	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.
WebRTC	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.
ClickOnce	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.

Important

Changes in config.json will NOT take effect until server is restarted.

📌 Note :

We recommend the user to use a non-production server to experiment the setting options above.

Domains

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 :

🔗 https://servername:8080/ — Default domain
🔗 https://servername:8080/customer1 — Customer1 domain
🔗 https://servername:8080/customer2 — Customer2 domain

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.

Each domain has sub-settings as follows:

*Sub Settings*	*Description*
Title & Title2	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
UserQuota	This is the maximum amount of data in kilobytes that can be placed in the “My Files” tab for a user account.
MeshQuota	This is the maximum amount of data in kilobytes that can be placed in the “My Files” tab for a given mesh
NewAccounts	If set to zero (0)
UserAllowedIP	Allows user to set a list of allowed IP addresses. See section on server IP filtering.
Auth	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.
Dns	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.
CertUrl	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. 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.
PasswordRequirements	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. The value must be set to an object, for example: `{ ""min"": 8, ""max"": 128, ""upper"": 1, ""lower"": 1, ""numeric"": 1, ""nonalpha"": 1 }` 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. 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.

📌 Note :

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.

In this mode, the server will serve a different TLS certificate depending on what DNS record is used to access the server.

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”.

🤝 Server Peering

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.

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.

Recommended

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)

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.

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.

    {
        "peers": {
            "serverId" : "Server1",
            "servers": {
                "Server1": { "url": "wss://192.168.1.100:443/" },
                "Server2": { "url": "wss://192.168.1.101:443/" }
            }
        }
    }

The configuration above assumes that server1 has an IP address of 192.168.1.100 and server2 has 192.168.1.101 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.

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 --tlsoffload, then use “ws://” for the URL instead of wss://.

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.

Once peered, all of the servers should act like one single host, no matter which server the user(s) are connected to.

📧 Email Setup

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

A verification email is sent when a new account is created or if the user requests it in the “My Account” tab.

The password recovery flow when “Reset Account” is triggered at the login page.

Both account verification and password recovery are triggered automatically once SMTP mail server configuration is included into the config.json file.

SMTP: User/Pass

Normal Server

Update the config.json with “smtp” section as shown below and restart the server.

{
  "smtp": {
    "host": "smtp.server.com",
    "port": 25,
    "from": "myaddress@server.com",
    "user": "myaddress@server.com",      # Optional
    "pass": "mypassword",                # Optional
    "tls": false                         # Optional, default false
  }
}

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.

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.

Gmail

One option is to configure MeshCentral work with Google Gmail by setting host with smtp.gmail.com, and port with 587. In the config.json file, use user’s Gmail address for both from 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:

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.

SMTP: OAuth Authentication

Gmail

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.

Start by visiting the Google API console:

🔗 Google Developers Console

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"

Click on the "OAuth Consent Screen" link, Under "APIs and Services" from the left hand menu:

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.

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:

Once this is complete, the next step will be to add credentials.

Choose OAuth Client

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.

Next, you will need to visit the Google OAuth Playground:

https://developers.google.com/oauthplayground

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 https://mail.google.com and click Authorize API.

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:

"smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "from": "my@googleaccount.com",
    "auth": {
      "clientId": "<YOUR-CLIENT-ID>",
      "clientSecret": "<YOUR-CLIENT-SECRET>",
      "refreshToken": "<YOUR-REFRESH-TOKEN>"
    },
    "user": "noreply@authorizedgooglealias.com",
    "emailDelaySeconds": 10,
    "tls": false,
    "verifyEmail": true
  }

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.

After successfully configuring the Gmail SMTP server, switch the OAuth 'Publishing Status' from Testing to In Production. This step prevents the need for frequent refresh token generation. Verification of your project isn't required to make this change.

🛢️ Database

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 NeDB that is written entirely in NodeJS and is setup automatically when MeshCentral is installed with the npm tool. The file meshcentral.db will be created in the “meshcentral-data” folder when MeshCentral is first launched. This database works well for small deployments scenarios.

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.

Database Export

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.

To export the database, stop the MeshCentral server and run the server again with --dbexport and a JSON file called meshcentral.db.json will be created in the meshcentral-data folder as shown below.

Alternatively, user can also specify the full export path for the JSON file as shown below.

Database Import

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.

Important

Importing a JSON file will overwrite the entire content of the database. A starting empty database is recommended.

When you are ready to import a JSON file into the database, run meshcentral with --dbimport as shown below. If path is not specified, the application will default to use meshcentral.db.json that is in meshcentral-data folder.

Alternatively, user can specify the full path of the import JSON as shown below.

Viewing the Database

For debugging purposes, Meshcentral allow users to have quick preview of certain frequently accessed data in the database with the following options:

*Option*	*Description*
`--showusers`	List of all users in the database.
`--showmeshes`	List of all meshes in the database.
`--shownodes`	List of all nodes in the database
`--showevents`	List all events in the database
`--showpower`	List all power events in the database.
`--showall`	List all records in the database.

For example, you can show the list of users with the --showusers

MongoDB Setup

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.

After completing the installation step,

Stop any instance of Meshcentral that is running locally or in any machine
Start a terminal or Windows Command prompt (CMD),
Create a folder “c:\data\db”
Go to the MongoDB bin folder and run mongod --bind 127.0.0.1.

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”.

📌 Note :

We recommend the user to use a non-production server to experiment the setting options above.

📌 Note :

Upon successful execution, MongoDB will wait for connections on its default port 27017.

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.
```
node meshcentral --mongodb mongodb://127.0.0.1:27017/meshcentral
```

Alternatively, to transition an existing meshcentral DB from NeDB and to MongoDB, just run commands below:

node meshcentral --dbexport

node meshcentral --mongodb mongodb://127.0.0.1:27017/meshcentral --dbimport

node meshcentral --mongodb mongodb://127.0.0.1:27017/meshcentral

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
```
{
  "settings": {
    "mongodb": "mongodb://127.0.0.1:27017/meshcentral",
    "mongodbcol": "meshcentral"
  }
}
```

📌 Note :

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.

If you are using MongoDB with authentication, you can change the URL a little to add the username and password, for example:

mongodb://username:password@127.0.0.1:27017/meshcentral

You can also provide extra connection parameters like this:

mongodb://username:password@127.0.0.1:27017/meshcentral?authMechanism=MONGODB-CR&authSource=db

🌀 Running State-less

By default, MeshCentral will read its configuration information from the meshcentral-data folder. The most important file in that folder being the config.json file, but the folder also contains certificates, branding images, terms of service and more.

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.

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.

To make this happen, we will be using the following command line options from MeshCentral:

*Command*	*Description*
`--configkey (key)`	Specifies the encryption password that will be used to read or write the configuration files to the database.
`--dblistconfigfiles`	List the names and size of all configuration files in the database.
`--dbshowconfigfile (filename)`	Show the content of a specified filename from the database. --configkey is required.
`--dbdeleteconfigfiles`	Delete all configuration files from the database.
*`--dbpushconfigfiles '' or (folder path)`**	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.
`--dbpullconfigfiles (folder path)`	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.
`--loadconfigfromdb (key)`	Runs MeshCentral server using the configuration files found in the database. The configkey may be specified with this command or --configkey can be used.

Once we have MeshCentral running as expected using the meshcentral-data folder, we can simply push that configuration into the database and run using the database alone like this:

node ./node_modules/meshcentral --dbpushconfigfiles '*' --configkey mypassword

node ./node_modules/meshcentral --loadconfigfromdb mypassword --mongodb "mongodb://127.0.0.1:27017/meshcentral"

This first line will load many of the “meshcentral-data” files into the database. At this point, we can back up the meshcentral-data folder and remove it. Then run the second line to start the server. Here we use MongoDB, but if one uses NeDB, the meshcentral.db file in the “meshcentral-data” folder will still be needed.

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.

⌨️ Commandline Options

In general, doing --option value is the same as adding "option": value in the settings section of the config.json.

Here are the most common options found by running meshcentral --help

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.

🔒 TLS Offloading

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 or Apache) so please contact your network administrator for the best solution that suits your setup.

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.

To make this work, it is important the server is setup with --tlsoffload. 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.

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

*Port*	*Function Description*
80	Directly forwards port 80 to MeshCentral port 80
443	Handle TLS using a web certificate and forward to MeshCentral port 443
4433	Handle TLS using MPS certificate and forward to MeshCentral port 4433

If possible, port 443 should be configured with a legitimate trusted certificate and the public part of the certificate named as webserver-cert-public.crt must be placed inside of meshcentral-data 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.

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.

📌 Note :

Please consult the TLS offloader user manual from the respective vendor to configure TLS offloading feature correctly.

📜 Let’s Encrypt support

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 Let's Encrypt. 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.

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 letsdebug.net 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:

{
  "settings": {
    "RedirPort": 80,
  },
  "letsencrypt": {
    "email": "myemail@myserver.com",
    "names": "domain1.com,domain2.com",
    "rsaKeySize": 3072,
    "production": false
  },
}

The only mandatory field is the email address, please enter a valid one.

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 --cert [name].

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.

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.

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.

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:

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.

Note

Please be patient with Let’s Encrypt certificate requests and make sure you correctly get a staging certificate before setting production to true.

If Let’s Encrypt works for you, please consider donating to them as they provide a critical service to the Internet community.

🛡️ Server IP filtering

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.

MeshCentral provides IP filtering option in the config.json file for each domain. For an example, we can set IP address whitelist for the default domain like as shown below.

    {
        "domains": {
            "": {
                "userallowedip" : "1.2.3.4,1.2.3.5",
            }
        }
    }

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.

📌 Note :

When IP address whitelist is effective, Mesh Agent connection from any IP address will be not affected.

You can also use files for IP lists

"userAllowedIp": "file:userallowedips.txt",
"userBlockedIp": "file:userblockedips.txt",
"agentAllowedIp": "file:agentallowedips.txt"

Place the file in the meshcentral-data folder.

All the lines that start with a number or : will be used, everything else is ignored. So, you can put comments anyway you like, but probably best to start then with a # or something to make it clear.

# 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

🧩 Embedding MeshCentral

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.

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.

To make this work, a following key alignment is required :

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.
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.
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.

In this section we will review both the login token and embedding options mentioned above.

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 --nousers or --user admin when you run the server, but these approach are not secure as it removes user authentication for those accessing the server.

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.

To enable this feature, configure config.json file to allow login tokens.

{
  "settings": {
    "allowLoginToken": true,
    "allowFraming": true
  }
}

Set both allowLoginToken and allowFraming to true to use login tokens along with framing MeshCentral within another web page.

Next, create a token. Execute MeshCentral with the --logintoken [userid] switch and userid value with the example below:

The userid is actually a combination of three values - user, domain, and username in a single string user/domain/username. 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.

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.

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 --loginTokenKey switch as shown below

The generated masker key must be placed in a secure location within the business website.

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.

Embedding Options

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.

Embedding Options / URL Argument	Description	Values
viewmode	Indicates the information to show. This is an integer value, possible values are:	1 = Devices tab 2 = Account tab 3 = Events Live 4 = Users General 5 = Server files tab 6 = Server General 10 = Device general information 11 = Device remote desktop 12 = Device terminal 13 = Device files 14 = Device Intel AMT console 15 = Device Mesh Agent console 16 = Device events 17 = Device info 19 = Device plugins 20 = Mesh General 21 = Mesh Summary 30 = User General 31 = User Events 40 = Server Stats 41 = Server Trace 42 = Server Plugins 50 = Users Groups 52 = Users Recordings 60 = Events Report 115 = Server Console Note: 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.
hide	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.	1 = Hide the page header 2 = Hide the page tab 4 = Hide the page footer 8 = Hide the page title 16 = Hide the left tool bar 32 = Hide back buttons
node	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: `https://localhost/?node=UkSNlz7t...2Sve6Srl6FltDd&viewmode=11&hide=15`	Node or NodeID is a long base64 encoded SHA384 value

📌 Note :

Typically, the URL for the website is followed by “?” then a set of name=value pairs separated by &.

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.

Only the remote desktop viewer will be displayed embedded within an iframe.

📌 Note :

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.

🔀 Server port aliasing

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.

For example you can run :

    node meshcentral --redirport 2001 --port 2002 --aliasport 443

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.

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.

In the following picture we have a usual server running with :

node meshcentral --cert Server1 --port 443 --mpsport 4433

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:

node meshcentral --cert Server1 --mpscert Server2 --port 443 --mpsport 4433 --mpsaliasport 443

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 Server2 on it. The server will also configure Intel AMT CIRA to connect to Server2:443.

A router or firewall that is located in front of the MeshCentral server needs to be configured correctly to forwarding :

Server1:443 -> 443 on MeshCentral

Server2:443 -> 4433 on MeshCentral

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.

📡 Web relay using DNS names and multiple web relays

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.

🎬 Video Walkthrus

🖧 Device Groups with Relay Agent

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.

To enable SSH support, add this line to the domain section of your config.json:

"ssh": true

Video Walkthru

Raritan and WebPowerSwitch with Relay

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.

🧭 NGINX Reverse-Proxy Setup

Video Walkthru

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: Nginx

In this example, we will :

Run MeshCentral on non-standard ports, but alias HTTPS to port 443.
NGINX will be using standard ports 80 and 443.
We will have NGINX perform all TLS authentication & encryption.
MeshCentral will read the NGINX web certificate so agents will perform correct server authentication.
NGINX will be setup with long timeouts, because agents have long standard web socket connections.

Note

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

Let’s get started by configuring MeshCentral with the following values in config.json:

{
  "settings": {
    "Cert": "myservername.domain.com",
    "Port": 4430,
    "AliasPort": 443,
    "RedirPort": 800,
    "AgentPong": 300,
    "TlsOffload": "127.0.0.1"
  },
  "domains": {
    "": {
      "certUrl": "https://127.0.0.1:443/"
    }
  }
}

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 myservername.domain.com, 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”.

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.

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.

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”.

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.

Next, we need to configure and launch NGINX. Here is an ngnix.conf to get started:

worker_processes 1;

events {
    worker_connections 1024;
}

http {
    # HTTP server. In this example, we use a wildcard as server name.
    server {
        listen 80;
        server_name _;

        location / {
            proxy_pass http://127.0.0.1:800/;
            proxy_http_version 1.1;

            # Inform MeshCentral about the real host, port and protocol
            proxy_set_header X-Forwarded-Host $host:$server_port;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }

    # HTTPS server. In this example, we use a wildcard as server name.
    server {
        listen 443 ssl;
        server_name _;

        # MeshCentral uses long standing web socket connections, set longer timeouts.
        proxy_send_timeout 330s;
        proxy_read_timeout 330s;

        # We can use the MeshCentral generated certificate & key
        ssl_certificate webserver-cert-public.crt;
        ssl_certificate_key webserver-cert-private.key;
        ssl_session_cache shared:WEBSSL:10m;
        ssl_ciphers HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers on;

        location / {
            proxy_pass http://127.0.0.1:4430/;
            proxy_http_version 1.1;

            # Allows websockets over HTTPS.
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;

            # Inform MeshCentral about the real host, port and protocol
            proxy_set_header X-Forwarded-Host $host:$server_port;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}

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.

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:

MeshCentral HTTP redirection web server running on port 800.
Loaded RSA web certificate at https://127.0.0.1:443/, SHA384: d9de9e27a229b5355708a3672fb23237cc994a680b3570d242a91e36b4ae5bc96539e59746e2b71eef3dbdabbf2ae138.
MeshCentral Intel(R) AMT server running on myservername.domain.com:4433.
MeshCentral HTTP web server running on port 4430, alias port 443.

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.

CIRA Setup with NGINX

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.

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:

stream {
    # Internal MPS servers, in this case we use one MeshCentral MPS server is on our own computer.
    upstream mpsservers {
        server 127.0.0.1:44330 max_fails=3 fail_timeout=30s;
    }

    # We can use the MeshCentral generated MPS certificate & key
    ssl_certificate mpsserver-cert-public.crt;
    ssl_certificate_key mpsserver-cert-private.key;
    ssl_session_cache shared:MPSSSL:10m;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    # MPS server.
    server {
        listen 4433 ssl;
        proxy_pass mpsservers;
        proxy_next_upstream on;
    }
}

NGINX will listen on port 4433, decrypt the connection and forward it to 44330 on the loopback interface. We are going to be used the “mpsserver” certificate that was created by MeshCentral as the TLS server certificate for port 4433. Now, we just have to make a few changes to the MeshCentral config.json file.

{
  "settings": {
    "Cert": "myservername.domain.com"
    "Port": 4430,
    "AliasPort": 443,
    "RedirPort": 800,
    "TlsOffload": "127.0.0.1"
    "MpsPort": 44330,
    "MpsAliasPort": 4433,
    "MpsTlsOffload": true
  },
  "domains": {
    "": {
      "certUrl": "https://127.0.0.1:443/"
    }
  }
}

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.

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.

🚦Traefik Reverse-Proxy Setup

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/

This section covers a really simple Traefik configuration. Traefik is capable of a lot more complex configurations.

In this example, we will:

MeshCentral on non-standard ports, but alias HTTPS to port 443.
Traefik will be using standard ports 80 and 443.
We will have Traefik perform all TLS authentication & encryption.
MeshCentral will read the NGINX web certificate so agents will perform correct server authentication.

First we will start with the MeshCentral configuration, here is a minimal configuration that will work:

{
  "settings": {
    "Cert": "myservername.domain.com",
    "Port": 4430,
    "AliasPort": 443,
    "RedirPort": 800,
    "TlsOffload": "127.0.0.1"
  },
  "domains": {
    "": {
      "certUrl": "https://127.0.0.1:443/"
      "AgentConfig": [ "webSocketMaskOverride=1" ]
    }
  }
}

📌 Note “agentConfig” line :

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.

The TlsOffload line indicates that MeshCentral should not perform TLS on port 4430. And the certUrl line indicates what URL can be used to load the external certificate that will be presented on port 443 in front of MeshCentral.

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:

[global]
  checkNewVersion = false
  sendAnonymousUsage = false

[entryPoints]
  [entryPoints.http]
  address = ":80"
    [entryPoints.http.redirect]
    entryPoint = "https"
  [entryPoints.https]
  address = ":443"
    [entryPoints.https.tls]
      [[entryPoints.https.tls.certificates]]
      certFile = "webserver-cert-public.crt"
      keyFile = "webserver-cert-private.key"

[file]

[backends]
  [backends.backend1]
    [backends.backend1.healthcheck]
      path = "/health.ashx"
      interval = "30s"

    [backends.backend1.servers.server1]
    url = "http://127.0.0.1:4430"
    weight = 1

[frontends]
  [frontends.frontend1]
  entryPoints = ["https"]
  backend = "backend1"
  passHostHeader = true
  [frontends.frontend1.routes]
    [frontends.frontend1.routes.main]
    rule = "Host:myserver.domain.com,localhost"

[api]
  entryPoint = "traefik"
  dashboard = true

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.

The backends section configures one MeshCentral server on port “4430”. Traefik will additionally check the health of the MeshCentral server periodically, every 30 seconds.

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 myserver.domain.com or localhost.

Finally, the API section creates a web portal on port 8080 for monitoring of Traefik.

⚡ HAProxy Reverse-Proxy Setup

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: HAProxy Official Website

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.

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.

global
    log /dev/log local0
    log /dev/log local1 notice
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
    stats timeout 30s
    user haproxy
    group haproxy
    daemon

defaults
    log global
    mode http
    option httplog
    option dontlognull
    option forwardfor
    option http-server-close

frontend http
    bind *:80
    redirect scheme https code 301 if !{ ssl_fc }

frontend https
    bind *:443 ssl crt /etc/haproxy/cert.pem
    http-request add-header X-Forwarded-Proto https
    acl acmepath path_beg /.well-known/acme-challenge/
    acl meshcentralhost hdr(host) -i mesh.sample.com
    acl meshcentralhost hdr(host) -i mesh.sample.com:443
    use_backend acme if acmepath
    use_backend meshcentral if meshcentralhost

backend acme
    server certbot localhost:54321

backend meshcentral
    http-request add-header X-Forwarded-Host %[req.hdr(Host)]
    server meshcentral 127.0.0.1:444

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.

{
  "settings": {
    "Cert": "myservername.domain.com",
    "Port": 444,
    "AliasPort": 443,
    "RedirPort": 0,
    "TlsOffload": "127.0.0.1"
  },
  "domains": {
    "": {
      "certUrl": "https://127.0.0.1:443/"
    }
  }
}

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.

🏭 Running in a Production Environment

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”.

On Linux, this is done like this:

export NODE_ENV=production

On Windows, it’s done like this:

SET NODE_ENV=production

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 :

MeshCentral HTTP redirection web server running on port 80.
MeshCentral v0.2.2-u, Hybrid (LAN + WAN) mode, Production mode.
MeshCentral Intel(R) AMT server running on devbox.mesh.meshcentral.com:4433.
MeshCentral HTTPS web server running on devbox.mesh.meshcentral.com:443.

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.

📲 Two step authentication

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.

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.

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.

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.

And taking authentication to the next step is removing the login page entirely. Use LoginKey 3FA with MeshCentral.

You can also setup Duo 2FA which is a commertial offering.

💾 Server Backup & Restore

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.

meshcentral-data
meshcentral-files

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.

mongodump --archive=backup.archive

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.

To restore back backup, just install a MeshCentral server, make sure it works correctly. Stop it, wipe the old meshcentral-data and meshcentral-files and put the backup version instead. If using MongoDB, copy the backup.archive back, make sure to clean up any existing “meshcentral” database, run mongo and type:

use meshcentral

db.dropDatabase()

Then exit with Ctrl-C and run:

mongorestore --archive=backup.archive

This will re-import the database from the backup. You can then start MeshCentral again.

Note

The two values for backup and restore in the json are only valid for databases backed by NeDB

Backup to Google Drive

sudo systemctl stop meshcentral.service

nano /opt/meshcentral/meshcentral-data/config.json

Remove underscored items

sudo systemctl start meshcentral.service

sudo systemctl status meshcentral.service

Log into your MC:

Create desktop app

Enter the Client ID and Client Secret into MC

🗝️ HashiCorp Vault support

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: HashiCorp Vault Official Site

Once you got a MeshCentral server working correctly, you can start a simple demonstration Vault server by typing:

vault server -dev

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:

node node_modules/meshcentral --vaultpushconfigfiles --vault http://127.0.0.1:8200 --token s.cO4… --unsealkey 7g4w… --name meshcentral

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”:

The config.json and terms.txt files and files in meshcentral-data that end with .key, .crt, .jpg and .png will be stored in Vault. You can then run MeshCentral like this:

node node_modules/meshcentral --vault http://127.0.0.1:8200 --token s.cO4… --unsealkey 7g4w… --name meshcentral

MeshCentral will first read all of the files from Vault and get started. An alternative to this is to create a very small config.json file in “meshcentral-data” that contains only the Vault configuration like this:

{
  "settings": {
    "vault": {
      "endpoint": "http://127.0.0.1:8200",
      "token": "s.cO4Q…",
      "unsealkey": "7g4wFC…",
      "name": "meshcentral"
    }
  }
}

Once the config.json file is setup, you can just run MeshCentral without any arguments.

node node_modules/meshcentral

Lastly you can all pull all of the files out of Vault using this command line:

node node_modules/meshcentral --vaultpullconfigfiles --vault http://127.0.0.1:8200 --token s.cO4… --unsealkey 7g4w… --name meshcentral

And delete the Vault secrets using this:

node node_modules/meshcentral --vaultdeleteconfigfiles --vault http://127.0.0.1:8200 --token s.cO4… --unsealkey 7g4w… --name meshcentral

🔏 Database Record Encryption

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.

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 _CRYPT field.

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:

{
  "settings": {
    "Port": 4430,
    "RedirPort": 800,
    "DbRecordsEncryptKey": "MyReallySecretPassword"
  }
}

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:

node node_modules/meshcentral --recordencryptionrecode

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:

{
  "settings": {
    "Port": 4430,
    "RedirPort": 800,
    "DbRecordsDecryptKey": "MyReallySecretPassword"
  }
}

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:

node node_modules/meshcentral --recordencryptionrecode

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.

📌 Note :

Also note that database record encryption can and should be used along with other data protection systems.

📊 MongoDB free server monitoring

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:

Type db.enableFreemonitoring() 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:

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.

🔓 MeshCentral Single Sign-On (SSO)

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.

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.

LDAP

You can integrate LDAP using these configuration options

Twitter Authentication

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 Twitter Developer Apps, this is where you can create new applications that are compatible with Twitter.

Start by creating a new application and fill in the application form. Give your application and name, description, server URL and more.

Make sure to select “Enable Sign in with Twitter” and set the callback URL to https://(server.domain.com)/auth-twitter-callback. 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:

Once the new application is created, go to the Keys and tokens tab. You will need the API Key and API secret key values. In the MeshCentral config.json, place these two values as clientid and clientsecret of the Twitter section of the AuthStrategies.

Once done, your config.json should look a bit like this:

{
  "settings": {
    "Cert": "myserver.mydomain.com",
    "Port": 443,
    "RedirPort": 80
  },
  "domains": {
    "": {
      "Title": "MyServer",
      "Title2": "Servername",
      "NewAccounts": true,
      "authStrategies": {
        "twitter": {
          "clientid": "xxxxxxxxxxxxxxxxxxxxxxx",
          "clientsecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        }
      }
    }
  }
}

📌 Note :

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.

Google, GitHub, Reddit Authentication

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 ClientID and ClientSecret for each service. You also need to register the correct callback URL for each service.

Take a look at the config.json below and note the callback URL that will need to be registered for each service provider.

{
  "settings": {
    "Cert": "myserver.mydomain.com",
    "Port": 443,
    "RedirPort": 80
  },
  "domains": {
    "": {
      "Title": "MyServer",
      "Title2": "Servername",
      "NewAccounts": true,
      "authStrategies": {
        "twitter": {
          "__callbackurl": "https://server/auth-twitter-callback",
          "clientid": "xxxxxxxxxxxxxxxxxxxxxxx",
          "clientsecret": " xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx "
        },
        "google": {
          "__callbackurl": "https://server/auth-google-callback",
          "clientid": "xxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com",
          "clientsecret": "xxxxxxxxxxxxxxxxxxxxxxx"
        },
        "github": {
          "__callbackurl": "https://server/auth-github-callback",
          "clientid": "xxxxxxxxxxxxxxxxxxxxxxx",
          "clientsecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
        "reddit": {
          "__callbackurl": "https://server/auth-reddit-callback",
          "clientid": "xxxxxxxxxxxxxxxxxxxxxxx",
          "clientsecret": " xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx "
        }
      }
    }
  }
}

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.

Microsoft Azure Active Directory

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.

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 https://[servername]/auth-azure-callback. 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.

Next, we need to create a secret that will be shared between Azure and MeshCentral. Go to the Certificates & secrets section and click New client secret. You then enter a name and for our example, we will opt to never make it expire.

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:

{
  "settings": {
    "Cert": "myserver.mydomain.com",
    "Port": 443,
    "RedirPort": 80
  },
  "domains": {
    "": {
      "Title": "MyServer",
      "Title2": "Servername",
      "NewAccounts": false,
      "authStrategies": {
        "azure": {
          "newAccounts": true,
          "clientid": "be4aadd3-77b8-4e55-af8a-4b8e2d994cb5",
          "clientsecret": "NP0XXXXXXXXXXXXXXXXXXX",
          "tenantid": "18910a48-e492-4c49-8043-3449f7964bd6"
        }
      }
    }
  }
}

The Application ID value is placed as Client ID in the configuration file. You can also see that in the example above, we have NewAccounts 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.

JumpCloud Authentication using SAML

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.

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.

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 JumpCloud and creating an administrator account. Once setup, go to Applications and click on the big plug sign to create a new application.

You will need to create a custom SAML application by clicking the Custom SAML App.

Then, you can fill in the form with an application name and logo.

For the IdP Entity ID, put jumpcloud.
For the SP Entity ID put meshcentral.
For the ACS URL, put the callback URL of your server. In this case it will be https://(yourservername)/auth-jumpcloud-callback
Lastly in the attributes section, add 3 user attribute mapping.
- firstname to firstname
- lastname to lastname
- email to email

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.

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 All Users group.

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 Applications tab, click on your new application and select Download Certificate as shown here.

Save the certificate as jumpcloud-saml.pem and place it in the meshcentral-data folder. You are now ready to configure MeshCentral.

Edit the config.json and make it look like this:

{
  "settings": {
    "Cert": "myserver.mydomain.com",
    "Port": 443,
    "RedirPort": 80
  },
  "domains": {
    "": {
      "Title": "MyServer",
      "Title2": "Servername",
      "NewAccounts": false,
      "authStrategies": {
        "jumpcloud": {
          "__callbackurl": "https://server/auth-jumpcloud-callback",
          "NewAccounts": true,
          "entityid": "meshcentral",
          "idpurl": "https://sso.jumpcloud.com/saml2/saml2",
          "cert": "jumpcloud-saml.pem"
        }
      }
    }
  }
}

Take note that the entityid, idpurl and cert 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 NewAccounts 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.

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.

Users can sign-in using the regular username and password or using JumpCloud.

Generic SAML setup

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 config.json to that a generic login icon is shown on the login page.

A generic SAML setup will look like this:

{
  "settings": {
    "Cert": "myserver.mydomain.com",
    "Port": 443,
    "RedirPort": 80
  },
  "domains": {
    "": {
      "Title": "MyServer",
      "Title2": "Servername",
      "NewAccounts": 1,
      "authStrategies": {
        "saml": {
          "__callbackurl": "https://server/auth-saml-callback",
          "entityid": "meshcentral",
          "idpurl": "https://server/saml2",
          "cert": "saml.pem"
        }
      }
    }
  }
}

The callback URL will be of the form https://(servername)/auth-saml-callback. You should set the entityid, idpurl as given by the identity provider. Lastly, place the identity provider certificate file in the meshcentral-data folder and indicate the name of the file in cert.

Once setup, restart the server and you should see a Single Sign-on button on the login screen.

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.

Note

MeshCentral only supports "POST". For example Authentik's default setting is to use Redirect as a Service Provider Binding.

Generic OpenID Connect Setup

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.

{
    "settings": {
        "cert": "mesh.your.domain",
        "port": 443,
        "sqlite3": true
    },
    "domains": {
        "": {
            "title": "Mesh",
            "title2": ".Your.Domain",
            "authStrategies": {
                "oidc": {
                    "issuer": "https://sso.your.domain",
                    "clientid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
                    "clientsecret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                    "newAccounts": true
                }
            }
        }
  }
}

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 additional strategy documentation.

📌 Note :

MeshCentral will use https://mesh.your.domain/auth-oidc-callback as the default redirect uri.

✨ Improvements to MeshCentral

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 :

Quick Installation –

By having MeshCentral published on NPM (www.npmjs.com) it’s now easy to download and install MeshCentral on both Linux and Windows. On Linux you can use NPM directly (npm install meshcentral) and on Windows you can use the .MSI installer.
Cross-Platform Support –

Contrary to MeshCentral1 that only runs on Windows, MeshCentral can run on any environment that supports NodeJS. This includes Windows, Linux and OSX. Because MeshCentral runs on Linux, it often lowers hosting costs and makes it possible to run MeshCentral in a Docker container environment.
Runs with Little Compute Resources –

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.
Multi-Tenancy and Load Balancing Support –

MeshCentral can handle hosting many server instances at once. Each instance or domain has it’s own administrators, users and computers to manage. The server can handle each instance using a url path server.com/customer1 or a DNS name customer1.server.com. 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.
Single Executable –

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.
Web Application Design –

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.
Real-Time User Interface –

In MeshCentral, the user never has to hit the refresh 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.
Single Programming Language –

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.
Support for LAN only Mode –

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.
Support for TLS Offloaders –

TLS offloaders are now fully supported. This means that MeshCentral can handle way more network connections and traffic significantly.
Support for CIRA User/Pass Login –

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.
No Live State Stored in the Database –

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.
Agentless Intel AMT Support –

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.
Latest Security & Crypto algorithms –

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.
Support for Email Verification and Password Recovery –

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.
MeshInterceptor Support –

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.

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.

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.

💡 Additional Resources

In addition to this document, there are a growing set of MeshCentral tutorial videos available on YouTube which covers all of the basic at www.meshcommander.com/meshcentral2/tutorials . The tutorial includes videos on how to perform server installation using both the Windows MSI installer and NPM methods.

🏁 Conclusion

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.

License

MeshCentral and this document are both opens source and licensed using Apache 2.0, the full license can be found at https://www.apache.org/licenses/LICENSE-2.0.

Annex 1: Sample Configuration File

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.

{
  "settings": {
    "MongoDb": "mongodb://127.0.0.1:27017/meshcentral",
    "MongoDbCol": "meshcentral",
    "Port": 4430,
    "AliasPort": 443,
    "RedirPort": 800,
    "TlsOffload": "127.0.0.1",
    "MpsPort": 44330,
    "MpsAliasPort": 4433,
    "MpsTlsOffload": true,
    "SessionTime": 30,
    "SessionKey": "MyReallySecretPassword",
    "AllowLoginToken": true,
    "AllowFraming": true,
    "WebRTC": true,
    "ClickOnce": true
  },
  "domains": {
    "": {
      "Title": "MyServer",
      "Title2": "Servername",
      "TitlePicture": "title-sample.png",
      "UserQuota": 1048576,
      "MeshQuota": 248576,
      "NewAccounts": true,
      "Footer": "<a href='https://twitter.com/mytwitter'>Twitter</a>",
      "PasswordRequirements": { "min": 8, "max": 128, "upper": 1, "lower": 1, "numeric": 1, "nonalpha": 1 }
    },
    "customer1": {
      "Dns": "customer1.myserver.com",
      "Title": "Customer1",
      "Title2": "TestServer",
      "NewAccounts": 1,
      "Auth": "sspi",
      "Footer": "Test"
    },
    "info": {
      "share": "C:\\ExtraWebSite"
    }
  },
  "letsencrypt": {
    "email": "myemail@myserver.com ",
    "names": "myserver.com,customer1.myserver.com",
    "rsaKeySize": 3072,
    "production": false
  },
  "peers": {
    "serverId": "server1",
    "servers": {
      "server1": { "url": "wss://192.168.2.133:443/" },
      "server2": { "url": "wss://192.168.1.106:443/" }
    }
  },
  "smtp": {
    "host": "smtp.myserver.com",
    "port": 25,
    "from": "myemail@myserver.com",
    "tls": false
  }
}

All these values are examples only, this config.json should just be used as an example and none of the values here are real.

Annex 2: Tips & Tricks

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: https://github.com/Ylianst/MeshCentral/issues

Remote Terminal

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:

su -s /bin/bash myOtherUser

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:

su -c '/bin/bash -i' myOtherUser

This will run bash in interactive mode and work correctly.

SSH and SFTP integration to the Terminal

MeshCentral has built-in web-based integration of SSH in the "Terminal" tab and SFTP in the "Files" tab.

PDF and ODT handout(s).

MeshCentral Guide

MeshCmd Guide as .pdf as .odt

Configuration Options

There are MANY configuration options available with meshcentral, search this file for options: https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json

Some options you can find relate to:

DNS
HTTPS
MPS (Management Presence Server)
MongoDB
MariaDB
SQLite3
MySQL
PostgreSQL
AceBase
WAN (Wide Area Network)
LAN (Local Area Network)
Maintenance Mode
Session Cookie
Database Encryption
Web Relay
Agent Connection
TLS (Transport Layer Security)
WebRTC
Web Push Notifications
Auto Backup
Crowdsec
IP KVM (Keyboard, Video, Mouse over IP)
Mesh Router
Syslog
WebDAV
Certificates and Authentication
MeshCentral Server Settings
Device Management
User Permissions
Remote Desktop Configuration

and more!

Server Options

Domain Options

SSL/Letsencrypt

MeshCentral supports SSL using self generated certs, your own certs or Letsencrypt

Enabling letsencrypt

Make sure you match and/or adjust all the following settings appropriately in your config.json file:

{
    "settings": {
        "redirPort"
        "cert": "yourdomain.com"
    },
    "domains": {
        "letsencrypt": {
        "__comment__": "Requires NodeJS 8.x or better, Go to https://letsdebug.net/ first before trying Let's Encrypt.",
        "email": "myemail@myserver.com",
        "names": "myserver.com,customer1.myserver.com",
        "skipChallengeVerification": false,
        "production": true
        },
    }
}

If you need further clarification to know what each of these settings are, check out the config schema.

Then restart meshcentral and it will get a cert for you, the process will need to restart to apply the cert.

Useful resources/troubleshooting

To check letsencrypt is working properly please use https://letsdebug.net/. We are using the HTTP-O1 challenge method with these instructions.

Also make sure you have port 80 open and pointing to your meshcentral server, IT WILL NOT WORK if port 80 isn't open and it HAS to be port 80.

You can read more about Letsencrypt and meshcentral here.

Mesh Agents

Windows

Default Install Path: c:\Program Files\Mesh Agent

Application Path: c:\Program Files\Mesh Agent\meshagent.exe

Application database Path: c:\Program Files\Mesh Agent\meshagent.db

Application Log Path: c:\Program Files\Mesh Agent\meshagent.log

xxx Path: c:\Program Files\Mesh Agent\meshagent.msh

Status Troubleshooting

Start: net start "mesh agent"
Stop: net stop "mesh agent"
Restart: net restart "mesh agent"
Status: Needs info

Troubleshooting steps: Needs info

Linux / BSD

Uninstall: sudo /usr/local/mesh_services/meshagent/[agent-name]/meshagent -fulluninstall

Apple macOS Binary Installer

Default Install Path: /usr/local/mesh_services/meshagent/meshagent

Launches from /Library/LaunchAgents/meshagent.plist

Controlling agent

launchctl stop meshagent
launchctl start meshagent

Install:

Uninstall: sudo /usr/local/mesh_services/meshagent/[agent-name]/meshagent -fulluninstall

Apple macOS Universal

For OSx 11+ including Big Sur, Monterey and later

Apple macOS

For macOS 10.x including Catalina, Mojave, High Sierra, Sierra, El Capitan, Yosemite, Mavericks, Mountain Lion and earlier.

Mobile Device (Android)

MeshCentral Assistant

See Assistant

Apple MacOS Binary Installer

Agent Commands

agentmsg : Add/Remove badged messages to the device's web ui

  agentmsg add "[message]" [iconIndex]
  agentmsg remove [index]
  agentmsg list

agentsize : Returns the binary size of the agent

agentupdate : Manually trigger an agent self-update

alert : Display an alert dialog on the logged in session

alert TITLE, CAPTION [, TIMEOUT]

amt

amtconfig

amtevents

apf

args

av : Displays Antivirus State

coredump

coreinfo

cpuinfo

cs : Display Windows Connected Standby State

dbcompact : Compacts the agent database

dbget

dbkeys

dbset

dnsinfo : Display DNS server info

domain : Display domain metadata

errorlog

eval : executes javascript on the agent

eval [code]

fdcount : Returns the number of active descriptors in the event loop

fdsnapshot : Returns detailed descriptor/handle/timer metadata

getclip : Fetches clipboard data from agent

getscript

help : Returns the list of supported console commands

httpget

info : Returns general information about the agent, such as connected state, loaded modules, LMS state, etc

kill : Sends a SIGKILL signal to the specified PID

kill [pid]

kvmmode : Displays the KVM Message Format

location : Displays saves location information about the connected agent

lock

log : Writes a message to the logfile

log [message]

ls : Enumerates the files in the agent's install folder

mousetrails : Enables/Disables Mouse Trails Accessibility on Windows. To change setting, specify a positive integer representing the number of latent cursors, where 0 is disable

mousetrails [n]

msh : Displays the loaded msh settings file

netinfo : Displays network interface information

notify : Display a notification on the web interface

openurl

osinfo : Displays OS information

parseuri : Parses the specified URI, and displays the parsed output

parseuri [uri]

plugin : Invokes a plugin

plugin [pluginName] [args]

power : Performs the specified power action

power [action]
  LOGOFF = 1
  SHUTDOWN = 2
  REBOOT = 3
  SLEEP = 4
  HIBERNATE = 5
  DISPLAYON = 6
  KEEPAWAKE = 7
  BEEP = 8
  CTRLALTDEL = 9
  VIBRATE = 13
  FLASH = 14

print

privacybar : Sets/Gets the default pinned state of the Privacy Bar on windows

privacybar [PINNED|UNPINNED]

ps : Enumerates processes on the agent

rawsmbios : Fetches the raw smbios table

safemode : Sets/Gets the SAFEMODE configuration of the agent, as well as the next boot state.

safemode (ON|OFF|STATUS)

scanwifi : Scans the available Wifi access points, and displays the SSID and Signal Strength

service : Shortcut to be able to restart the agent service

service status|restart

setclip : Sets clipboard data to the agent

setclip [text]

setdebug : Sets the location target for debug messages

setdebug [target]
0 = Disabled
1 = StdOut
2 = This Console
* = All Consoles
4 = WebLog
8 = Logfile

smbios : Displays the parsed SMBIOS metadata

startupoptions : Displays the command-line options that the agent was started with

sysinfo : Collects and displays telemetry on the platform

task

taskbar : Hides or shows the Windows System task bar, optionally on the specified Terminal Server Session ID

taskbar HIDE|SHOW [TSID]

timerinfo : Displays metadata about any configured timers on the event loop

toast : Displays a toast message on the logged in user's session

toast [message]

translations : Shows the currently configured translations

type

type (filepath) [maxlength]

uac : Get/Sets the Windows UAC mode

uac [get|interactive|secure]

unzip

unzip input, destination

: Unzips the specified file

users : Enumerates the logged in users on the system

versions : Displays version information about the agent

vm : Detects if the system is a Virtual Machine

volumes : Displays volume information reported by the OS

wakeonlan : Sends wake-on-lan packets to the specified MAC address

wakeonlan [mac]

wallpaper : Gets/Toggles the logged in user's desktop background image

wallpaper (GET|TOGGLE)

wpfhwacceleration : Enable/Disable WPF HW Acceleration on Windows

wpfhwacceleration (ON|OFF|STATUS)

wsclose

wsconnect

wslist

wssend

zip

zip (output file name), input1 [, input n]

Agent msh options

You can find a full list of options for the agent here

skipmaccheck=1: Will not regenerate the agents nodeid and cause duplication of the agent when the MAC address changes.

You can add options to your .msh on agent install with this

MeshCentral Assistant

Initial Setup

Agent Invite Code

"domains": {
    "": {
        "agentInviteCodes": true
    }
}

agent invite code

Agent Invitation

Click on the 'Invite' button next to the device group name to access it.

Link Invitation

For link invitation web page customization:

Alongside meshcentral-data create a folder called meshcentral-web
Create a views folder in it and copy the file node_modules/meshcentral/views/invite.handlebars into it.
That copy will be served instead of the default one, so you can customize it as you want.

agent invite code

Email Invitation

This option will show up if you have an SMTP email server set up with MeshCentral.

For invitation email customization:

Alongside meshcentral-data create a folder called meshcentral-web
Create an emails folder in it and copy the files node_modules/meshcentral/emails/mesh-invite.txt and node_modules/meshcentral/emails/mesh-invite.html into it.
These copies will be used instead of the default ones, so you can customize them as you want.

email-invitation

Email notification

You can also get an email notification when someone clicks the "Request Help" button in the Assistant agent.

Code Signing

Authenticode-JS Video

Nodejs Code Signing module

MeshCentral comes with authenticode.js, you can run it like this:

node node_modules/meshcentral/authenticode-js

and you will get

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]

Automatic Agent Code Signing

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:

Note

If you generate your private key on windows with use BEGIN PRIVATE KEY and openssl needs BEGIN RSA PRIVATE KEY you can convert your private key to rsa private key using openssl rsa -in server.key -out server_new.key

Setting Agent File info

Now that MeshCentral customizes and signs the agent, you can set that value to anything you like.

"domains": {
      "agentFileInfo": {
            "filedescription": "sample_filedescription",
            "fileversion": "0.1.2.3",
            "internalname": "sample_internalname",
            "legalcopyright": "sample_legalcopyright",
            "originalfilename": "sample_originalfilename",
            "productname": "sample_productname",
            "productversion": "v0.1.2.3"
      }
}

External Signing Job

The externalsignjob feature allows you to perform additional operations on the agent after MeshCentral completes its code signing process. This is particularly useful for:

Using hardware security tokens for signing
Performing signing on a separate server or cloud host
Archiving signed agents
Adding additional security measures

The externalsignjob is called after MeshCentral completes its entire code signing process, including: - Resource modification - Digital signature application - Timestamp application (if configured)

To use this feature, add the following to your config.json:

"settings": {
    "externalsignjob": "path/to/your/script.bat"
}

The script will receive the path to the agent as its first argument. Here are example scripts:

Batch File Example

@echo off
Echo External Signing Job
signtool sign /tr http://timestamp.sectigo.com /td SHA256 /fd SHA256 /a /v /f path/to/your/signing.cer /csp "eToken Base Cryptographic Provider" /k "[{{MyPassword}}]=PrivateKeyContainerName" "%~1"

PowerShell Example

$file = $args[0]
signtool sign /tr http://timestamp.sectigo.com /td SHA256 /fd SHA256 /a /v /f path/to/your/signing.cer /csp "eToken Base Cryptographic Provider" /k "[{{MyPassword}}]=PrivateKeyContainerName" $file

The externalsignjob can be used for more than just signing. For example, you could:

Archive signed agents to a secure location
Upload signed agents to a distribution server
Perform additional security checks
Add custom metadata or watermarks
Integrate with your organization's build pipeline

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.

Debugging

Websockets Video

Make sure you understand how MeshCentral works with your browser using chrome developer tools.

MeshCentral Server

Useful config.js settings

https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json

"AgentsInRAM": false,
"AgentUpdateBlockSize": 2048,
"agentUpdateSystem": 1,
"noAgentUpdate": 1,
"WsCompression": false,
"AgentWsCompression": false,

Understanding node and paths

Note that when running MeshCentral, you should always run from the path that is parent to node_modules, so you do this:

cd C:\Program Files\Open Source\MeshCentral
node node_modules\meshcentral

You do NOT do this:

cd C:\Program Files\Open Source\MeshCentral\node_modules\meshcentral
node meshcentral

The problem with the second command is that NPM may install missing modules in the incorrect location.

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:

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

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.

Unable to update server

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:

{
  "settings": {
    "npmPath": "c:\\npm.exe",
    "npmProxy": "http://1.2.3.4:80"
  }
}

The problem could also be that you need a proxy, the configuration line to that is above.

You can also manually update. Just stop your server and so this:

mv node_modules node_modules_bak
npm install meshcentral
node node_modules/meshcentral

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:

node node_modules/meshcentral --install
node node_modules/meshcentral --uninstall
node node_modules/meshcentral --start
node node_modules/meshcentral --stop

Port Troubleshooting on server

If you're getting a port 4433 is not available 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.

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.

Running Meshcentral server in debug mode

Debug more will cause MeshCentral to output a lot of debug messages to the console. To display all debug messages, run MeshCentral like this:

node node_modules/meshcentral --debug

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:

node node_modules/meshcentral --debug web,amt,mps

Here is the list of all debug options:

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

You can also specify the debug option in the config.json file in the settings section. For example:

"settings": {
  "debug": "web,amt,mps"
}

Enabling trace in your browser Dev Tools

You can enable browser console tracing by adding trace=1 as a parameter to the URL of the MeshCentral main web page. For example https://myserver.com/?trace=1. Once present, open the browser's console window to see all web client tracing messages.

To log all database queries, change log_statement in /etc/postgresql/13/main/postgresql.conf

# CUSTOM
log_statement = 'all'           # none, ddl, mod, all

The stacktrace was logged to stdout/journalctl. Supposedly, you can enable debug logging for node modules by adding DEBUG=<modulename> to the environment.

Adding this to /etc/systemd/system/meshcentral.service should do it but it didn't seem to do anything.

I think that's because Mesh uses the trace logging in the browser instead of logging things in the server logs.

Environment=DEBUG=mesh*

If you want to change node to meshcentral in journalctl, add this to /etc/systemd/system/meshcentral.service.

SyslogIdentifier=meshcentral

Finding agent problems

Using the servers My Server > console

agentstatus - Gives you summary counts of problems
agentissues - Gives IP:port and what error
dupagents - Gives duplicateAgent IP's, counts and names

Logging it all

To log everything that's possible, prepare the log directory.

mkdir /meshcentral/meshcentral-logs/
chown tactical:tactical logs
ln -s ../meshcentral-logs/log.txt /meshcentral/meshcentral-data/log.txt

And then add this to your config.

    "meshErrorLogPath": "/meshcentral/meshcentral-logs/",
    "authLog": "/meshcentral/meshcentral-logs/auth.log",
    "log": [
        "cookie",
        "dispatch",
        "main",
        "peer",
        "web",
        "webrequest",
        "relay",
        "webrelaydata",
        "webrelay",
        "mps",
        "mpscmd",
        "swarm",
        "swarmcmd",
        "agentupdate",
        "agent",
        "cert",
        "db",
        "email",
        "amt",
        "httpheaders",
        "websocket"
    ],

You'll then have 3 files:

-rw-rw-r-- 1 tactical tactical   2593 Feb  2 12:22 auth.log
-rw-r--r-- 1 tactical tactical 147593 Feb  2 12:31 log.txt
-rw-rw-r-- 1 tactical tactical    381 Feb  2 12:02 mesherrors.txt

log.txt will now log everything in the Trace tab

Restricting server to specific IP(s)

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:

"agentAllowedIp": [ "192.168.2.147" ],

Of course, this is just for debugging.

Finding system ID types

https://serverurl/meshagents aka trying figure out what this is

Pull down cert .crt file from internet

See #1662 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:

echo -n \| openssl s_client -connect yourdomain.com:443 2> /dev/null\| sed -ne '/-BEGIN   CERTIFICATE-/,/-END CERTIFICATE-/p' > /opt/meshcentral/meshcentral-data/webserver-cert-public.crt
service meshcentral restart

MeshAgent

Troubleshooting agent

./meshagent -state

Agent Debug Logs to server

This automatically downloads all agent error logs into meshcentral-data/agenterrorlogs.txt

Set in config.json

"agentLogDump": true

Determine Agent capabilities

On the server goto the agents console tab. Type:

info

Useful MeshAgent.msh flags

https://github.com/Ylianst/MeshAgent/blob/master/meshcore/agentcore.h#L190

controlChannelDebug=1
logUpdate=1

Obtain generated .msh File

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.

MeshAgent Commands

MeshAgent run
MeshAgent dbTool.js list

Forcing Core version from Cmdline

Download meschore.js and rename to CoreModule.js and put it alongside MeshAgent.exe
Stop MeshAgent service
Run MeshAgent.exe dbTool.js import CoreModule

On the fly Patching MeshAgent

MeshAgent#89 (comment)

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.....

When you are satisfied with your changes to the .js file, you can use the clipboard, in the following fashion:

meshagent -exec "require('clipboard').nativeAddCompressedModule('foo');process.exit();"

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:

meshagent -exec "setModulePath('pathToFolder');require('clipboard').nativeAddCompressedModule('foo');process.exit();"

This command is just like the previous, except it searches for modules in the path specified.

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.

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.

Agent Debugging using MeshCore JS Debugger

(#119) How to test changes to the meshagent and recompile them.

Copy duktape-debugger.js to the mesh directory on the target machine.
From the console tab of the agent, enter this command, substituting the port number you want to use instead of 9999 eval "attachDebugger({ webport: 9999 })"

Then open your browser to http://localhost:9999 or whatever port you used.

Note

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.

Troubleshooting Agent connectivity

If an agent keeps disconnecting and reconnecting, add this line to the "settings" section of the config.json:

"agentping": 30

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:

"agentpong": 30

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:

"agentpong": 90

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.

If you ever get the same problem but on the browser side, you can also use one of these:

"browserping": 30
"browserpong": 30

Same idea, browser side instead of agent side.

Intel AMT

To debug issues, confirm that Intel AMT is active and there MeshCentral is not showing any red errors on the "Intel AMT" line:

Next, you can go in the "My Server / Trace" tab and enable tracing on the "Intel AMT Manager" like this:

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.

Device Tabs

Search or Filter

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):

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

General

For viewing general information about the agent

Group
Description
IP-KVM Port Number
IP-KVM Port Type
Intel AMT
Intel AMT Tag
Mesh Agent
Operating System
Windows Security
Antivirus
Active User
User Consent
Notifications
Tags

Fields

Buttons

Actions Notes Log Event Message PDU On/Off/Control Chat

7 Day Power State

Legend

Black color: Device is Powered On on (Intel AMT & agents)
Purple color: Device is in sleep state such as Hibernating (Intel AMT agents only)
Teal color: Device is connected through AMT/CIRA, but the Power State is UNKNOWN (Intel AMT agents only)
DarkGreen color: Device is connected through AMT/CIRA and is in Soft-Off Power State (Intel AMT agents only)
Grey color: Device is Powered Off/Not Connected To MeshCentral (Intel AMT & agents)

Text Links

You can set alternate port in the link if it's not default by right-clicking.

Interfaces
Location
MeshCmd
RDP
Web-VNC
Web-RDP
Web-SSH
XTerm
HTTP
HTTPS
SSH
SCP
MQTT Login

Desktop

For connecting to the machines KVM interface.

Connect Button

Right-clicking on Connect button will give you additional options:

Ask Consent + Bar
Ask Consent
Privacy Bar

RDP Connect Button

Right-clicking on RDP Connect button allows you to specify Alternate Port.

Intel AMT Connect Button

Uses Intel AMT to control video output of the hardware video card.

During a desktop session

Bottom left include:

desktop bottom left

Sending special Keys

Top Right include:

Actions

Wake Up
Run Commands
Sleep
Reset
Power Off
Uninstall Agent

Settings

Quality
Scaling
Frame rate
Swap Mouse Buttons
Reverse Mouse Wheel
Use Remote Keyboard Map
Automatic Clipboard
Lock on Disconnect

Session recording indicator
Screen rotating
switching view mode
full screen

Bottom right include:

Session Sharing with Guest
Toggling keyboard lockout on guest
Refresh Desktop view
Upload Clipboard
Download Clipboard
Record Session to file
Take screenshot
Toggle Remote Desktop Background
Open URL on remote desktop
Lock the Remote computer
Display a notification on the remote computer
Open Chat Window

Terminal

For connecting to a command line based interface on the agent

Right-clicking on Connect button allows you to:

Note

Linux and Windows have different options:

Admin Shell (Windows)
Admin Powershell (Windows)
User Shell (Windows)
User Powershell (Windows)
SSH (Linux)

Files

For transferring files to and from the agent.

Events

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.

Details

Agent information that includes:

OS
Agent Info
Network Info
BIOS
Motherboard
Memory
Storage
Intel AMT

Note you can show CPU and Memory usage info by clicking the icon in the top right corner

Intel AMT

Console

For debugging and communicating with the mesh agent.

It allows JS commands to be issued to the device but also run extra commands from the meshcore. Type help for all available options

2falock
acceleratorsstats
agentissues
agentstats
amtacm
amtmanager
amtpasswords
amtstats
args
autobackup
backupconfig
bad2fa
badlogins
certexpire
certhashes
closeusersessions
cores
dbcounters
dbstats
dispatchtable
dropallcira
dupagents
email
emailnotifications
firebase
heapdump
heapdump2
help
info
le
lecheck
leevents
maintenance
migrationagents
mps
mpsstats
msg
nodeconfig
print
relays
removeinactivedevices
resetserver
serverupdate
setmaxtasks
showpaths
sms
swarmstats
tasklimiter
trafficdelta
trafficstats
updatecheck
usersessions
versions
watchdog
webpush
webstats

Plugins - Installation & Usage

Note

Plugins as such receive no support by the main developers of MeshCentral. If you experience problems with MeshCentral please make sure to disable all plugins before further troubleshooting!

Use Cases

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.

List of publically available plugins

https://github.com/topics/meshcentral-plugin

Installation of a plugin

First please make sure that you enable plugins in the configuration

"plugins": { "enabled": true },
Restart MeshCentral if you needed to change the configuration.
Log into MeshCentral as full administrator.
Go my My Server -> Plugins, then hit the Download plugin button.
A dialog opens requesting a URL, e.g. put in: https://github.com/ryanblenis/MeshCentral-ScriptTask
The plugin pops up in the plugin list below the download button, you can now configure and enable/disable it.

Plugins - Development & Hooks

Note

Plugins as such receive no support by the main developers of MeshCentral. If you experience problems with MeshCentral please make sure to disable all plugins before further troubleshooting!

Overview

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.

Anatomy of a plugin:

- plugin_name/
-- config.json
-- plugin_name.js
-- modules_meshcore/ // optional
--- plugin_name.js  // optional

Plugin Configuration File

A valid JSON object within a file named config.json in the root folder of your project. An example:

{
  "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"
}

Configuration File Properties

Field	Required	Type	Description
name	Yes	string	a human-readable name for the plugin
shortName	Yes	string	an alphanumeric, unique short identifier for the plugin (will be used to access your functions throughout the project
version	Yes	string	the current version of the plugin
author	No	string	the author's name
description	Yes	string	a short, human-readable description of what the plugin does
hasAdminPanel	Yes	boolean	`true` or `false`, indicates whether or not the plugin will offer its own administrative interface
homepage	Yes	string	the URL of the projects homepage
changelogUrl	Yes	string	the URL to the changelog of the project
configUrl	Yes	string	the URL to the config.json of the project
downloadUrl	Yes	string	the URL to a ZIP of the project (used for installation/upgrades)
repository	Yes	JSON object	contains the following attributes
repository.type	Yes	string	valid values are `git` and in the future, `npm` will also be supported.
repository.url	Yes	string	the URL to the project's repository
versionHistoryUrl	No	string	the URL to the project's versions/tags
meshCentralCompat	Yes	string	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.

Plugin Hooks

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.

These are separated into the following categories depending on the type of functionality the plugin should offer.

Web UI, to modify the MeshCentral admin interface
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
Mesh Agent (Node), to introduce functionality to each agent

Web UI Hooks

onDeviceRefreshEnd: called when a device is selected in the MeshCentral web interface
registerPluginTab: 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
onDesktopDisconnect: called when a remote desktop session is disconnected
onWebUIStartupEnd: called when the page has loaded for the first time after a login / refresh
goPageStart: called before page changes take effect. Passes 2 arguments ( : int, : Event)
goPageEnd: called after page changes take effect. Passes 2 arguments ( : int, : Event)

Exports

Any function can be exported to the Web UI layer by adding the name of the function to an exports array in the plugin object.

Back End Hooks

server_startup: called once when the server starts (or when the plugin is first installed)
hook_agentCoreIsStable: called once when an agent initially checks in
hook_processAgentData: called each time an agent transmits data back to the server
hook_userLoggedIn: called when a user has logged into the web interface
hook_setupHttpHandlers: called before all http handlers are setup

Mesh Agent

Use of the optional file plugin_name.js in the optional folder modules_meshcore will include the file in the default meshcore file sent to each endpoint. This is useful to add functionality on each of the endpoints.

Structure

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 parent variable within that object.

Ping-Pong

If you build a plugin which makes use of meshrelay.ashx, keep in mind to either handle ping-pong messages (serverPing, serverPong) on the control channel or to request MeshCentral to not send such messages through sending the noping=1 parameter in the connection URL. For a deeper sight search for "PING/PONG" in meshrelay.js.

Versioning

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.

Changelog

A changelog is highly recommended so that your users know what's changed since their last version.

Sample Plugin

MeshCentral-Sample 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.

Security

You can use the MeshCentral Server Console with the command badlogins to see the current settings.

Adjust these items in your config.json

"settings": {
    "_maxInvalidLogin": {
    "time": 10,
    "count": 10,
    "coolofftime": 10
    },
}

Disabling TLS 1.0/1.1 for AMT

{
  "settings": {
    "mpshighsecurity": true
  }
}

Duo 2FA setup

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 Duo.com 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:

Client ID
Client secret
API hostname

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:

{
  "domains": {
    "": {
      "duo2factor": {
        "integrationkey": "ClientId",
        "secretkey": "ClientSecret",
        "apihostname": "api-xxxxxxxxxxx.duosecurity.com"
      }
    }
  }
}

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.

14.1 Tokens

User Tokens

User Tokens 1

User Tokens 2

Software Integration Tokens

Warning

You can only have a SINGLE loginTokenKey for your meshcentral server!
So if you regenerate a loginTokenKey, the old one will be revoked/deleted!

You can create/view the Login Token Key with the following:

node node_modules/meshcentral --loginTokenKey

You can then reset/revoke/renew the Login Token Key with the following to create a new one:

node node_modules/meshcentral --loginTokenKey --loginTokenGen

FAQ

json config files

Any item in the config.json file starting with an underscore character are ignored.

Ignored

"_title": "MyServer"

Valid setting

"title": "MyServer"

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: https://duckduckgo.com/?va=j&t=hc&q=json+lint&ia=answer

Help! I've been hacked there are weird agents appearing in my MeshCentral Console

No, you haven't.

Your agent installer was scanned by an antivirus.
It didn't recognize the exe.
You have the option enabled to submit unknown applications for analysis.
They ran it against their virtualization testing cluster.
You allow anyone to connect to your server (you should look into techniques to hide your server from the internet).
Here are some examples of what that looks like.

You're sure you're typing in everything right, giving it 2FA code and can't login

TOTP is time sensitive, check your time/NTP and make sure it's right (on server and TOTP app device)! :)

Branding and Customization

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 here

Note

You will need to reinstall the agent for agent customizations to take effect.

Mac Clients

You have to manually grant Mac permissions outside of the agent install process due to the MacOS security system under Security & Privacy > Privacy

To see the screen (otherwise you just see the menu bar, and otherwise blank)

To be able to transfer files

To be able to control keyboard and mouse

I'm using CloudFlare and I'm getting a black screen but the mouse moves?

If you are using CloudFlare for your DNS hosting and your remote screen is black, DONT PANIC!

Unfortunately, MeshCentral doesn't always work with CloudFlare's Proxy DNS Mode.

The fix is to simply set the 'Proxy Status' to OFF inside your DNS A Record, within the CloudFlare control panel.

Simply follow the steps here

Once done, open your firewall for the port and agentPort ports of where your meshcentral is hosted, then restart your MeshCentral Server

There is currently a PINNED GitHub issue about this here

Tips n' Tricks

Colors in SSH

The SSH terminal does support color. The issue is going to be the terminal configuration of the shell. Try typing this:

ls -al --color /tmp

Fancy config editing with VS Code

A common problem in the issues is an incorrect config.json. What makes a config incorrect? How can you verify your config is correct?

Easy! Use Visual Studio Code to edit your config.json and add the schema at the top.

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.

{
  "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
  "settings": {
    "your settings go here": "..."
  }
}

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.

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).

Hopefully this will help verify your config is syntactically correct and prevent needless formatting errors, misspellings, etc.

Downloading Folders

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.

If you would like to share device groups with different AD users.

In the config.json set "ldapuserkey" to "sAMAccountName".

Messaging

Introduction

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.

Telegram Setup

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:

{
  "settings": {
    "Cert": "devbox.mesh.meshcentral.com",
  },
  "domains": {
    "": {
      "title": "My Server"
    }
  },
  "messaging": {
    "telegram": {
      "apiid": 0,
      "apihash": "00000000000000000000000",
      "bottoken": "00000000:aaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }
}

Note the "messaging" section in the config.json. For Telegram user login, it looks like this:

{
  "messaging": {
    "telegram": {
      "apiid": 0,
      "apihash": "00000000000000000000000",
      "session": "aaaaaaaaaaaaaaaaaaaaaaa"
    }
  }
}

User login makes use of "session", while bot login uses "bottoken". One way to get started with the setup is to run node node_modules/meshcentral --setuptelegram and follow the instructions.

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:

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.

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.

{
  "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,
      }
    }
  }
}

Discord Setup

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.

There are many tutorials online on how to create a Discord bot and get the login token. For example follow the two first sections of this tutorial. 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.

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.

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:

{
  "messaging": {
    "discord": {
      "serverurl": "https://discord.gg/xxxxxxxxx",
      "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}

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.

XMPP Setup

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.

{
  "messaging": {
    "xmpp": {
      "service": "xmppserver.com",
      "credentials": {
        "username": "username",
        "password": "password"
      }
    }
  }
}

An easy way to get setup with XMPP is to create a free account with chatterboxtown.us 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.

CallMeBot Setup

CallMeBot 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:

{
  "messaging": {
    "callmebot": true
  }
}

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.

Once the user has enabled their account, they can cut & paste the CallMeBot URI into MeshCentral to validate their account.

Pushover Setup

Pushover 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:

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:

{
  "messaging": {
    "pushover": {
      "token": "xxxxxxxxxxxxxxxxxxxxx"
    }
  }
}

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.

ntfy setup

ntfy is a completely free notification service. You can enable the ntfy integration with the following config.json section:

{
  "messaging": {
    "ntfy": true
  }
}

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.

For self-hosting your own ntfy server with ACL support

You can set host to the DNS name of your server, userurl to the url to provide to users to setup access to your server and authorization to the Basic base64 User+Pass authenttication for your server

{
  "messaging": {
    "ntfy": {
      "host": "myntfyserver.com",
      "userurl": "https://myntfyserver.com/userhelp",
      "authorization": "Basic cGhpbDpteXBhc3M="
    }
  }
}

Zulip setup

You can enable the MeshCentral Zulip integration with the following config.json section:

{
  "messaging": {
    "zulip": {
      "site": "https://api.zulip.com",
      "email": "your-bot@zulip.com",
      "api_key": "your_32_character_api_key"
    }
  }
}

Slack setup

Slack integration is achieved by the use of Incoming Webhooks. You can get started by following the Slack guide here and getting your URL

Once you have your incoming webhooks url, You can enable the Slack integration with the following config.json section

{
  "messaging": {
    "slack": true
  }
}

User Setup

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.

This verification is necessary so that MeshCentral does not send notifications to incorrect messaging accounts.

Administrator Management

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.

Two-Factor Authentication

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.

As an administrator you can turn off use of messaging for 2FA using the following settings in the config.json:

{
  "settings": {
    "Cert": "devbox.mesh.meshcentral.com",
  },
  "domains": {
    "": {
      "title": "My Server",
      "passwordRequirements": {
        "msg2factor": false
      }
    }
  }
}

Notice the msg2factor is set to false. In this case, messaging can still be used for user notifications, but will not be offered as a 2FA option.

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:

Customization

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.

Web Branding

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.

Once done, edit the config.json file and set one or all of the following values:

"domains": {
  "": {
    "Title": "",
    "Title2": "",
    "TitlePicture": "title-sample.png",
    "loginPicture": "logintitle-sample.png",
    "welcomeText": "This is sample text",
    "welcomePicture": "mainwelcome-04.jpg",
    "welcomePictureFullScreen": true,
    "siteStyle": "1",
    "nightMode": "1",
    "meshMessengerTitle": "Mesh Chat",
    "meshMessengerPicture": "chatimage.png",
    "footer": "This is a HTML string displayed at the bottom of the web page when a user is logged in.",
    "loginfooter": "This is a HTML string displayed at the bottom of the web page when a user is not logged in."
  },

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.

The title image must a PNG image of size 450 x 66.

You can also customize the server icon in the “My Server” tab. By default, it’s a picture of a desktop with a padlock.

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.

This is great to personalize the look of the server within the web site.

Customizing Web Icons

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 meshcentral-web in the main directory, where you find other folders like meshcentral-data, meshcentral-backup, meshcentral-files, and node-modules. Inside meshcentral-web, make another folder named public and copy the entire node_modules/meshcentral/public/images folder into this new meshcentral-web/public folder and then edit the files in meshcentral-web/public/images/. This step is suggested because if MeshCentral updates, it might delete any changes in node_modules. But, changes in meshcentral-web will stay safe, and MeshCentral will use these files instead of the originals in node_modules.

To update device icons, you need to edit these files: meshcentral-web/public/images/webp/iconsXX.webp (icons16.webp, icons32.webp, icons50.webp, icons100.webp), and meshcentral-web/public/images/iconsXX.png (icons16.png, icons32.png, icons50.png, icons64.png, icons100.png) and the corresponding meshcentral-web/public/images/icons256-X-1.png. Make sure to keep the resolution of these files as it is.

By following these steps, you can customize any icon in MeshCentral. Just find and change the corresponding image files in the meshcentral-web/public/images folder. Similarly, you can also move other folders from node_modules/meshcentral to meshcentral-web while keeping the original folder structure. This allows you to modify other parts of MeshCentral too, like the .handlebars templates for the web interface. Simply copy files from node_modules/meshcentral/views to meshcentral-web/views and make your changes in meshcentral-web. This lets you match MeshCentral's look to your company's brand or your own style.

Customizing Web Style

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:

Create the file custom.css under meshcentral-web/public/styles. See above for more information on meshcentral-web.
Anything added to this file will override the default stylesheets.

An example file:

#masthead {
     background-color: red;
}

#page_leftbar {
     background: linear-gradient(to bottom, #104893 0%,green 100%)
}

#footer {
     background-color: green;
}

Gives:

Custom Style

Note

You can of course override the stylesheets by directly copying them into meshcentral-web/public/styles but run the risk that future updates to those files in MeshCentral will be masked. custom.css is guaranteed to be loaded last on every page and will contain no content by default which means upgrades will work as normal.

Customizing Agent Invitation

Agents can be invited by public link or via email. Click Here to see details.

Agent Branding

You can customize the Agent to add your own logo, change the title bar, install text, the service name, or even colors!

Note

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.

"domains": {
    "": {
        "agentCustomization": {
            "displayName": "MeshCentral Agent",
            "description": "Mesh Agent background service",
            "companyName": "Mesh Agent Company",
            "serviceName": "Mesh Agent Service",
            "installText": "Text string to show in the agent installation dialog box",
            "image": "mylogo.png",
            "fileName": "meshagent",
            "foregroundColor": "#FFA500",
            "backgroundColor": "#EE82EE"
        }
    }
}

agent icon

Terms of use

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.

For example, placing this in “terms.txt”

<br />
This is a <b>test file</b>.

Will show this on the terms of use web page.

Using the OpenID Connect Strategy on MeshCentral

Overview

Introduction

There is a lot of information to go over, but first, why OpenID Connect?

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.

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.

ATTENTION: As of MeshCentral v1.1.22 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.

Chart of Frequently Used Terms and Acronyms

Term	AKA	Descriptions
OAuth 2.0	OAuth2	OAuth 2.0 is the industry-standard protocol for user authorization.
OpenID Connect	OIDC	Identity layer built on top of OAuth2 for user authentication.
Identity Provider	IdP	The service used to provide authentication and authorization.
Preset Configs	Presets	Set of pre-configured values to allow some specific IdPs to connect correctly.
OAuth2 Scope	Scope	A flag requesting access to a specific resource or endpoint
OIDC Claim	Claim	A returned property in the user info provided by your IdP
User Authentication	AuthN	Checks if you are who you say you are. Example: Username and password authentication
User Authorization	AuthZ	Check if you have the permissions required to access a specific resource or endpoint

OpenID Connect Technology Overview

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.

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.

That description was straight from OpenID Connect Documentation, 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 authentication OAuth2 is known for, with user authorization by allowing the request of additional scopes that provide additional claims or access to API's in an easily expandable way.

Annotations

Own IDP, CA and Docker

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.

The following errors can be found in the log file:

OIDC: Discovery failed.

UNABLE_TO_GET_ISSUER_CERT_LOCALLY

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:

    environment:
            - NODE_EXTRA_CA_CERTS=/opt/meshcentral/meshcentral-data/chain.pem

Basic Config

Introduction

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.

Basic Config File Example

{
    "settings": {
        "cert": "mesh.your.domain",
        "port": 443,
        "sqlite3": true
    },
    "domains": {
        "": {
            "title": "MeshCentral",
            "title2": "Your sub-title",
            "authStrategies": {
                "oidc": {
                    "issuer": "https://sso.your.domain",
                    "clientid": "2d5685c5-0f32-4c1f-9f09-c60e0dbc948a",
                    "clientsecret": "7PiGSLSLL4e7NGi67KM229tfK7Z7TqzQ",
                    "newAccounts": true
                }
            }
        }
    }
}

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.

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 https://mesh.your.domain/auth-oidc-callback 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.

WARNING: The redirect endpoint must EXACTLY match the value provided to your IdP or your will deny the connection.

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.

Advanced Options

Overview

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 node-openid-client on GitHub 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 config schema, and if you have a complicated config maybe check out the openid-client readme. 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.

Advanced Config File Example

{
    "settings": {
        "cert": "mesh.your.domain",
        "port": 443,
        "redirPort": 80,
        "AgentPong": 300,
        "TLSOffload": "192.168.1.50",
        "SelfUpdate": false,
        "AllowFraming": false,
        "sqlite3": true,
        "WebRTC": true
    },
    "domains": {
        "": {
            "title": "Mesh",
            "title2": ".Your.Domain",
            "orphanAgentUser": "~oidc:e48f8ef3-a9cb-4c84-b6d1-fb7d294e963c",
            "authStrategies": {
                "oidc": {
                    "issuer": {
                        "issuer": "https://sso.your.domain",
                        "authorization_endpoint": "https://auth.your.domain/auth-endpoint",
                        "token_endpoint": "https://tokens.sso.your.domain/token-endpoint",
                        "end_session_endpoint": "https://sso.your.domain/logout",
                        "jwks_uri": "https://sso.your.domain/jwks-uri"
                    },
                    "client": {
                        "client_id": "110d5612-0822-4449-a057-8a0dbe26eca5",
                        "client_secret": "4TqST46K53o3Z2Q88p39YwR6YwJb7Cka",
                        "redirect_uri": "https://mesh.your.domain/auth-oidc-callback",
                        "post_logout_redirect_uri": "https://mesh.your.domain/login",
                        "token_endpoint_auth_method": "client_secret_post",
                        "response_types": "code"
                    },
                    "custom": {
                        "scope": [ "openid", "profile", "read.EmailAlias", "read.UserProfile" ],
                        "preset": null
                    },
                    "groups": {
                        "recursive": true,
                        "required": ["Group1", "Group2"],
                        "siteadmin": ["GroupA", "GroupB"],
                        "revokeAdmin": true,
                        "sync": { 
                            "filter": ["Group1", "GroupB", "OtherGroup"]
                        },
                        "claim": "GroupClaim",
                        "scope": "read.GroupMemberships"
                    },
                    "logouturl": "https://sso.your.domain/logout?r=https://mesh.your.domain/login",
                    "newAccounts": true
                },
                {...}
            }
        }
    }
}

"Issuer" Options

Introduction

In the advanced example config above, did you notice that the issuer property has changed from a string to an object 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 ALL issuer information. Obviously if you manually configure an endpoint, it will be used even if the discovered information is different from your config.

NOTE: If you are using a preset, you dont need to define an issuer. If you do, the predefined information will be ignored.

Common Config Chart

Name	Description	Default	Example	Required
`issuer`	The primary URI that represents your Identity Providers authentication endpoints.	N/A	`"issuer": "https://sso.your.domain"` `"issuer": { "issuer": "https://sso.your.domain" }`	Unless using preset.

Advanced Config Example

"issuer": {
   "issuer": "https://sso.your.domain",
   "authorization_endpoint": "https://auth.your.domain/auth-endpoint",
   "token_endpoint": "https://tokens.sso.your.domain/token-endpoint",
   "end_session_endpoint": "https://sso.your.domain/logout",
   "jwks_uri": "https://sso.your.domain/jwks-uri"
},

Required and Commonly Used Configs

The issuer property in the issuer 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.

Schema

"issuer": { 
    "type": ["string","object"],
    "format": "uri",
    "description": "Issuer options. Requires issuer URI (issuer.issuer) to discover missing information unless using preset",
    "properties": {
        "issuer": { "type": "string", "format": "uri", "description": "URI of the issuer." },
        "authorization_endpoint": { "type": "string", "format": "uri" },
        "token_endpoint": { "type": "string", "format": "uri" },
        "jwks_uri": { "type": "string", "format": "uri" },
        "userinfo_endpoint": { "type": "string", "format": "uri" },
        "revocation_endpoint": { "type": "string", "format": "uri" },
        "introspection_endpoint": { "type": "string", "format": "uri" },
        "end_session_endpoint": {
            "type": "string",
            "format": "uri",
            "description": "URI to direct users to when logging out of MeshCentral.",
            "default": "this.issuer/logout"
            },
        "registration_endpoint": { "type": "string", "format": "uri" },
        "token_endpoint_auth_methods_supported": { "type": "string" },
        "token_endpoint_auth_signing_alg_values_supported": { "type": "string" },
        "introspection_endpoint_auth_methods_supported": { "type": "string" },
        "introspection_endpoint_auth_signing_alg_values_supported": { "type": "string" },
        "revocation_endpoint_auth_methods_supported": { "type": "string" },
        "revocation_endpoint_auth_signing_alg_values_supported": { "type": "string" },
        "request_object_signing_alg_values_supported": { "type": "string" },
        "mtls_endpoint_aliases": {
            "type":"object",
            "properties": {
                "token_endpoint": { "type": "string", "format": "uri" },
                "userinfo_endpoint": { "type": "string", "format": "uri" },
                "revocation_endpoint": { "type": "string", "format": "uri" },
                "introspection_endpoint": { "type": "string", "format": "uri" }
            }
        }
    },
    "additionalProperties": false
},

"Client" Options

Introduction

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.

NOTE: The client object is required, however an exception would be with using old configs, which will be discussed later.

Common Configs

Name	Description	Default	Example	Required
`client_id`	The client ID provided by your Identity Provider (IdP)	N/A	`bdd6aa4b-d2a2-4ceb-96d3-b3e23cd17678`	`true`
`client_secret`	The client secret provided by your Identity Provider (IdP)	N/A	`vUg82LJ322rp2bvdzuVRh3dPn3oVo29m`	`true`
`redirect_uri`	"URI your IdP sends you after successful authorization.	`https://mesh.your.domain/auth-oidc-callback`	`https://mesh.your.domain/oauth2/oidc/redirect`	`false`
`post_logout_redirect_uri`	URI for your IdP to send you after logging out of IdP via MeshCentral.	`https://mesh.your.domain/login`	`https://site.your.other.domain/login`	`false`

Advanced Config Example

"client": {
    "client_id": "00b3875c-8d82-4238-a8ef-25303fa7f9f2",
    "client_secret": "7PP453H577xbFDCqG8nYEJg8M3u8GT8F",
    "redirect_uri": "https://mesh.your.domain/auth-oidc-callback",
    "post_logout_redirect_uri": "https://mesh.your.domain/login",
    "token_endpoint_auth_method": "client_secret_post",
    "response_types": "code"
},

Required and Commonly Used Configs

There are many available options you can configure but most of them go unused. Although there are a few commonly used properties. The first two properties, client_id and client_secret are required. The next one redirect_uri is used to setup a custom URI for the redirect back to MeshCentral after being authenicated by your IdP. The post_logout_redirect_uri property is used to tell your IdP where to send you after being logged out. These work in conjunction with the issuers end_session_url to automatically fill in any blanks in the config.

Schema

"client": { 
    "type": "object",
    "description": "OIDC Client Options",
    "properties": {
        "client_id": { 
            "type": "string",
            "description": "REQUIRED: The client ID provided by your Identity Provider (IdP)"
        },
        "client_secret": {
            "type": "string",
            "description": "REQUIRED: The client secret provided by your Identity Provider (IdP)"
        },
        "redirect_uri": {
            "type": "string",
            "format": "uri",
            "description": "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)"
        },
        "post_logout_redirect_uri": {
            "type": "string",
            "format": "uri",
            "description": "URI for your IdP to send you after logging out of IdP via MeshCentral.",
            "default": "https:[currentHost][currentPath]/login"
        },
        "id_token_signed_response_alg": { "type": "string", "default": "RS256" },
        "id_token_encrypted_response_alg": { "type": "string" },
        "id_token_encrypted_response_enc": { "type": "string" },
        "userinfo_signed_response_alg": { "type": "string" },
        "userinfo_encrypted_response_alg": { "type": "string" },
        "userinfo_encrypted_response_enc": { "type": "string" },
        "response_types": { "type": ["string", "array"], "default": ["code"] },
        "default_max_age": { "type": "number" },
        "require_auth_time": { "type": "boolean", "default": false }, 
        "request_object_signing_alg": { "type": "string" },
        "request_object_encryption_alg": { "type": "string" },
        "request_object_encryption_enc": { "type": "string" },
        "token_endpoint_auth_method": {
            "type": "string",
            "default": "client_secret_basic",
            "enum": [ "none", "client_secret_basic", "client_secret_post", "client_secret_jwt", "private_key_jwt" ]
        }, 
        "introspection_endpoint_auth_method": {
            "type": "string",
            "default": "client_secret_basic",
            "enum": [ "none", "client_secret_basic", "client_secret_post", "client_secret_jwt", "private_key_jwt" ]
        }, 
        "revocation_endpoint_auth_method": {
            "type": "string",
            "default": "client_secret_basic",
            "enum": [ "none", "client_secret_basic", "client_secret_post", "client_secret_jwt", "private_key_jwt" ]
        }, 
        "token_endpoint_auth_signing_alg": { "type": "string" },
        "introspection_endpoint_auth_signing_alg": { "type": "string" },
        "revocation_endpoint_auth_signing_alg": { "type": "string" },
        "tls_client_certificate_bound_access_tokens": { "type": "boolean" }
    },
    "required": [ "client_id", "client_secret" ],
    "additionalProperties": false
},

"Custom" Options

Introduction

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 scope of the authorization request though, as well as choose which claims to use if your IdP uses something other than the defaults.

NOTE: The scope must be a string, an array of strings, or a space separated list of scopes as a single string.

Common Config Chart

Name	Description	Default	Example	Required
`scope`	A list of scopes to request from the issuer.	`"openid profile email"`	`["openid", "profile"]`	`false`
`claims`	A group of claims to use instead of the defaults	Defauts to name of property except that `uuid` used `sub`	`"claims": {"uuid": "unique_name"}`	`false`

Advanced Config Example

"custom": {
    "scope": [ "openid", "profile", "read.EmailAlias", "read.UserProfile" ],
    "preset": null,
    "claims": {
        "name": "nameOfUser",
        "email": "publicEmail"
    }
},

NOTE: You can preset to null if you want to explicitly disable presets.

Required and Commonly Used Configs

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 openid, profile, and email 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.

Schema

"custom": {
    "type": "object",
    "properties": {
        "scope": {
            "type": ["string", "array"],
            "description": "A list of scopes to request from the issuer.",
            "default": "openid profile email",
            "examples": ["openid", ["openid", "profile"], "openid profile email", "openid profile email groups"]
        },
        "claims": {
            "type": "object",
            "properties": {
                "email": { "type": "string" },
                "name": { "type": "string" },
                "uuid": { "type": "string" }
            }
        },
        "preset": { "type": "string", "enum": ["azure", "google"]},
        "tenant_id": { "type": "string", "description": "REQUIRED FOR AZURE PRESET: Tenantid for Azure"},
        "customer_id": { "type": "string", "description": "REQUIRED FOR GOOGLE PRESET IF USING GROUPS: Customer ID from Google, should start with 'C'."}
    },
    "additionalProperties": false
},

"Groups" Options

Introduction

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.

Common Config Chart

Name	Description	Default	Example	Required
`sync`	Allows you to mirror user groups from your IdP.	`false`	`"sync": { "filter": ["Group1", "Group2"] }` `"sync": true`	`false`
`required`	Access is only granted to users who are a member of at least one of the listed required groups.	`undefined`	`"required": ["Group1", "Group2"]`	`false`
`siteadmin`	Full site admin priviledges will be granted to users who are a member of at least one of the listed admin groups	`undefined`	`"siteadmin": ["Group1", "Group2"]`	`false`
`revokeAdmin`	If true, admin privileges will be revoked from users who arent a member of at least one of the listed admin groups.	`true`	`"revokeAdmin": false`	`false`

Advanced Config Example

"groups": {
    "recursive": true,
    "required": ["Group1", "Group2"],
    "siteadmin": ["GroupA", "GroupB"],
    "revokeAdmin": false,
    "sync": { 
        "filter": ["Group1", "GroupB", "OtherGroup"]
    },
    "claim": "GroupClaim",
    "scope": "read.GroupMemberships"
},

Required and Commonly Used Configs

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 scope or claim 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.

Schema

"groups": {
  "type": "object",
  "properties": {
    "recursive": {
      "type": "boolean",
      "default": false,
      "description": "When true, the group memberships will be scanned recursively."
    },
    "required": {
      "type": [ "string", "array" ],
      "description": "Access is only granted to users who are a member of at least one of the listed required groups."
    },
    "siteadmin": {
      "type": [ "string", "array" ],
      "description": "Full site admin priviledges will be granted to users who are a member of at least one of the listed admin groups."
    },
    "revokeAdmin": {
      "type": "boolean",
      "default": false,
      "description": "If true, admin privileges will be revoked from users who are NOT a member of at least one of the listed admin groups."
    },
    "sync": {
      "type": [ "boolean", "object" ],
      "default": false,
      "description": "If true, all groups found during user login are mirrored into MeshCentral user groups.",
      "properties": {
        "filter": {
          "type": [ "string", "array" ],
          "description": "Only groups listed here are mirrored into MeshCentral user groups."
        }
      }
    },
    "scope": { "type": "string", "default": "groups", "description": "Custom scope to use." },
    "claim": { "type": "string", "default": "groups", "description": "Custom claim to use." }
  },
  "additionalProperties": false
}

Preset OpenID Connect Configurations

Overview

Common Config Chart

NOTE: All settings directly related to presets are in the custom section of the config.

Name	Description	Example	Required
`preset`	Manually enable the use of a preset.	`"preset": "google"` `"preset": "azure"`	`false`
`customer_id`	Customer ID of the Google Workspaces instace you plan to use with the groups feature.	`"customer_id": ["Group1", "Group2"]`	If `google` preset is used with `groups` feature.
`tenant_id`	Tenant ID from Azure AD, this is required to use the `azure` preset as it is part of the issuer url.	`"tenant_id": "46a6022g-4h33-1451-h1rc-08102ga3b5e4"`	If `Azure` preset is being used.

Google Preset

Prerequisites

Check out this documentation to get ready before we start.

Basic Config Example

"oidc": {
    "client": {
        "client_id": "268438852161-r8xa7qxwf3rr0shp1xnpgmm70bnag21p.apps.googleusercontent.com",
        "client_secret": "ETFWBX-gFEaxfPXs1tWmAOkuWDFTgoL3nwh"
    }
}

Specifics

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.

Advanced Example with Groups

"oidc": {
    "client": {
        "client_id": "424555768625-k7ub3ovqs0yp7mfo0usvyyx51nfii61c.apps.googleusercontent.com",
        "client_secret": "QLBCQY-nRYmjnFWv3nKyHGmwQEGLokP6ldk"
    },
    "custom": {
        "preset": "google",
        "customer_id": "C46kyhmps"
    },
    "groups": {
        "siteadmin": ["GroupA", "GroupB"],
        "revokeAdmin": true,
        "sync": true
    },
    "callbackURL": "https://mesh.your.domain/auth-oidc-google-callback"
},

Customer ID and Groups

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 and 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.

Schema

"custom": {
    "type": "object",
    "properties": {
        "preset": { "type": "string", "enum": ["azure", "google"]},
        "customer_id": { "type": "string", "description": "Customer ID from Google, should start with 'C'."}
    },
    "additionalProperties": false
},

Azure Preset

Prerequisites

To configure OIDC-based SSO, you need an Azure account with an active subscription. Create an account 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.

Check this documentation for more information.

Basic Config Example

"oidc": {
    "client": {
        "client_id": "a1gkl04i-40g8-2h74-6v41-2jm2o2x0x27r",
        "client_secret": "AxT6U5K4QtcyS6gF48gndL7Ys22BL15BWJImuq1O"
    },
    "custom": {
        "preset": "azure",
        "tenant_id": "46a6022g-4h33-1451-h1rc-08102ga3b5e4"
    }
}

Specifics

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.

NOTE: The Azure AD preset uses the Tenant ID as part of the issuer URI:
"https://login.microsoftonline.com/" + strategy.custom.tenant_id + "/v2.0"

Advanced Example with Groups

"oidc": {
    "client": {
        "client_id": "a1gkl04i-40g8-2h74-6v41-2jm2o2x0x27r",
        "client_secret": "AxT6U5K4QtcyS6gF48gndL7Ys22BL15BWJImuq1O"
    },
    "custom": {
        "preset": "azure",
        "tenant_id": "46a6022g-4h33-1451-h1rc-08102ga3b5e4"
    },
    "groups": {
        "recursive": true,
        "siteadmin": ["GroupA", "GroupB"],
        "revokeAdmin": true,
        "sync": true
    },
    "callbackURL": "https://mesh.your.domain/auth-oidc-azure-callback"
},

Schema

"custom": {
    "type": "object",
    "properties": {
        "preset": { "type": "string", "enum": ["azure", "google"]},
        "tenant_id": { "type": "string", "description": "Tenant ID from Azure AD."}
    },
    "additionalProperties": false
},

Depreciated Properties

Overview

Introduction

As of MeshCentral v1.1.22 and the writing of this documentation, the node module that handles everything was changed from passport-openid-connect to openid-client. 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.

Migrating Old Configs

We upgraded but what about all the existing users, we couldn't just invalidate every config pre v1.1.22. 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.

Old Config Example

"oidc": {
    "newAccounts": true,
    "clientid": "421326444155-i1tt4bsmk3jm7dri6jldekl86rfpg07r.apps.googleusercontent.com",
    "clientsecret": "GNLXOL-kEDjufOCk6pIcTHtaHFOCgbT4hoi"
}

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 "google" to "oidc" is all that was done to the above config, besides obsfuscation of course.

Advcanced Old Config Example

"oidc": {
    "authorizationURL": "https://sso.your.domain/api/oidc/authorization",
    "callbackURL": "https://mesh.your.domain/oauth2/oidc/callback",
    "clientid": "tZiPTMDNuSaQPapAQJtwDXVnYjjhQybc",
    "clientsecret": "vrQWspJxdVAxEFJdrxvxeQwWkooVcqdU",
    "issuer": "https://sso.your.domain",
    "tokenURL": "https://sso.your.domain/api/oidc/token",
    "userInfoURL": "https://sso.your.domain/api/oidc/userinfo",
    "logoutURL": "https://sso.your.domain/logout?rd=https://mesh.your.domain/login",
    "groups": {
        "recursive": true,
        "required": ["Group1", "Group2"],
        "siteadmin": ["GroupA", "GroupB"],
        "sync": { 
            "filter": ["Group1", "GroupB", "OtherGroup"]
        }
    },
    "newAccounts": true
},

Upgrading to v1.1.22

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.

Links

https://cloud.google.com/identity/docs/reference/rest/v1/groups/list

https://www.onelogin.com/learn/authentication-vs-authorization

https://auth0.com/docs/authenticate/protocols/openid-connect-protocol

https://github.com/panva/node-openid-client

https://openid.net/connect/

You just read openidConnectStrategy.ms v1.0.1 by @mstrhakr

Submodules and Features

MeshCmd

Access the official MeshCmd user guide in your preferred format

📄 PDF version

📝 ODT version

🎬 Video Walkthru

🧾 Abstract

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.

📘 Introduction

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.

Broadly, the tool is intended to perform three sets of tasks :

MeshCentral2 command line operations

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.
Intel AMT local actions

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.
Intel AMT remote actions

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.

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: http://www.meshcommander.com/meshcommander/meshcmd

If you have access to a MeshCentral2 server, the download link to MeshCmd is at the bottom left of the main device page.

Once you click on the MeshCmd 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.

Once downloaded, just run it from the command prompt or terminal window.

C:\Temp>meshcmd
MeshCentral Command (MeshCmd)
No action specified, use MeshCmd like this:

  meshcmd [action] [arguments...]

Valid MeshCentral actions:
  Route             - Map a local TCP port to a remote computer.

Valid local actions:
  SMBios            - Display System Management BIOS tables for this computer.
  RawSMBios         - Display RAW System Management BIOS tables for this computer.
  MicroLMS          - Run MicroLMS, allowing local access to Intel AMT.
  AmtInfo           - Show Intel AMT version and activation state.
  AmtVersions       - Show all Intel ME version information.
  AmtHashes         - Show all Intel AMT trusted activation hashes.
  AmtCCM            - Activate Intel AMT into Client Control Mode.
  AmtACM            - Activate Intel AMT into Admin Control Mode.
  AmtDeactivate     - Deactivate Intel AMT if activated in Client Control mode.
  AmtAcmDeactivate  - Deactivate Intel AMT if activated in Admin Control mode.

Valid local or remote actions:
  MeshCommander     - Launch a local MeshCommander web server.
  AmtUUID           - Show Intel AMT unique identifier.
  AmtAuditLog       - Show the Intel AMT audit log.
  AmtLoadWebApp     - Load MeshCommander in Intel AMT 11.6+ firmware.
  AmtClearWebApp    - Clear everything from Intel AMT web storage.
  AmtStorageState   - Show contents of the Intel AMT web storage.
  AmtSaveState      - Save all Intel AMT WSMAN object to file.
  AmtPresence       - Heartbeat a local Intel AMT watchdog agent.
  AmtScript         - Run .mescript on Intel AMT.
  AmtIDER           - Mount local disk image to remote computer.

Help on a specific action using:

  meshcmd help [action]

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 help 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.

🔌 MeshCentral TCP port mapping

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.

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.

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.

One typical use of this is to route local port 1234 to port Microsoft RDP port 3389 on a remote device. Once routed, you can start a RDP session on localhost:1234 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.

To get started, click on a device in MeshCentral and click on the Router link on the bottom left of the device page.

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 :

{
 "action": "route",
 "localPort": 1234,              Change this
 "remoteName": "AmtMachine7",
 "remoteNodeId": "node//@yw$s5jLUivpzZ49laprt4T0sBaOKImbDAiniothQwccZPukCB696$BvPWAW0Bg2",
 "remotePort": 3389,                 Change this
 "username": "admin",
 "password": "",                 Note that the password is empty
 "serverId": "D99362D5ED8BAEA8BF9E743B34B242256370C460FD66CB62373C6CFCB204D6D70
7403E396CF0EF6DC2B3A42F735135FD",
 "serverHttpsHash": "D9DE9E27A229B5355708A3672FB23237CC994A680B3570D242A91E36B4AE5BC
96539E59746E2B71EEF3DBDABBF2AE138",
 "debugLevel": 0,
 "serverUrl": "wss://devbox.mesh.meshcentral.com:443/meshrelay.ashx"
}

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.

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 meshaction.txt file, you can also specify it as a meshcmd argument.

C:\MeshCmd>meshcmd --pass xxxxxxxx 
Redirecting local port 1234 to AmtMachine7:3389. Press ctrl-c to exit. 
Now, the traffic router is ready. You can now RDP to localhost:1234 and login to the remote computer.

🧭 MeshCommander

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:http://www.meshcommander.com/and also included as part of MeshCentral.

The three versions included in MeshCmd are :

MeshCommander as a local web server.
MeshCommander for LMS .
MeshCommander for firmware.

In this section, we review the three versions, how they are used and what can be done with them.

1. MeshCommander local web server

You can start MeshCommander on a local web server by typing meshcmd meshcommander. By default, local port 3000 is used, but you can optionally specify the port using --localport [port]. Running it with look like this:

C:\MeshCmd>meshcmd meshcommander
MeshCommander running on HTTP port 3000. Ctrl-C to exit.

Once running, use a web browser and go to http://localhost:3000 to see the MeshCommander web page. The page will start out without any computers in it and you will have to add some.

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 Open… and Save… buttons. This version of MeshCommander will have some limitations when compared to the full version installed using the Windows .MSI installer. Notably :

No certificate management or validation.
Mutual-Authenticated TLS is not supported.
Kerberos authentication is not supported.
IDE-R is not supported.

This said, features like KVM, Terminal and most Intel AMT configuration options are available which makes this a fairly powerful Intel AMT management console.

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:

C:\MeshCmd>meshcmd meshcommander install
Installing to "C:\Program Files (x86)\Open Source\MeshCmd\MeshCommander.exe" MeshCommander installed.

C:\MeshCmd>meshcmd meshcommander start
MeshCommander starting.

On Linux computers, both systemd and initd are supported. When installing, the MeshCmd executable will be copied to a different installation folder.

2. LMS & MeshCommander

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 16992 and 16993 to Intel AMT thru the MEI driver. One way to check if the LMS service is installed on your computer is to try http://localhost:16992 or https://localhost:16993 in a browser. A page should generally show up.

📌 Note :

On Windows, LMS is a Windows service that must be downloaded and installed as part of the OEM drivers for a computer.

On Linux, it’s generally never installed and users normally have to download the source code and compile it themselves.

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:

C:\MeshCmd>meshcmd microlms
MicroLMS started, MeshCommander on HTTP/16994.

This will start MicroLMS and as indicated, start MeshCommander on local port 16994 at the same time.

In total, traffic redirection looks like this :

In addition to providing normal services, MicroLMS that is part of MeshCmd will also start a web server on port 16994 and allow a browser to access LMS MeshCommander, a special version of MeshCommander specially made to run in this situation.

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.

Because it’s in this mode, you can use the web interface to de-activate Intel AMT or login to perform additional configuration.

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 --noconsole:

C:\MeshCmd>meshcmd microlms --noconsole
MicroLMS started.

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 :

C:\MeshCmd>meshcmd microlms install
Installing to "C:\Program Files (x86)\Open Source\MeshCmd\MicroLMS.exe" 
MicroLMS installed.

C:\MeshCmd>meshcmd microlms start
MicroLMS starting.

On Linux computers, both systemd and initd are supported. When installing, the MeshCmd executable will be copied to a different installation folder.

3. MeshCommander for firmware

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 16992 & 16993. 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.

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.

C:\MeshCmd>meshcmd amtloadwebapp --host 192.168.2.144 --pass xxxxxxxx
Uploading MeshCommander...
Verifying MeshCommander...
Done.

To get the current state of Intel AMT web storage, type this :

C:\MeshCmd>meshcmd amtstoragestate --host 192.168.2.144 --pass xxxxxxxx
Storage State: {
  "information": {
    "version": 1,
    "realms": 7765759,
    "user": "admin"
  },
  "content": {
    "index.htm": {
      "size": 57246      Replacement index.htm with size.
    }
  }
}

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:

C:\MeshCmd>meshcmd amtclearwebapp --host 192.168.2.144 --pass xxxxxxxx
Done.

When MeshCommander is loaded into Intel AMT, you can access it from a different computer using http://computername:16992 or https://computername:16993 You will need to authenticate first before getting access to the web page.

🔧 Intel AMT state & activation

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 SMBios action works on most computers and is used to get basic information about your current system. The output is JSON format.

C:\MeshCmd>meshcmd smbios
{
  processorInfo: {
    0: {
      Processor: "CPU"
      MaxSpeed: "3800 Mhz"
      Cores: 4
      Threads: 8
      Populated: 1
      Status: "Enabled"
      Socket: "CPU 1"
      Manufacturer: "Intel(R) Corporation"
      Version: "Intel(R) Core(TM) i7-3770 CPU @ 3.40GHz"
    }
  }
  memoryInfo: {
    location: "System Board"
    maxCapacityKb: 33554432
  }
  systemInfo: {
    uuid: "C57B83D9A94E11E18BA1505054503030"
    wakeReason: "Power Switch"
  }
  systemSlots: {
    uuid: "C57B83D9A94E11E18BA1505054503030"
    wakeReason: "Power Switch"
  }
  amtInfo: {
    AMT: true
    enabled: true
    storageRedirection: true
    serialOverLan: true
    kvm: true
    TXT: false
    VMX: true
    MEBX: "66.0.0.8"
    ManagementEngine: "8.1.0.57353"
  }
}

If you have Intel AMT on your system, you can use the amtinfo, amtversions and amthashes 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 :

meshcmd amtinfo

C:\MeshCmd>meshcmd amtinfo
Intel AMT v8.1.71, activated in client control mode.
Wired Enabled, DHCP, 00:1E:8C:F5:4F:ED, 192.168.2.10.

meshcmd amtversions

C:\MeshCmd>meshcmd amtversions
MEI Version = MKQ7710H.86A.0072.2017.0519.1347
Flash = 8.1.71
Netstack = 8.1.71
AMTApps = 8.1.71
AMT = 8.1.71
Sku = 24584
VendorID = 8086
Build Number = 3608
Recovery Version = 8.1.71
Recovery Build Num = 3608
Legacy Mode = False

meshcmd amthashes

C:\MeshCmd>meshcmd amthashes
VeriSign Class 3 Primary CA-G1, (Default, Active)
  SHA256: E7685634EFACF69ACE939A6B255B7B4FABEF42935B50A265ACB5CB6027E44E70
VeriSign Class 3 Primary CA-G3, (Default, Active)
  SHA256: EB04CF5EB1F39AFA762F2BB120F296CBA520C1B97DB1589565B81CB9A17B7244
…

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 amtccm and amtdeactivate actions.

meshcmd amtinfo

C:\MeshCmd>meshcmd amtinfo
Intel AMT v8.1.71, pre-provisioning state.

meshcmd amtccm --pass xxxxxxxx

C:\MeshCmd>meshcmd amtccm --pass xxxxxxxx
Success

meshcmd amtinfo

C:\MeshCmd>meshcmd amtinfo
Intel AMT v8.1.71, activated in client control mode.

meshcmd amtdeactivate

C:\MeshCmd>meshcmd amtdeactivate
Success

📌 Note :

Note that when using the amtccm 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.

📋 Intel AMT Audit Log

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.

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.

C:\MeshCmd>meshcmd amtauditlog
2004-01-01 19:17:58.000-08:00 - Local: Provisioning Started
2018-01-26 14:03:16.000-08:00 - Local: Unprovisioning Started
2018-01-26 14:03:31.000-08:00 - Local: Provisioning Started
2018-02-01 12:13:14.000-08:00 - admin: KVM Enabled
2018-02-01 12:16:01.000-08:00 - admin: KVM Session Started
2018-02-01 12:16:07.000-08:00 - admin: KVM Session Ended
2018-02-02 10:56:06.000-08:00 - admin: KVM Session Started
2018-02-02 10:56:08.000-08:00 - admin: KVM Session Ended

To get a remote audit log :

C:\MeshCmd>meshcmd amtauditlog --host 192.168.2.144 --user admin --pass xxxxxxxx
2003-12-31 23:06:58.000-08:00 - $$OsAdmin: Intel(r) ME Time Set
2017-08-15 06:53:31.000-07:00 - $$OsAdmin: Intel(r) ME Time Set
2017-10-13 17:55:11.000-07:00 - Local: Provisioning Started
2017-10-13 17:55:54.000-07:00 - Local: Opt-In Policy Change
2017-10-15 06:44:38.000-07:00 - admin: KVM Enabled

You can also save the audit log to file using the --output option.

💻 Running Intel AMT script

MeshCmd has a full WSMAN stack built-in and can be used to run .mescript 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.

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.

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 Add CIRA link for meshes that are Intel AMT only (no agent).

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.

C:\MeshCmd>meshcmd amtscript --host 192.168.2.106 --pass xxxxxxxx --script cira_setup.mescript
Script Started
Policies removed successfully
Adding root certificate...
Management Presence Server (MPS) successfully added
Found matching (primary) mps: Intel(r) AMT:Management Presence Server 0
Setting policy...
Policy added successfully
Remote Access user interfaces set to: BIOS & OS Enabed
Parsing block parameters
Setting Environment Detection
Environment Detection set successfully
Script Completed

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.

➡️ IDE Redirection

🎬 Video Walkthru

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.

Then use the AmtIDER command of MeshCMD to start an IDER session. The help command for AmtIDER looks like this:

C:\Temp>meshcmd help amtider
AmtIDER will mount a local disk images to a remote Intel AMT computer. Example usage:

  meshcmd amtider --host 1.2.3.4 --user admin --pass mypassword --tls --floppy disk.img --cdrom disk.iso

Possible arguments:

  --host [hostname]      The IP address or DNS name of Intel AMT.
  --user [username]      The Intel AMT login username, admin is default.
  --pass [password]      The Intel AMT login password.
  --tls                  Specifies that TLS must be used.
  --floppy [file]        Specifies .img file to be mounted as a flppy disk.
  --cdrom [file]         Specifies .img file to be mounted as a CDROM disk.
  --timeout [seconds]    Optional, disconnect after number of seconds without disk read.

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.

🏁 Conclusion

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.

License

MeshCmd and this document are both opens source and licensed using Apache 2.0, the full license can be found at https://www.apache.org/licenses/LICENSE-2.0

MeshCtrl

MeshCmd Guide as .pdf as .odt

Video Walkthru

Abstract

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.

Introduction

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.

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.

Running MeshCtrl

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:

node ./node\_modules/meshcentral/meshctrl

In this case, when the above command is run without parameters, you should see something like this:

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.

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.

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.

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.

This is the easiest way to login and start issuing commands is to login using a username and password.

You do this by using the "loginuser" and "loginpass" argument like this:

node ./node_modules/meshcentral/meshctrl serverinfo --loginuser "admin" --loginpass "mypassword"

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:

Authentication token required, use --token [number].

In this case, you need to use the Google Authenticator application or a similar application to enter your time based second factor like this:

node ./node_modules/meshcentral/meshctrl serverinfo --loginpass "mypassword" –token 123456

Once the command is run successfully, you should see a response like this:

name: devbox.meshcentral.com
mpsname: devbox.meshcentral.com
mpsport: 4433
port: 443
emailcheck: true
domainauth: false
tlshash: E7A41E1A56D8D716F7D7729B876E48693F2D19C4761F22B1…
https: true
redirport: 80

This is a typical response for the “serverinfo” command and a good way to test that everything is working as expected.

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.

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:

{
  "settings": {
    "Port": 443,
    "AllowLoginToken": true
  }
}

Then run the MeshCentral server with the --logintokenkey parameter, you should see something like this:

node ./node_modules/meshcentral --logintokenkey
f3bd69a08a2dde4a3423bec8f20d8626b1e6365381f2d9919e7dfe256ace9cbbdea66bed2bdcd00b71eea9d7c727cb6eb37f3148c0c2d240d5ed44c8f3f6795a479c949159dad366571fea4db7f31c24

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:

node ./node_modules/meshcentral –logintokenkey > key.txt

Now that you have the server key, you can use MeshCtrl like this:

node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt --loginuser admin

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:

node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt

Like the username and password example above, the result will be the server information we requested. Something like this:

name: devbox.meshcentral.com
mpsname: devbox.meshcentral.com
mpsport: 4433
port: 443
emailcheck: true
domainauth: false
tlshash: E7A41E1A56D8D716F7D7729B876E48693F2D19C4761F22B1…
https: true
redirport: 80

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.

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:

node ./node_modules/meshcentral/meshctrl serverinfo --url wss://server/domainname --loginuser "admin" --loginpass "mypassword"

or for servers have a DNS name for a domain:

node ./node_modules/meshcentral/meshctrl serverinfo --url wss://domainname.server --loginuser "admin" --loginpass "mypassword"

Note the "--url" argument is different and so, the server will see MeshCtrl access the server using a different domain.

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:

node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt --url wss://server/domainname --domain mycustomer

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:

{
  "settings": {
    "Cert": "myserver.com",
    "Port": 443
  },
  "domains": {
    "": {
      "title": "Default domain",
    },
    "customer1": {
      "dns": "c1.myserver.com",
      "title": "Customer1 domain",
    }
  }
}

The domain login for MeshCtrl with a key file would look like this:

node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt --url wss://c1.myserver.com --domain customer1

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.

Making use of MeshCtrl

We can start doing useful operations with MeshCtrl. The current list of operations are:

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

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]”

example

Note

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".

Gathering information

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:

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"

In the --json argument is used, it looks like this:

node meshctrl.js listusers --json
  {
    "_id": "user//admin",
    "name": "admin",
    "creation": 1417814230,
    "siteadmin": 4294967295,
    …

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:

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

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:

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

You can also add “--count" to just return the number of devices instead of displaying them. An example of this would be:

node meshctrl listdevices --id 7b4b43cdad850135f36ab31124b52e47c167fba055… --count
13

Here we see that in a specific device group, there are 13 devices.

Adding and removing accounts

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.

With MeshCtrl the same process can be accomplished using the following command line:

node ./node_modules/meshcentral/meshctrl adduser --user SampleUser --pass SamplePassword

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:

--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.

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.

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.

To remove a user account, use the following command:

node ./node_modules/meshcentral/meshctrl removeuser --userid SampleId

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.

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.

Creating and removing device groups

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.

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:

node ./node_modules/meshcentral/meshctrl adddevicegroup --name "Sample group name" --desc "Sample description"

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.

You can delete a group by using the “RemoveDeviceGroup” command like this:

node ./node_modules/meshcentral/meshctrl removedevicegroup --id 7b4b43cd…dc89fe0e581c

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.

Adding and removing users from device groups

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.

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:

node ./node_modules/meshcentral/meshctrl addusertodevicegroup --id 7b4b43cd…dc89fe0e581c --userid bob --fullrights

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:

  --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.

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.

To remove a user from a group, use the “removeuserfromdevicegroup” command. For example:

node ./node_modules/meshcentral/meshctrl removeuserfromdevicegroup --id 7b4b43cd…dc89fe0e581c --userid bob

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.

Message Broadcast

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:

node ./node\_modules/meshcentral/meshctrl broadcast --msg "This is a test"

All connected users will see this:

The broadcast command is great for notifying users of upcoming server downtime or other events.

Conclusion

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.

License

MeshCtrl and this document are both opens source and licensed using Apache 2.0, the full license can be found at https://www.apache.org/licenses/LICENSE-2.0

MeshCentral Router

MeshCentral Router Guide as .pdf as .odt

Video Walkthru

Abstract

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.

Introduction

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.

Downloading

MeshCentral router is a Windows application that comes built-into the MeshCentral server or can be downloaded at: https://meshcentral.com/tools/MeshCentralRouter.exe

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:

Download

The router link will only show up on Windows browsers.

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.

Login

If the second factor authentication is required, MeshCentral Router does not support hardware keys (WebAuthn), but does support the YubiKey™ OTP.

Creating Port Maps

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.

port_maps

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.

port_maps

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.

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.

Custom Apps

Starting v1.0.21

Command Line Arguments

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.

-debug

Causes MeshCentral Router to generate a “debug.log” dump file that can be useful for debugging.

-host:<hostname>
-user:<username>
-pass:<password>
-ignorecert

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.

-map:<protocol>:<localport>:<computername>:<app>:<remoteport>

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:

-map:TCP:0:"MyComputer":HTTP:80
-map:UDP:1235:"MyComputer"::1234

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.

In addition to port mapping, you can also setup relay maps where a remote computer is used as a traffic relay like this:

-relaymap:<protocol>:<localport>:<computername>
 :<app>:<remoteip>:<remoteport>

This will relays a local port to thru the server and thru a remote agent to a target IP address and port. For example:

-relaymap:TCP:555:"MyComputer":HTTP:192.168.1.1:80

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.

-all

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.

-tray

The “tray” switch will place MeshCentral Router on the Windows system tray instead of the normal application bar.

MeshCentral Router with SAML or OAuth

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

Download MCR and run it.
In the first dialog box, there will be an "Install..." button to setup MeshCentral router with the "mcrouter://" protocol in your system registry.
Once done, close MCR.
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".
This will launch the router and connect directly to your server using a login cookie.

Note

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.

Conclusion

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.

License

MeshCentral, MeshCentral Router and this document are all opens source and licensed using Apache 2.0, the full license can be found at https://www.apache.org/licenses/LICENSE-2.0.

Intel AMT

Intel AMT Guide as .odt

Video Walkthru

Abstract

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.

History of AMT

Introduction

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.

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.

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”

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.

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:

Mesh Agent

Fast remote desktop / clipboard access.
Remote access to operating system files.
Remote chat and other OS features.

Intel® AMT

Remote desktop even when the agent or operating system is not functional.
Remote access to BIOS.
Connectivity when soft-off / sleeping.
Remote power actions.

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.

Bare-Metal Activation Server

The AmtProvisioningServer section in the settings 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.

This bare-metal activation server is not enabled by default and only makes sense when activating devices on the local network.

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.

baremetal

MeshCentral Group Types

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.

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.

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.

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.

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.

Client Initiated Remote Access & MPS server

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.

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.

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.

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:

https://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide/HTMLDocuments/MPSDocuments/Intel%20AMT%20Port%20Forwarding%20Protocol%20Reference%20Manual.pdf

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.

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.

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.

The CIRA protocol is binary, but MeshCentral will detect that the request is made from a browser and return a short message:

MeshCentral2 MPS server.
Intel® AMT computers should connect here.

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.

Activation Certificate Setup

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.

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.

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:

{
  "settings": {
    "Cert": "devbox.mesh.meshcentral.com",
  },
  "domains": {
    "": {
      "title": "My Server",
      "AmtAcmActivation": {
        "log": "amtactivation.log",
        "certs": {
          "myamtcert": {
            "certpfx": "amtcert.pfx",
            "certpfxpass": "pfxpassword"
          }
        }
      }
    }
}

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:

{
  "settings": {
    "Cert": "devbox.mesh.meshcentral.com",
  },
  "domains": {
    "": {
      "title": "My Server",
      "AmtAcmActivation": {
        "log": "amtactivation.log",
        "certs": {
          "myvprocert": {
            "certfiles": [ "amtacm-vprodemo.crt",
   "amtacm-intermediate1.crt",
   "amtacm-intermediate2.crt",
   "amtacm-root.crt" ],
            "keyfile": "amtacm-vprodemo.key"
          }
        }
      }
    }
}

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.

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.

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.

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.

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:

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”.
The name “meshcentral.com” by have been set as “Trusted FQDN” in MEBx.
The name “meshcentral.com” must have been set using a USB key with a setup.bin file.

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.

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.

Note

Activation over wifi has some additional issues.
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.
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 Open AMT Cloud Toolkit 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.

Intel AMT MEI and LMS

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

Intel AMT System Defense

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.

Contribute to MeshCentral

📤 Contributing to MeshCentral via GitHub Pull Request

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 :

Fork the Repository :

Start by forking the MeshCentral repository on GitHub.

This creates a copy of the repository under your own GitHub account, allowing you to make changes without affecting the original project.
Make Your Changes
- In your forked repository, create a new branch to keep your changes organized. This helps in managing different contributions separately.
- Make the necessary changes in your repository. This could involve updating documentation files or modifying code to add new features or fix bugs.
Review Your Changes :

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.
Submit a Pull Request
- Once your changes are ready and reviewed, submit a pull request (PR) from your branch to the master branch of the main MeshCentral repository.
- 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.
Wait for Review :

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.
Respond to Feedback :

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.
Final Steps :

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!

🗣️ Contribute to MeshCentral's Multilingual Support

To make MeshCentral multilingual, your contributions are crucial. Follow these steps to translate the interface into various languages.

Remove Local Translations :

Delete translate.json from your meshcentral-data folder. This file contains your local copy of translations, which may become outdated as new features and texts are added.
Access MeshCentral :

Ensure you are logged into MeshCentral.
Open Translation Tool:

Visit https://YOURMESHCENTRALSERVER.COM/translator.htm to access the translation interface.
Choose a Language :

Select the language you wish to translate from the list provided.
Translate Text :

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.
Enter Translations :

For each text segment, enter your translation in the bottom box (not the top one) and click SET (F1).
Repeat Translation : Continue translating by repeating steps 5 and 6 for other texts as desired.
Save and Apply Translations
- Click SAVE TO SERVER (F3) to save your translations to meshcentral-data/translate.json locally in your MeshCentral server.
- Optionally, click SAVE TO FILE (F4) to download the translate.json file for offline review or sharing.
Deploy Translations :

Click TRANSLATE SERVER 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.
Finalize Changes :

It’s crucial to restart MeshCentral to ensure that the translated files are picked up correctly.
Share your translations :

Once a language translation is complete, take the latest translation.json and share it by emailing it to the maintainer (Ylianst, ylianst@gmail.com) or by submitting it to the MeshCentral GitHub repository via a pull request.

Note

Additional Information :

If you make any changes to default.handlebars, run the translate server to propagate these modifications to the language-specific handlebar files located in node_modules/meshcentral/views/translations.

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.

Design and Architecture

🎬 Video Walkthru

🧾 Abstract

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.

📌 Note :

The software and added documentation and tutorial videos are available at : https://www.meshcommander.com/meshcentral2

📘 Introduction

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.

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.

🎯 Goals & Requirements

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.

Additionally, there are many other goals :

Must be quick and easy to install.

Must install on all major operating systems and platforms.

Can be deployed on small computers and the cloud.

Can be deployed within containers.

Can be deployed in many network environments.

Must support both software agent and Intel® AMT hardware agent.

Must only use open source dependencies.

Must provide all basic remote management features (desktop, terminal, files…)

Must use the network efficiently.

Must have a real time user interface.

Must be easy to use.

Must be fast.

Etc.

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.

🖥️ Design Overview

In this section, we do a very high level overview of MeshCentral’s design. MeshCentral has 3 big components :

The server,
The agent and
The web application.

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.

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.

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.

This is probably a good time to introduce DukTape (https://www.duktape.org/). 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.

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.

🗄️ MeshCentral server

The MeshCentral server is a NodeJS application that is published on NPM at : https://www.npmjs.com/package/meshcentral Many administrators can get started quickly using “npm install meshcentral” once NodeJS is installed. MeshCentral will work on Node 6.x and higher.

📦 Dependencies

The server makes use of the following dependencies on NPM. These are all automatically installed by NPM when installing MeshCentral.

Can be found in the file : MeshCentralServer.njsproj

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 :

node-windows

greenlock, le-store-certbot, le-challenge-fs :

Installed on all Windows install. Allows background service install:
le-acme-core :

Installed only when Let’s Encrypt must be used:
mongojs :

Installed when MongoDB is in used.
nodemailer :

Installed when SMTP server support is in used.

MeshCentral will run npm install automatically when any of these optional modules are needed but not currently available.

🎬 Understanding the different modes: LAN, WAN and Hybrid

📁 Code files and folders

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.

Folders

agents: Compiled agents, install scripts, tools and agent JavaScript.

public: Static web elements such as images, CSS, HTML and more.

views: Main web application, login screen and messenger app.

Configuration & text files

package.json: Description of the MeshCentral package on NPM.

sample-config.json: A sample “config.json” file to get started.

readme.txt: Readme file published with the MeshCentral package.

Code files

 amtevents.js             | Used to decode Intel AMT WSMAN events.
 amtmanager.js            | Used to handle Intel AMT/CIRA things.
 amtprovisioningserver.js | Used to Provision Intel AMT on a Local Network.
 amtscanner.js            | Used to scan a local network for Intel AMT machines.    
 amtscript.js             | Used to run Intel AMT scripts from MeshCommander.       
 certoperations.js        | Used to generate and perform certificate operations.    
 common.js                | Various commonly used methods.
 crowdsec.js              | Used to handle all crowdsec security features                     
 db.js                    | Used to access the MongoDB or NeDB database.            
 exeHandler.js            | Used to modify windows executables.
 firebase.js              | Used to handle Google Firebase things.
 interceptor.js           | Used to insert credentials in an HTTP stream.           
 letsencrypt.js           | Used to obtain and use a Let’s Encrypt certificate.
 mcrec.js                 | Standalone Session Recording Indexer.
 meshaccelerator.js       | Used to offload RSA sign to other CPU cores.            
 meshagent.js             | Used to communicate to agents.
 meshbot.js               | Sample bot to connect to meshcentral and preform various tasks                     
 meshcentral.js           | The is the main module, gets the server started.
 meshctrl.js              | MeshCtrl performs command line actions on a MeshCentral server.
 meshcore.js              | Main Agent Code that runs on your remote devices.
 meshdesktopmultiplex.js  | Used to handle remote desktop multiplexing.
 meshdevicefile.js        | Used to handle file download requests.
 meshipkvm.js             | Used to handle IP KVM integration
 meshmail.js              | Used to send SMTP mails.
 meshmessaging.js         | Used to handle all users messaging methods like 2FA.
 meshrelay.js             | Used to relay agent and browser web socket connections. 
 meshscanner.js           | MeshCentral server discovery when in LAN mode.
 meshsms.js               | Used to handle all users sms methods.
 meshuser.js              | Used to communicate with browsers.                      
 mpsserver.js             | Used to communicate to Intel® AMT CIRA.
 mqttbroker.js            | Used to create/handle an MQTT broker (beta)               
 multiserver.js           | Used for server-to-server communication.                
 pass.js                  | Performs password hash + salt.                          
 redirserver.js           | Used to handle HTTP traffic.                            
 swarmserver.js           | Used to upgrade legacy MeshCentralv1 agents. 
 webauthn.js              | Handles all WebAuthN things.
 webrelayserver.js        | Used for all HTTP/HTTPS web relaying from agents.          
 webserver.js             | Handles HTTPS traffic.                                  
 winservice.js            | Server background install on Windows.

At a high level, the MeshCentral.js file will get the server started.

By default, it will start :

webserver.js on port 443,
redirectserver.js on port 80 and
mpssrver.js on port 4433.

The webserver.js file will create a meshuser.js or meshagent.js instance each time a user or agent connects. The other files support various usages, but this is the basic working on the server.

Server database

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.

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.

🔐 Certificates

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.

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.

Server Certificates

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 meshcentral-data folder. The four certificates are:

Server root

root-cert-public.crt

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 4433, 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 --fastcert is used, in that case a RSA2048 certificate is generated.

MPS certificate

mpsserver-cert-public.crt

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.

Web certificate

webserver-cert-public.crt

This is the default certificate used to secure the HTTPS port 443. 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 --fastcert is used, in that case a RSA2048 certificate is generated. In production environments, this certificate is replaced with a real certificate.

There are many ways to change this certificate for a more appropriate certificate in production environments :

You can replace the webserver-cert-\* files in the meshcentral-data folder.
You can use Let’s Encrypt which will override this certificate automatically.
You can use a reverse-proxy in front of the server with --tlsoffload.

Agent certificate

agentserver-cert-public.crt

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 --fastcert is used, in that case a RSA2048 certificate is generated.

The meshcentral-data folder contains critical server information including private keys therefore, it’s important that it be well protected. It’s important to backup the meshcentral-data 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.

If someone re-installs a server, placing the meshcentral-data folder back with these certificates should allow the server to resume normal operations and accept connections for Intel AMT and agents as before.

Agent Certificates

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.

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.

Agent root certificate

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.

Secondary certificate

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.

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 meshagent.db file and to not give important information to untrusted agents.

🔒 TLS Security

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.

Probably the most important TLS configuration is for the MeshCentral server ports 443 and 4433. These two ports are exposed to the Internet and so, should be setup as securely as possible.

MeshCentral HTTPS port 443

The HTTPS port on the MeshCentral server will only support TLS 1.2 and above, and makes use of only 6 cypher suites:

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)

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, https://ssllabs.com gives the server an A rating with no known vulnerabilities and no weak ciphers detected.

SSL Labs confirms that all major browsers should be able to connect correctly to this server.

MeshCentral MPS port 4433

The Manageability Presence Server (MPS) port 4433 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 4433 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.

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.

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:

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)

The suites starting with TLS\_RSA\_ 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.

🛰️ Agent to server handshake

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

The server and agent signatures are computed like this :

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.

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.

🌍 Browser to agent relay and WebRTC

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.

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.

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 c 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.

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.

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.

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.

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.

To perform the switch-over, both browser and agent will exchange WebRTC control messages over the newly established web socket relay session.

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.

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.

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.

💬 Messenger

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 :

User-to-user and
user-to-computer communication.

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.

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 c 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.

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.

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.

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.

💡 Additional Resources

In addition to this document, there are a growing set of MeshCentral resources at :

https://www.meshcommander.com/meshcentral2. :

This includes an Installer’s documents, a User’s Guide and plenty of YouTube tutorial videos.

For developers, it’s best to start on the MeshCentral GitHub repository at :

https://github.com/Ylianst/MeshCentral

If any issues are found, it’s best to create a new issue in GitHub or mail ylianst@gmail.com

🏁 Conclusion

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.

License

MeshCentral and this document are both opens source and licensed using Apache 2.0, the full license can be found at https://www.apache.org/licenses/LICENSE-2.0

PDF and ODT handout(s).

MeshCentral Guide

MeshCmd Guide as .pdf as .odt

Other

ADFS SSO Guide

📋 Assumptions

The following guide was built under the assumptions that :

ADFS 4.0 running on Server 2016 using Active Directory
Main ADFS setup already completed / working. SSL certs installed and port forwarded as expected.

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.

📘 Guide

As with anything SSO, you need 2 pieces – the IDP setup (in this case ADFS) and the SP setup (in this case Mesh).

Mesh Setup

Add the following to your mesh config file in the domains part :

Callback URL :

Should be the FQDN for your Mesh Server, ending with /auth-saml-callback
Entity ID :

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.
IDP URL:

This is the URL to ADFS. Ends with /adfs/ls unless you did something very weird in ADFS.
Cert:
You will need to export the token signing cert from ADFS, then convert it to PEM format. This cert can be found in ADFS -> Service -> Certificates. You can use this openssl command to convert it from CRT to PEM format :
```
openssl x509 -in mycert.crt -out mycert.pem -outform PEM
```

Save the config and restart the mesh server.

Windows Server Configuration

ADFS setup (in pictures) :

Relying Party Trust -> New Relying Party Trust

Edit the new “Relying Party Trust” Properties:

Then it’s time to add Claims…

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.

Add another rule:

For all fields, select from the dropdowns

MeshCentral Satellite

🚀 Coming Soon!

🧾 Abstract

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.

📘 Introduction

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.

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.

Currently, MeshCentral Satellite can perform four operations on behalf of the MeshCentral server :

Create an Intel AMT domain computer.
Remove an Intel AMT domain computer.
Issue a certificate for Intel AMT.
Revoke an Intel AMT certificate.

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.

🧰 Installation and Configuration

Start by creating an empty folder on a computer that is part of the domain you need to interact with. For example, create a c:\MeshCentralSatellite then copy MeshCentralSatellite.exe into that folder. You can find that executable in the node_modules/meshcentral/agents folder of your server. If it’s not present, update your server to the latest version and look again.

Once started you should see something this:

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.

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.

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.

The Device Name has two options, Operating System Name or Node Identifier. If you opt for Operating System Name, Intel AMT devices will show as, for example, iME-ComputerName in the list of domain computers. If node identifier is used, Intel AMT devices will look like iME-xxxxxxxxxxx where xxx is the start of the MeshCentral node identifier for this device.

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.

The security groups section will list any security groups created until the Computers section of the domain controller. Checking one or more of these security groups will automatically going new Intel AMT devices to these groups.

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 <computername>\<caname> you can then hit the check box next to the name and select the certificate template to use.

For certificate configuration, you can leave it as-is with SAM Account Name and the common name and all alternative names selected.

Once done, you can hit ok. The settings will be saved in a file called config.txt in plain text in the same folder as MeshCentralSatellite.exe. 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.

Once done, select Local Connect the Files menu to connect to the MeshCentral server.

MeshCentral Satellite should be connected and ready to receive commands from the server.

✅ Checking the connection

In order to make sure the server correctly recognizes the MeshCentral Satellite connection, you can go to the server console and type usersession. The Satellite session should be marked.

Currently, you should only have a single satellite session per user. In the future, multiple sessions could be supported for redundancy.

🔧 Configuring Intel® AMT 802.1x

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.

Here is an example of an 802.1x EAP-TLS profile that will require that Intel AMT be issued a certificate :

      "AmtManager": {
        "802.1x": {
          "AuthenticationProtocol": "EAP-TLS",
          "SatelliteCredentials": "admin"
        },
        "WifiProfiles": [
          {
            "ssid": "Network-8021x",
            "authentication": "wpa2-802.1x",
            "encryption": "ccmp-aes"
          }
        ]
      }

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:

      "AmtManager": {
        "802.1x": {
          "AuthenticationProtocol": "PEAPv0/EAP-MSCHAPv2",
          "SatelliteCredentials": "admin"
        },
        "WifiProfiles": [
          {
            "ssid": "Network-8021x",
            "authentication": "wpa2-802.1x",
            "encryption": "ccmp-aes"
          }
        ]
      }

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 wpa2-802.1x and so, the 802.1x profile will be setup for both the Intel AMT wired interface and the specified WIFI profile for wireless.

Note that is both examples, SatelliteCredentials indicates the account name that MeshCentral Satellite will be connected on. In our case, we used the admin account that matches the account configuration we used in sections 3 and 4.

Make these changes to the config.json and restart the MeshCentral server. Once done, any device groups that are set to configure Intel AMT will generate operations for MeshCentral Satellite.

🧾 Computer and certificate operations

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.

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 amtconfig to force the check of the Intel AMT configuration. In our case, it looks like this :

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:

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:

The new Intel AMT device was added to the domain along with the Intel AMT version and node identifier in the description. If Node Identifier 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.

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 :

Note that there is no 802.1x profiles or WIFI profiles. After the new configuration, MeshCommander shows Intel AMT looking like this :

There are now two new certificates in the Security 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.

🖥️ Running as a Background Service

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 Service 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.

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 Log On account to one with the proper rights.

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.

The lines starting with Service: are coming from the background service. At this point, you can close the local application and the service will keep running in the background.

License

MeshCentral, MeshCentral Satellite and this document are both opens source and licensed using Apache 2.0, the full license can be found at Apache License 2.0.

Home

MeshCentral Documentation

About

🌐 Social Media

📚 Documentation

📺 Video Tutorials

💬 Feedback

Install

Installation

🧾 Abstract

Quickstart

🚀 Quick Start Guide: Basic NPM Installation

🛠️ Basic Setup

1. Install Node.js

2. Install and Start MeshCentral

Running as a Service

⚙️ Configuration and Customization

Default Mode and Initial Access

Advanced Configuration

Database and Scaling Notes

Installation Guides

Installation

🧾 Abstract

📦 NPM Installation for Advanced Users

Prerequisites and Verification

1. Verify Node.js and NPM

2. Configure Proxy Settings (If Applicable)

MeshCentral Installation

3. Install MeshCentral

4. Start the Server

5. Configure for WAN/Internet Access (Optional)

🐳 Container (OCI-specification).

🏷️ Basic Tags:

All Tags

🐋 Docker/Podman

Pulling the image:

Docker CLI:

Docker Compose:

☸️ Kubernetes

📚 Extra sources

Quickstart

🪟 Quick Start on Windows with the Installer

Installation Prompts Explained

Updating and Maintenance

🔒 Windows Defender Firewall Settings

Accessing Firewall Settings

1. Editing Existing Rules

2. Adding New Rules

Databases

This section will go into how to configure MongoDB as a database backend.

MeshCentral Cheatsheet:

This section will go into how to configure PostgreSQL as a database backend.

MeshCentral Cheatsheet:

Postgres Cheatsheet

This section will go into how to configure MySQL/MariaDB as a database backend.

MeshCentral Cheatsheet:

MariaDB/MySQL Cheatsheet:

This section will go into how to configure a local database as backend.

MeshCentral Cheatsheet:

Security

🛡️ Crowdsec

🎬 Video Walkthru

Secure

🔒 Increased Security Installation on Debian/Ubuntu

1. Create a Low-Privilege User

2. Install MeshCentral

3. Initialize Data Folders

4. Restrict Permissions

5. Adjust Write Permissions for Functionality (Optional)

A. File Upload/Download

B. Let's Encrypt Support

6. Manual Server Update

MeshCentral

MeshCentral Guide

🧾 Abstract

📘 Introduction

🎬 Video Walkthru

🖥️ Server Installation

🚀 Basic Usage

Launch